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
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A label (max 255 characters) | yes |
| shares | array | One share per payee (see Share object) | yes |
Share object
| Name | Type | Description | Required |
|---|---|---|---|
| carrierId | number | Carrier record that gets the share, for any payee type. commission does not affect the split | yes |
| type | string | percent, fixed, threshold, or remainder | yes |
| percent | number | Percent of the amount after fixed shares (e.g., 60 for 60%), up to 2 decimals. Required for percent | no |
| amountCents | integer | Fixed amount in cents (e.g., 3000 for $30.00). Required for fixed | no |
| tiers | array | Percent tiers (see Tier object). Required for threshold | no |
| payoutMethod | string | direct or pending. Default direct | no |
Tier object
| Name | Type | Description | Required |
|---|---|---|---|
| upToCents | integer | null | Upper end of the tier, in cents. null for the last tier | yes |
| percent | number | Percent of the amount in this tier (e.g., 10 for 10%), up to 2 decimals | yes |
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
- Fixed shares come off the split amount.
- Each percent and threshold share is calculated from what is left after the fixed shares. They all use that same amount.
- The
remaindershare 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 }
] }| Payment | Broker (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:
| Name | Type | Description |
|---|---|---|
| id | number | ID of the rule set |
| name | string | Label of the rule set |
| version | number | Version number, starting at 1 |
| shares | array | The shares, as sent |
| createdAt | string | When 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
remaindershare, tiers are out of order or the lastupToCentsis notnull, or a share is missing its field (percent,amountCents, ortiers) - 404 Not Found: A
carrierIddoes not belong to your account
NoteWe check a
directpayee's bank account at payout, not at creation. If it is missing, we hold the leg. See Manage split legs.
Updated 9 days ago