Plans

A Plan is a comprehensive billing aggregator that brings together multiple components of the insurance premium collection process. Rather than being an invoice itself, a Plan contains and orchestrates:

Invoice: The billing document sent to the insured with premium details
Payment Link: A secure checkout URL for collecting payment
Flow-of-Funds: The routing configuration determining how collected funds are distributed between the agency, carrier, and producer
Policies: One or more insurance policies being billed
Payment Tracking: Status and history of payments received against the plan

This aggregated structure allows you to manage the entire billing lifecycle through a single resource, from invoice generation through payment collection and fund distribution.

Pre-Requirements for Plan Creation

Before you can create Plans, your tenant environment must have the following components configured:

Required Account Setup:

Account Type	Purpose	Requirement
Operational Account	Your agency's primary business operating account for receiving agency fees and operational funds	Exactly one per tenant
Transitory Account	Temporary holding account used for fund transfers between accounts	Exactly one per tenant
Fiduciary Account	Trust account(s) for holding client premium funds before disbursement to carriers	At least one, linked to a carrier

Required Entity Setup:

Entity	Purpose	Requirement
Carrier	Insurance company that will receive premium payments	At least one carrier with an associated fiduciary account
Producer (optional)	Agent/broker who earns commission on the policy	Required only if tracking commissions

Why These Are Required:

The flow-of-funds engine requires these accounts to properly route collected payments. When an insured pays a premium:

Funds are collected via the payment gateway
Premium amounts are routed to the carrier's fiduciary account
Agency fees are routed to the operational account
Producer commissions are calculated and tracked for payout
The transitory account facilitates transfers between accounts when needed

Verification:

Before creating your first Plan, verify your setup by calling:

GET /v1/carriers - Confirm at least one carrier exists
GET /v1/accounts - Confirm your accounts are configured

If these prerequisites are not met, Plan creation will fail with a validation error indicating the missing configuration.

Plan Statuses

Status	Description
`draft`	Plan created but not finalized; no payment link generated
`open`	Active plan with payment link; awaiting payment
`partially_paid`	Some payments received but balance remains
`paid`	Fully paid
`overdue`	Payment due date has passed
`deleted`	Soft deleted

Create a Plan

Creates a new plan with its associated invoice, payment link, and fund flow configuration.

Endpoint: POST /v1/plans

Use Cases:

Create a billing plan for a new insurance policy with automatic invoice generation
Generate a payment link for premium collection
Configure flow-of-funds for agency billing vs direct billing
Set up automated payment reminders

Request Body:

Field	Type	Required	Description
`insured_id`	string	No	ID of existing insured; if not provided, use recipient fields
`recipient_name`	string	No	Name of the invoice recipient
`recipient_email`	string	No	Email for sending invoice
`recipient_phone_number`	string	No	Phone number (max 20 chars)
`sender_name`	string	No	Name of the sender on the invoice
`sender_email`	string	No	Email of the sender on the invoice
`policies`	array	No	List of policies to include (see Policy Object below)
`billing_type`	string	No	`direct` or `agency` (default: `direct`)
`payment_due`	datetime	No	Payment due date
`status`	string	No	`draft` or `open` (default: `open`)
`invoice_number`	string	No	Custom invoice number
`invoice_header`	string	No	Custom header text (default: "Invoice")
`invoice_memo`	string	No	Notes to display on invoice
`agency_fees`	array	No	Additional agency fees (objects with `name` and `amount`)
`allowed_payment_methods`	array	No	Accepted methods: `ach`, `check`, `checkout_ach`, `checkout_credit_card`
`reminder_days`	array	No	Days relative to due date for reminders (max 4 reminders)
`producer_id`	string	No	Associated producer for commission
`use_agency_branding`	boolean	No	Use agency branding on invoice (default: false)

Policy Object:

