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: The API field for markets on policies is carrier_id (a legacy name). The carrier_id and market_id values are identical — 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 (carrier_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

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",
        "carrier_id": "car_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.

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": [
      {
        "carrier_id": "car_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.

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.

Use GET /v1/plans/count for dashboard summaries (counts by status) or GET /v1/plans?status=overdue to identify plans that need attention.

Manually Updating Status

PUT /v1/plans/{plan_id}/status

Use this to record offline payments or to cancel/delete a plan. 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:

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.

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.