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.

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
• notify_recipient_on_payout_sent controls whether the producer receives a confirmation email when their payout is sent (default: true)
• notify_tenant_on_payout_sent controls whether your account's admins receive a summary email when a payout is sent to this producer (default: false)
• notify_tenant_on_payout_failure controls whether your account's admins are alerted if a scheduled payout to this producer fails (default: true)

See Payouts for the full list of cadence options, the next_payout_date field, and examples. (The older recurrence_payout_day single-day field is still accepted but superseded by payout_cadence.)

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

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.

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.