Create split rule set

This endpoint creates a split rule set at version 1. Add it to any number of invoices and card charges.

Request

POST /api/public/split-rule-sets

Request body

NameTypeDescriptionRequired
namestringA label (max 255 characters)yes
sharesarrayOne share per payee (see Share object)yes

Share object

NameTypeDescriptionRequired
carrierIdnumberCarrier record that gets the share, for any payee type. commission does not affect the splityes
typestringpercent, fixed, threshold, or remainderyes
percentnumberPercent of the amount after fixed shares (e.g., 60 for 60%), up to 2 decimals. Required for percentno
amountCentsintegerFixed amount in cents (e.g., 3000 for $30.00). Required for fixedno
tiersarrayPercent tiers (see Tier object). Required for thresholdno
payoutMethodstringdirect or pending. Default directno

Tier object

NameTypeDescriptionRequired
upToCentsinteger | nullUpper end of the tier, in cents. null for the last tieryes
percentnumberPercent of the amount in this tier (e.g., 10 for 10%), up to 2 decimalsyes

List tiers from lowest to highest. The last tier covers everything above. Tiers measure the amount after fixed shares, the same base as percent shares.

A direct leg pays the payee's bank account on file (see Add bank for carrier). A pending leg emails the payee to cash out by bank transfer, Venmo, or paper check, as with a pending payment.

Share order

  1. Fixed shares come off the split amount.
  2. Each percent and threshold share is calculated from what is left after the fixed shares. They all use that same amount.
  3. The remainder share gets the rest.

Each rule set needs exactly one remainder share, so the shares always add up to the split amount.

Suppose a rule set has a $30.00 fixed share, a 60% share, and a remainder share. On a $1,000.00 payment, the fixed share is $30.00, the percent share is $582.00 (60% of $970.00), and the remainder is $388.00.

Threshold shares

A threshold share changes with the payment size. To cap the broker at $500.00, give 10% up to $5,000.00 and 0% above. Tiers apply after fixed shares. These examples have none.

{ "carrierId": 503, "type": "threshold", "tiers": [
  { "upToCents": 500000, "percent": 10 },
  { "upToCents": null, "percent": 0 }
] }
PaymentBroker (threshold)Carrier (remainder)
$3,000.00$300.00$2,700.00
$10,000.00$500.00$9,500.00

For tiered rates, give each tier its own percent. With 70% up to $5,000.00 and 50% above, an $8,000.00 payment gives $3,500.00 + $1,500.00 = $5,000.00.

Example

{
  "name": "Standard 60/25/15",
  "shares": [
    { "carrierId": 501, "type": "percent", "percent": 60, "payoutMethod": "direct" },
    { "carrierId": 502, "type": "percent", "percent": 25, "payoutMethod": "direct" },
    { "carrierId": 503, "type": "remainder", "payoutMethod": "pending" }
  ]
}

Response

A successful request returns a 201 Created status code with the rule set:

NameTypeDescription
idnumberID of the rule set
namestringLabel of the rule set
versionnumberVersion number, starting at 1
sharesarrayThe shares, as sent
createdAtstringWhen created (ISO 8601)
{
  "id": 12,
  "name": "Standard 60/25/15",
  "version": 1,
  "shares": [
    { "carrierId": 501, "type": "percent", "percent": 60, "payoutMethod": "direct" },
    { "carrierId": 502, "type": "percent", "percent": 25, "payoutMethod": "direct" },
    { "carrierId": 503, "type": "remainder", "payoutMethod": "pending" }
  ],
  "createdAt": "2026-11-09T15:00:00.000Z"
}

Error Responses

  • 400 Bad Request: Percents total over 100 (a threshold counts at its highest tier percent), the rule set does not have exactly one remainder share, tiers are out of order or the last upToCents is not null, or a share is missing its field (percent, amountCents, or tiers)
  • 404 Not Found: A carrierId does not belong to your account
📘

Note

We check a direct payee's bank account at payout, not at creation. If it is missing, we hold the leg. See Manage split legs.


Did this page help you?