Producers

Producers represent the agents or brokers who sell policies on behalf of your agency. In Advance, producers are linked to plans for commission tracking, and can be configured for automatic commission payouts on a recurring schedule.

Setting Up a Producer

POST /v1/producers

At minimum, provide producer_name. All other fields are optional but recommended for complete records:

• Contact details (contact_name, contact_email, contact_phone) are used for communication and appear on invoices.
• customer_external_id lets you reference this producer by your own system's ID (e.g., your AMS producer code). Once set, you can look up the producer by this ID using GET /v1/producers/customer_external_id/{id} — useful for syncing without storing Advance IDs.
• Billing contact fields (billing_contact_name, billing_contact_email, billing_contact_phone) are stored for payout processing but are not returned in API responses.
• producer_registry_id links this producer to an entry in Advance's shared producer registry. It's echoed back on the producer response, and is required if you want plans using this producer to be eligible for premium financing. An unrecognized producer_registry_id returns a 400 error. See Linking a Producer to the Registry below.

Dedicated Account Number

Every producer gets its own account number for incoming payments, returned as virtual_account on the producer. Give it to anyone paying on that producer's behalf — a premium finance company sending a funding, or an agency paying outside checkout. Money sent there by ACH or wire lands in your collection account and is attributed to that producer automatically.

The account is set up automatically shortly after the producer is created. Until then virtual_account is null.

Commission Rate Versioning

Commission rates are versioned with effective dates, which means you can:

• See the complete history of rate changes for a producer
• Schedule future rate increases in advance
• Be confident that policies always use the rate that was active when they were created

Viewing commission item history

GET /v1/producers/{producer_id}/commission-items/history

Returns all commission items grouped by (carrier_id, name). Each group represents the full rate history for one commission item scoped to a specific market. Groups have three buckets:

• current_rate — the version active today
• scheduled_rate — a future version not yet in effect (null if none scheduled)
• historical_rates — past versions that have expired

Because a producer can have the same commission item name for multiple markets (e.g., "Auto Insurance" for Market A and "Auto Insurance" for Market B), each group includes a carrier_id field to distinguish them.

[
  {
    "name": "Auto Commission",
    "carrier_id": "car_abc123",
    "current_rate": {
      "commission_item_id": "ci_001",
      "commission_percentage": 7.0,
      "effective_from": "2024-01-01",
      "effective_to": "2024-12-31"
    },
    "scheduled_rate": {
      "commission_item_id": "ci_002",
      "commission_percentage": 8.0,
      "effective_from": "2025-01-01",
      "effective_to": null
    },
    "historical_rates": []
  }
]

Setting or changing a rate

POST /v1/producers/{producer_id}/commission-items

To set or change a rate, create a new version. Once created, rates are immutable — you can't edit them, only add a new version. If an open-ended rate already exists for the same (carrier_id, name), it is automatically closed (its effective_to is set to the day before the new rate starts).

Example: schedule a rate increase for January 1

curl -X POST "https://api.advancehq.com/v1/producers/prod_xyz789/commission-items" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '[{
    "carrier_id": "car_abc123",
    "name": "Auto Commission",
    "commission_percentage": 7.0,
    "effective_from": "2025-01-01"
  }]'

This creates a new rate for Auto Commission starting January 1. Any existing open-ended Auto Commission rate for this market is automatically closed on December 31.

Deleting a commission item

DELETE /v1/producers/{producer_id}/commission-items/{commission_item_id}

Removes a specific rate version. Returns 400 if any policies reference this commission item. Returns 204 on success.

If you delete a future-dated rate, the predecessor rate that was automatically closed when it was created is reopened — its effective_to is reset to null.

How rates apply to policies

When a plan is created with a producer, the commission rate used for each policy is determined by the policy's effective date — the system looks up whichever rate was active on that date and locks it in. Subsequent rate changes don't affect existing policies. This means you can safely add new rate versions without worrying about retroactive changes.

When you set producer_commission_percentage directly on a policy in the plan creation request, that value overrides the rate lookup entirely.

Payout Configuration

Producers can receive automatic commission payouts on a recurring schedule. Configure this at producer creation or update:

