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, market, 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.

Prerequisites

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

Required Account Setup:

Required Entity Setup:

The fund-flow 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 market's fiduciary account, agency fees go to the operational account, and the transitory account facilitates transfers in between. If these prerequisites are not met, plan creation will fail with a validation error.

Note: Policies reference a market via market_id. See Markets for details.

Verify readiness with GET /v1/markets before your first plan.

Plan Lifecycle

Plans move through statuses as payments are collected:

Plans created through the public API always start as open — the payment link is generated immediately. Status transitions happen automatically as payments come in, but you can also update status manually using PUT /v1/plans/{plan_id}/status.

Creating a Plan

POST /v1/plans

Linking to an insured

You can associate a plan with an existing insured record via insured_id, or supply recipient_name and recipient_email inline for a one-off plan. Using insured_id is recommended when you manage insureds separately — it enables filtering plans by insured and provides a single source of truth for customer data.

Billing type: direct vs agency

billing_type controls who is billed:

• direct (default) — The insured receives the invoice and pays the premium. Use this for standard premium collection.
• agency — The producer or agency pays on behalf of the insured. Use this when your agency collects premiums and remits to markets.

Policies

Each plan includes one or more policies. A policy links a market (market_id is the only required field) and specifies the financial breakdown: premium, taxes, fees, and any additional line items.

For commission tracking, set producer_commission_percentage on the policy. If both a percentage and a fixed producer_commission_amount are supplied, the fixed amount takes precedence. The commission_percentage field on the policy tracks the agency's market commission — this is automatically pulled from the market's configured product line rate if you set product_line_name.

Per-policy producer assignment

For Direct Bill plans, each policy can be assigned its own producer via producer_id on the policy object. When policies have different producers, each generates its own independent commission disbursement in the fund flow — so a single plan can pay out commissions to multiple agents from one insured payment.

For Agency Bill plans, the producer is set at the plan level and applies uniformly to all policies.

You can also set producer_id at the plan level as a fallback: any policy that doesn't specify its own producer will inherit the plan-level one.

Per-policy agency fees and surplus lines

Agency fees (agency_fees), surplus taxes (surplus_tax_lines), and surplus fees (surplus_fees_lines) can all be set per policy. This is the recommended approach for multi-policy plans where each policy may have different fee or surplus obligations. Per-policy amounts are summed with any plan-level amounts when calculating the invoice total and routing fund flow.

Payment methods

The allowed_payment_methods field controls which payment methods a plan accepts. There are two online checkout methods and two offline methods:

Online checkout methods (checkout_ach, checkout_credit_card) control which options appear on the payment page:

• If you omit all checkout_* values, both online methods are enabled by default.
• To offer only one online method, pass just that value — e.g. ["checkout_credit_card"] shows card only, ["checkout_ach"] shows ACH only.

Offline methods (ach, check) are additive — include them to also display manual bank-transfer or pay-by-check instructions on the invoice.

Examples:

• allowed_payment_methods omitted → online ACH + credit card
• ["checkout_credit_card"] → online credit card only
• ["checkout_ach", "check"] → online ACH plus pay-by-check instructions
• ["ach"] → both online methods plus manual bank-transfer instructions

Check instructions. Plans that accept checks print who the check is payable to, where to mail it, and the invoice number to write on it. These come from your agency's check settings by default, and you can set a different payee or mailing address for an individual plan.

Reminders

reminder_days is an array of integers relative to the due date: negative values fire before the due date, positive values after. For example, [-7, -1, 3] sends reminders 7 days before, 1 day before, and 3 days after the due date. Maximum 4 entries.

Example: Plan with producer and reminders

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",
    "billing_type": "direct",
    "payment_due": "2025-03-01T00:00:00Z",
    "reminder_days": [-7, -3, 1],
    "policies": [
      {
        "policy_name": "Workers Compensation",
        "policy_number": "WC-2025-100",
        "market_id": "mkt_def456",
        "producer_id": "prod_xyz789",
        "product_line_name": "Workers Comp",
        "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": "625.00" },
        "producer_commission_percentage": "10"
      }
    ]
  }'

The response includes payment_url (the checkout link to send to the insured) and invoice_pdf_url (downloadable invoice PDF). The plan_id is the identifier you use for all subsequent operations on this plan.

Plans that support premium financing (installments)

If your tenant is live with a premium financing partner, an eligible plan created through POST /v1/plans automatically offers the insured the option to pay in installments at checkout — Advance brokers the financing quote for you. (This is different from the third-party flow below, where you arrange the loan yourself.) A plan is eligible only when the plan total is at least $900, the insured has a complete address, and each policy's market is set. When the insured chooses installments, they pay the down payment at checkout — which binds the loan — and the partner finances the remainder. Once a quote exists, the plan detail response includes a premium_financing object with the quote reference, terms, and agreement link; it is null otherwise and is never returned on the list endpoint.

For financing quotes to succeed, the plan's market, producer, and product line must each be linked to Advance's shared registry (market_registry_id, producer_registry_id, coverage_registry_id). Without these links, the quote will not go through. See Markets and Producers for how to search the registry and link your records.