Field	Type	Required	Description
`policy_name`	string	Yes	Name/description of the policy
`policy_number`	string	Yes	Policy number
`carrier_id`	string	Yes	Insurance carrier ID
`effective_date`	datetime	No	Policy effective date
`expiration_date`	datetime	No	Policy expiration date
`product_line_name`	string	No	Carrier product line name
`premium`	object	No	Premium amount (`name` and `amount` fields)
`taxes`	object	No	Tax amount (`name` and `amount` fields)
`fees`	object	No	Fee amount (`name` and `amount` fields)
`additional_policy_items`	array	No	Additional line items (each with `name` and `amount`)
`commission_percentage`	number/string	No	Carrier commission percentage
`producer_commission_percentage`	number/string	No	Producer commission percentage
`producer_commission_amount`	number/string	No	Producer commission amount (takes precedence over percentage)
`status`	string	No	Policy status (default: `open`)

Example Request - Basic Plan:

curl -X POST "https://api.advancehq.com/v1/plans" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Acme Corporation",
    "recipient_email": "[email protected]",
    "payment_due": "2025-02-15T00:00:00Z",
    "status": "open",
    "policies": [
      {
        "policy_name": "General Liability",
        "policy_number": "POL-2025-001",
        "carrier_id": "car_abc123",
        "effective_date": "2025-01-01T00:00:00Z",
        "expiration_date": "2026-01-01T00:00:00Z",
        "premium": {
          "name": "Premium",
          "amount": "5000.00"
        },
        "taxes": {
          "name": "State Tax",
          "amount": "250.00"
        }
      }
    ]
  }'

Example Request - Plan with Existing Insured and Producer:

curl -X POST "https://api.advancehq.com/v1/plans" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "insured_id": "ins_abc123",
    "producer_id": "prod_xyz789",
    "billing_type": "agency",
    "payment_due": "2025-03-01T00:00:00Z",
    "status": "open",
    "invoice_memo": "Thank you for your business!",
    "reminder_days": [-7, -3, 1, 7],
    "allowed_payment_methods": ["checkout_ach", "checkout_credit_card"],
    "policies": [
      {
        "policy_name": "Workers Compensation",
        "policy_number": "WC-2025-100",
        "carrier_id": "car_def456",
        "effective_date": "2025-01-15T00:00:00Z",
        "expiration_date": "2026-01-15T00:00:00Z",
        "premium": {
          "name": "Premium",
          "amount": "12500.00"
        },
        "producer_commission_percentage": "10"
      }
    ],
    "agency_fees": [
      {
        "name": "Processing Fee",
        "amount": "75.00"
      }
    ]
  }'

Response:

{
  "plan_id": "plan_abc123def456",
  "plan_number": "INV-2025-0001",
  "message": "Plan created successfully",
  "payment_url": "https://app.advancehq.com/checkout/abc123",
  "invoice_pdf_url": "https://storage.advancehq.com/invoices/plan_abc123.pdf"
}

List All Plans

Retrieves all plans for your tenant with optional filtering and pagination.

Endpoint: GET /v1/plans

Query Parameters:

Parameter	Type	Default	Description
`pagination`	boolean	false	Enable paginated response
`page`	integer	1	Page number (1-based)
`page_size`	integer	100	Items per page (max 10000)
`status`	string	open	Filter by status

Use Cases:

Sync invoices with your agency management system
Generate reports on outstanding balances
Monitor payment collection progress

Example - Get All Open Plans:

curl -X GET "https://api.advancehq.com/v1/plans?status=open" \
  -H "Authorization: Bearer your_api_key"

Example - Paginated Request:

curl -X GET "https://api.advancehq.com/v1/plans?pagination=true&page=1&page_size=50&status=partially_paid" \
  -H "Authorization: Bearer your_api_key"

Response (Non-Paginated):