• recurrence_payout_enabled: true enables automatic payouts
• payout_cadence sets when payouts run — a specific-dates or weekday-pattern monthly schedule, a weekly schedule, or an every-N-weeks schedule
• minimal_monthly_threshold sets a minimum accumulated balance that must be reached before a payout is triggered — useful for avoiding small, frequent transfers
• transfer_speed controls how funds are sent (default: ach)
• external_account_id points to the bank account (from GET /v1/external-accounts) where payouts are deposited
• the payout notification settings control whether the producer receives a confirmation email when their payout is sent, and whether your account's admins are emailed when a payout is sent or when a scheduled one fails

Each notification setting follows your account-level default unless you set it on the producer. Omit it and the producer keeps following the account default; send an explicit value to override it for that producer, or an explicit null to clear the override and go back to following the account. See Payouts for how the account defaults work.

See Payouts for the full list of cadence options, the next_payout_date field, and examples.

Payout-related fields (billing_contact_*, transfer_speed, external_account_id, and the payout notification settings) are stored and used for processing but are not included in the public producer API responses. The payout notification settings can be set on create/update but must currently be reviewed in the Advance dashboard rather than read back through the public API.

Two previously-accepted fields, notifications_email_enabled and notifications_email_template, have been removed. They never affected any email that was sent. If your integration still sends them they are ignored, and requests continue to succeed — but you can drop them from your payloads.

Producer Statements

If you bill your wholesale brokers for the premium on policies they've placed with you, you can generate
that bill from the producer's page in Advance, review it, and send it.

Choose a scope — all of the producer's currently open plans, or a date range filtered by invoice date or
policy effective date — and Advance computes one line per policy: policy number, invoice number, insured,
dates, gross premium, the producer's own commission, agency and surplus-lines fees, total invoiced, amount
paid, and total due. Policy taxes, policy fees, additional policy items, and each plan's own due date are
available but off by default. You can show, hide, rename, and reorder any column, and your choices are
remembered as the default for the next statement. A total row sits directly beneath the last line, under
Total Due. Your agency's own commission never appears on a producer statement.

Every statement carries a statement date — the date you generated it — which is not editable. A due
date is optional: set one before finalizing and it appears beneath the statement date, or leave it out
and the statement carries none.

Before finalizing you can optionally include ACH instructions (the producer's dedicated virtual account)
and/or check instructions, add a memo, and choose whether to email it right away. The check payable-to name
and mailing address come from your Settings → Invoice & Payment configuration (the payable-to arrives
pre-filled and can be overridden for a single statement), and the payment details also show your
Settings → Auto Inbox address so brokers know where to send payment files; anything you have not
configured is left off rather than shown blank. A statement exists from the moment you choose its scope, so
closing the window part-way through doesn't lose your work — reopen it and carry on, or discard it. Once
finalized the figures are final: download it (as
{Producer Name}-Statement-{MM-DD-YYYY}.xlsx, with dates shown as MM/DD/YYYY) or send it again at any time
from the producer's Statements tab, which also keeps the full history of who it was sent to and whether
each send succeeded.

Statements are managed in the Advance dashboard and are not part of the public API.

Linking a Producer to the Registry

Advance maintains a shared registry of known producers. Linking your producer records to registry entries is what allows a plan's policies to be submitted for premium financing with Advance's financing partner. Linking is optional for plans that never use financing, but required for financing eligibility -- if the producer on a plan isn't linked, financing quotes for that plan will not go through.

To link a producer, search the producer registry by name to find the matching entry, then set its producer_registry_id when you create the producer. It's echoed back on the producer response so you can confirm the link, and an id that doesn't exist in the registry is rejected. Search is fuzzy and tolerant of small typos, but only matches producers already in Advance's registry; if yours genuinely isn't listed, contact Advance support.

Markets and product lines link to the registry the same way -- see Markets. For the registry search and linking endpoints and their exact fields, see the API reference.

Looking Up Producers

Three ways to find a producer:

• GET /v1/producers — list all producers
• GET /v1/producers/{producer_id} — fetch by Advance ID
• GET /v1/producers/customer_external_id/{customer_external_id} — fetch by your system's ID

The external ID lookup is particularly useful in integrations where you manage producers in your AMS and want to reference them in plan creation without maintaining a separate mapping table.