You can also check eligibility programmatically: the plan detail response reports whether a plan currently qualifies for Advance-brokered premium financing and, when it doesn't, the reasons why — for example, the plan is financed by your own third-party provider, your tenant isn't set up with a financing partner, the plan total is under the financing minimum, the insured's address is incomplete, or the market, producer, or product line isn't linked to the registry. This is read-only and does not change quoting behavior; it's returned on the plan detail only. See the API reference for the exact fields and reason values.

Creating a Premium Financing Plan

POST /v1/plans/premium-financing

Use this endpoint instead of POST /v1/plans when a plan is financed by your own third-party premium financing provider rather than paid in full by the insured. The insured is charged only the down payment at checkout; the financed remainder is your arrangement with your financing provider, not something collected through Advance.

This endpoint accepts all the same fields as POST /v1/plans (insured, policies, billing type, reminders, etc.), plus two additional required fields:

The financed remainder is not something you send — Advance computes it automatically as total_invoiced_amount - down_payment_amount once the plan's policies are totaled, and returns it as financed_amount on GET /v1/plans/{plan_id}.

Example: Premium financing plan

curl -X POST "https://api.advancehq.com/v1/plans/premium-financing" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "insured_id": "ins_abc123",
    "payment_due": "2025-03-01T00:00:00Z",
    "policies": [
      {
        "market_id": "mkt_def456",
        "premium": { "name": "Premium", "amount": "1000.00" }
      }
    ],
    "finance_provider_name": "Acme Premium Finance",
    "down_payment_amount": "200.00"
  }'

The response has the same shape as POST /v1/plans — plan_id, payment_url, invoice_pdf_url. The checkout link only ever asks the insured for the down payment; Advance does not offer its own installment financing on top of a plan that's already financed by your provider.

Recording the financed remainder

Once your financing provider pays out the financed remainder (typically by check), record it the same way you'd record any other offline payment — deposit and link it to the plan (see Manually Updating Status) or through your normal check-deposit process. The plan moves to paid once both the down payment and the financed remainder have been collected.

Editing a Plan

You can correct an open plan in place. The plan keeps its plan number and payment link, so a link you already sent keeps working and shows the corrected amount. Each edit issues a new invoice, and nothing is emailed to the insured.

Anything you leave out of an edit keeps its current value, except the policies: send every policy the plan should keep, since they replace the existing ones.

A plan can be edited only until it receives a payment, is cancelled, or its payouts start. See the API reference for the request details.

Tracking Payments

Once a plan is open, use GET /v1/plans/{plan_id} to check the current state. The collected_amount field shows how much has been received, and total_invoiced_amount is the full amount due. Status changes automatically to partially_paid when some — but not all — of the balance is collected, and to paid when collection is complete.

Each plan also carries a reconciliation_status field summarizing how much of the total has been collected against it: unreconciled, partially_reconciled, reconciled, or overpaid.

Use GET /v1/plans/count for dashboard summaries (counts by status) or GET /v1/plans?status=overdue to identify plans that need attention. You can also narrow the list by reconciliation state with GET /v1/plans?reconciliation_status=partially_reconciled to surface plans still awaiting funds.

Manually Updating Status

PUT /v1/plans/{plan_id}/status

Use this to record offline payments or to cancel/delete a plan. A plan can only be deleted while no payment has been collected for it; once money has been received, cancel or refund it instead. When setting status to paid or partially_paid, include amount to record the payment amount. This is useful when payment was collected outside the checkout flow (e.g., a check was received).

# Record a partial payment collected by check
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": "partially_paid", "amount": "2500.00" }'

Fund Flow

GET /v1/plans/{plan_id}/fund-flow

After a plan is paid, use this endpoint to see how funds were (or will be) routed. The fund flow shows each disbursement leg: payment received into the transitory account, then distributed to the market's fiduciary account, agency operational account, and any producer payout.

Fund flow statuses progress as transfers complete:

Each leg also carries its own status and, once it has moved, the actual transfer date: the market and producer payout legs reach completed with that date when their external payout finishes. This is useful for reconciliation and auditing — you can verify that a paid plan's funds actually reached the expected accounts.

Which bank account each leg uses

Each leg also shows the bank account involved in a single account_details object — the account name, the bank, the last four digits of the account number, and the account type.

For a leg that has not been transferred yet, this is always the account currently linked to that market, producer, or agency account. Advance re-checks it at the moment it moves the money, so if you update a bank account after a plan is created, the next transfer uses the new account and the fund flow reflects that straight away. Once a leg's transfer has started, its bank details are fixed to the account actually used and no longer change, so past transfers always show where the money really went.

A party with no bank account on file has no leg in the fund flow; the leg appears once an account is linked. If an account is missing or closed when a transfer is due, that leg waits rather than failing, and the remaining legs still go through.

Branches may be added after plan creation if an entity (market, producer) gains a bank account between plan creation and payment receipt. The branches_rederived field in the disbursement-received response indicates how many were added.

Surplus Lines

For surplus lines policies, use surplus_tax_lines and surplus_fees_lines to itemize surplus taxes and fees separately from standard policy taxes and fees. These can be set per policy (recommended) or at the plan level. Per-policy and plan-level surplus amounts are combined into a single surplus disbursement in the fund flow and surfaced as dedicated line items on the invoice.