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 carrier. 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 carriers (e.g., "Auto Insurance" for Carrier A and "Auto Insurance" for Carrier 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 carrier 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
• recurrence_payout_day sets the day of month (1–28) when payouts run
• 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

Payout-related fields (billing_contact_*, transfer_speed, external_account_id, notifications_*) are stored and used for processing but are not included in API responses.

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.