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.

Creating a Market with a Bank Account

When you create a market, you can optionally include bank account details in the same request. This creates the bank account and links it to the market in a single call, which is useful when onboarding a new carrier that needs a payout destination immediately.

The bank_account object requires account_name, account_number, and routing_number. The created bank account is automatically set as the market's payout destination.

If you prefer to set up the bank account separately, create the market first and then link an existing account via the update endpoint.

Payout Configuration

Markets can receive automatic scheduled disbursements on a recurring schedule. To enable payouts:

1. Ensure the market has a linked bank account (via inline creation or by linking an existing external account)
2. Link the market to an Advance fiduciary account (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_type and 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:

• notify_recipient_on_payout_sent -- email the market when their payout is sent (default: true)
• notify_tenant_on_payout_sent -- email your admins when a payout is sent (default: false)
• notify_tenant_on_payout_failure -- email your admins when a payout fails (default: true)

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.

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.
• Bank account details provided at creation are used to create an external account record. The account number and routing number cannot be retrieved via the API after creation.