[
  {
    "plan_id": "plan_abc123",
    "plan_number": "INV-2025-0001",
    "insured_id": "ins_xyz789",
    "insured_name": "Acme Corporation",
    "status": "open",
    "total_invoiced_amount": "5250.00",
    "collected_amount": "0.00",
    "payment_due": "2025-02-15T00:00:00Z",
    "payment_url": "https://app.advancehq.com/checkout/abc123",
    "invoice_pdf_url": "https://storage.advancehq.com/invoices/plan_abc123.pdf",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Response (Paginated):

{
  "data": [
    {
      "plan_id": "plan_abc123",
      "plan_number": "INV-2025-0001",
      "insured_name": "Acme Corporation",
      "status": "open",
      "total_invoiced_amount": "5250.00",
      "collected_amount": "0.00"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 150,
    "total_pages": 3,
    "has_next": true,
    "has_previous": false
  }
}

Get Plan by ID

Retrieves detailed information about a specific plan.

Endpoint: GET /v1/plans/{plan_id}

Use Cases:

Check payment status of a specific invoice
Retrieve invoice PDF URL for customer
Verify plan details before processing

Example:

curl -X GET "https://api.advancehq.com/v1/plans/plan_abc123" \
  -H "Authorization: Bearer your_api_key"

Response:

{
  "plan_id": "plan_abc123",
  "plan_number": "INV-2025-0001",
  "invoice_number": "INV-2025-0001",
  "insured_id": "ins_xyz789",
  "insured_name": "Acme Corporation",
  "producer_id": "prod_def456",
  "status": "partially_paid",
  "billing_type": "agency",
  "premiums": "12500.00",
  "taxes_and_fees": "75.00",
  "additional_policy_items_amount": "0.00",
  "total_invoiced_amount": "12575.00",
  "collected_amount": "5000.00",
  "commission_amount": "1257.50",
  "processing_fees_ach": "0.00",
  "processing_fees_credit_card": "375.00",
  "payment_due": "2025-03-01T00:00:00Z",
  "payment_url": "https://app.advancehq.com/checkout/abc123",
  "invoice_pdf_url": "https://storage.advancehq.com/invoices/plan_abc123.pdf",
  "invoice_header": "Invoice",
  "invoice_memo": "Thank you for your business!",
  "policies": [
    {
      "policy_id": "pol_123",
      "policy_name": "Workers Compensation",
      "policy_number": "WC-2025-100",
      "carrier_id": "car_def456",
      "carrier_name": "National Insurance Co",
      "effective_date": "2025-01-15T00:00:00Z",
      "expiration_date": "2026-01-15T00:00:00Z",
      "premium": {
        "name": "Premium",
        "amount": "12500.00"
      },
      "taxes": {
        "name": "State Tax",
        "amount": "50.00"
      },
      "fees": {
        "name": "Policy Fee",
        "amount": "25.00"
      },
      "additional_policy_items": [],
      "status": "open"
    }
  ],
  "agency_fees": [
    {
      "name": "Processing Fee",
      "amount": "75.00"
    }
  ],
  "created_at": "2025-01-10T14:20:00Z",
  "last_updated": "2025-01-20T09:15:00Z"
}

Get Plans Count

Returns the count of plans grouped by status.

Endpoint: GET /v1/plans/count

Use Cases:

Dashboard statistics
Monitoring invoice volume by status

Example:

curl -X GET "https://api.advancehq.com/v1/plans/count" \
  -H "Authorization: Bearer your_api_key"

Response:

{
  "total": 1250,
  "open": 450,
  "paid": 680,
  "partially_paid": 85,
  "draft": 20,
  "overdue": 15
}

Update Plan Status

Updates the status of an existing plan.

Endpoint: PUT /v1/plans/{plan_id}/status

Use Cases:

Mark a plan as deleted
Reopen a draft plan
Manually update payment status

Request Body:

Field	Type	Required	Description
`status`	string	Yes	New status: `draft`, `open`, `deleted`, `paid`, `partially_paid`

Example:

curl -X PUT "https://api.advancehq.com/v1/plans/plan_abc123/status" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "deleted"
  }'