Split

Bill an enterprise partner once and have Blitz split the payment across a roster of contractors or vendors on your behalf.

Create a Split

curl -X POST https://api.nest.useblitz.co/api/commerce/integration/splits \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enterpriseCompanyId": "co_...",
    "apContactBusinessProfileId": "bp_...",
    "clientIdempotencyKey": "unique-per-split",
    "totalAmountCents": "10000",
    "roster": [
      { "amountCents": "6000", "earlyPayoutElected": false, "contractorPaymentProfileId": "pp_..." },
      { "amountCents": "3500", "earlyPayoutElected": true, "subVendorId": "sv_..." }
    ]
  }'

• roster — each row is exactly one of contractorPaymentProfileId (an existing creator/business), subVendorId (your own vendor roster), or email (onboard someone brand new — see below).
• totalAmountCents— optional. Must be at least the roster sum; the difference becomes your company's margin, credited automatically once the Split funds. Omit to bill exactly the roster sum.
• clientIdempotencyKey — a repeated call with the same value against the same enterprise/AP-contact pair returns the existing Split instead of creating a duplicate.

Add a roster row by email

Set email (plus optional fullName) instead of contractorPaymentProfileId or subVendorIdto add a contractor who isn't on your roster yet, with no separate invite step:

{
  "amountCents": "500",
  "earlyPayoutElected": false,
  "email": "new-contractor@example.com",
  "fullName": "Jordan Lee"
}

• Already a SubVendor on your own roster for that email? It's reused as-is.
• Already a real Blitz account for that email? A SubVendor is created and auto-attached to it immediately — no invite/accept step.
• No existing account at all? A brand-new, passwordless account is provisioned immediately and lands active right away.

Either way, the row resolves to a subVendorId server-side — the response reflects it the same as if you'd passed subVendorIdyourself. A contractor onboarded this way with no PayPal email on file still can't be elected for instant payout until one's added.

Check status

Revise a pending roster

curl -X PUT https://api.nest.useblitz.co/api/commerce/integration/splits/spl_.../roster \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "totalAmountCents": "10500",
    "roster": [
      { "amountCents": "6000", "earlyPayoutElected": false, "contractorPaymentProfileId": "pp_..." },
      { "amountCents": "4000", "earlyPayoutElected": true, "subVendorId": "sv_..." }
    ]
  }'

Body shape matches creation: roster (required, same row shape as above — including email) and totalAmountCents (optional, omit to bill exactly the new roster sum). This replaces the roster wholesale, not a partial patch.

List your Splits

Skipping manual approval — auto-accept

By default, a Split you create through this API still waits for the named enterprise to approve it manually in their Blitz account, exactly like a Split created in the product. If an enterprise wants to skip that step for your company specifically, they can turn on auto-accept for you from their own Split settings — every Split you then create against them moves straight to approved and pays out automatically. This is entirely their decision; there's nothing for you to configure on your side.

Webhook events

Subscribe to these from your webhook endpoint instead of polling GET :id/GET in a loop. Every payload is intentionally thin — cross-reference the status endpoints above for the full current state (fees, net amounts, status, etc.).

• split.leg_a.approved — the enterprise approved the Split.
• split.leg_a.rejected — the enterprise rejected the Split.
• split.leg_a.claimed— your company's balance was credited the roster sum.
• split.roster_entry.settled — one roster row was transferred to its contractor (instant election or on-demand instant payout).
• split.roster_entry.failed— one roster row's transfer failed. Not something you retry yourself — it's independently retried server-side.
• split.margin.settled — your declared margin was released, either by your own instant election or the scheduled net-terms auto-release.

split.leg_a.* and split.margin.settled payloads carry { splitId, legAPayoutId } / { splitId, marginPayoutId }:

{
  "splitId": "spl_...",
  "legAPayoutId": "pay_..."
}

split.roster_entry.* payloads carry { splitId, rosterEntryId }:

{
  "splitId": "spl_...",
  "rosterEntryId": "dist_..."
}

split.margin.settled:

{
  "splitId": "spl_...",
  "marginPayoutId": "pay_..."
}