Markets

Markets represent the insurance carriers (insurance companies) whose policies your agency writes. In Advance, markets are linked to policies within plans and determine how collected premiums are routed and what commission rates apply.

When You Need Markets

You need to create and configure markets when:

• Your agency starts working with a new insurance carrier
• You want to automate premium routing and commission tracking for a carrier
• You need to set up scheduled disbursements (payouts) to a carrier

Every policy in a plan references a market. When a plan is created, Advance uses the market's configuration to determine where premiums flow and what commission rates apply.

Product Lines and Commission Rates

A market's product lines represent the types of insurance it offers (e.g., "General Liability", "Auto", "Workers Comp"). Each product line carries a commission rate -- the percentage of premium your agency earns from the market for policies written on that line.

How rates work

• Each rate version has an effective_from and optionally an effective_to date
• When a policy is created, the rate active on the policy's effective date is locked in permanently
• New rate versions do not affect existing policies
• If an open-ended rate exists for the same product line name, creating a new version automatically closes the old one (its effective_to is set to the day before the new rate starts)
• Rates are immutable once created -- to change a rate, create a new version

Event-specific commission overrides

Product lines support per-event-type commission overrides via the event_commissions field. For example, you might set a higher commission for new business than for renewals:

{
  "name": "Commercial Auto",
  "commission_percentage": 12.5,
  "event_commissions": {
    "new": 15.0,
    "renew": 10.0
  }
}

When event_commissions is set, the event-specific rate takes precedence over commission_percentage for matching policy event types. The base commission_percentage is used as a fallback for any event type not listed.

A product line can also be linked to Advance's shared coverage registry via coverage_registry_id when it's created (see Linking a Market to the Registry below). This is required for premium-financing eligibility on plans using that product line.

Adding a Payout Bank Account

Include a bank_account object when you create or update a market to create a bank account and set it as the market's payout destination. On an existing market, this replaces the current payout account.

The bank_account object requires account_name, account_number, and routing_number. The account_name must be unique across your bank accounts. The linked account is returned as bank_account_id.

Payout Configuration

Markets can receive automatic scheduled disbursements on a recurring schedule. A market's payouts involve two accounts: fiduciary_account_id is the Advance account the money comes from, and bank_account_id is the market's bank account it goes to. To enable payouts:

1. Ensure the market has a linked payout bank account (see Adding a Payout Bank Account)
2. Link the market to an Advance fiduciary account (fiduciary_account_id) -- this is the source of payout funds
3. Enable payouts by setting recurrence_payout_enabled to true
4. Configure the payout schedule via payout_cadence

Supported cadence types are monthly, weekly, and every_n_weeks. The next_payout_date field in responses shows when the next scheduled payout will occur.

Payout notifications

You can control who gets notified about payouts: whether the market is emailed when its payout is
sent, and whether your own admins are emailed when a payout is sent or when a scheduled one fails.

These follow your account-level defaults unless you set them on the market. Omitting a notification
field when you create or update a market leaves it following the account default; sending an explicit
value makes it an override for that market, and sending an explicit null clears the override and
returns the market to the account default. See Payouts for how the defaults work, and
the API reference for the field names.

Connecting Markets to Plans

When creating a plan, each policy specifies a market_id (or carrier_id). If you also set product_line_name on the policy, Advance automatically looks up the commission rate for that product line on the policy's effective date and applies it. This eliminates the need to manually specify commission_percentage on every policy.

Linking a Market to the Registry

Advance maintains a shared registry of known insurance carriers (markets) and coverages. Linking your own market and product-line 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 market or product line on a plan isn't linked, financing quotes for that plan will not go through.

The flow is the same for both: search the registry by name to find the entry that matches your record, then link it. You link a market by setting its market_registry_id when you create the market, and a product line by setting its coverage_registry_id when you add it to a market. (Registry linking is done at creation time.) Both are echoed back on the corresponding responses so you can confirm the link, and an id that doesn't exist in the registry is rejected. (On product-line responses the link is also mirrored under the older coverages_registry_id name for backward compatibility, but that field is deprecated -- use coverage_registry_id.)

Search is fuzzy and tolerant of small typos, but only matches names already in Advance's registry; if your carrier or coverage genuinely isn't listed, contact Advance support. Producers link the same way -- see Producers. For the registry search and linking endpoints and their exact fields, see the API reference.

Looking Up Markets

Three ways to find a market:

• List all -- returns lean records without product lines, efficient for building selection dropdowns. Supports optional pagination.
• By ID -- full details including all product line rates
• By external ID -- look up using the customer_external_id you assigned at creation, useful when your AMS stores carriers by your own codes

Important Notes

• The customer_external_id must be unique per tenant. Attempting to create two markets with the same external ID will fail.
• The market_id and carrier_id fields in responses contain the same value. During the migration period, both are returned. Use market_id in new integrations.
• Product line rates are immutable. To change a rate, create a new version with a new effective_from date.
• Every market response returns fiduciary_account_id, the linked Advance fiduciary account. A null value means no account is linked, so the market gets no fiduciary leg in the fund flow — check this before creating its first plan.
• account_id is the older name for fiduciary_account_id. It is still accepted and returned, but use fiduciary_account_id in new integrations.
• A null bank_account_id means the market has no payout bank account yet.