All documentation
Documentation
POST /sdk/v1/campaign-creators/payouts/bulk
Sends calculated campaign payouts for up to 100 creators. Each creator is recalculated immediately before payment so the amount cannot silently change between preview and payment.
For a custom one-off amount that should appear in campaign spend without settling calculated earnings, use Campaign quick pay.
Headers
X-Application-Id(required)X-Api-Key(required)X-Idempotency-Key(required): a unique value for this payout request. Retry the same request with the same key to receive the original result without paying twice.
Body
payouts is a non-empty array with no more than 100 items. Each item accepts:
campaignCreatorRecordId(required)amount(required): the exact calculatedpayout.totalreturned by the preview, excluding anyadditionalLineItems.currency(required): the exactpayout.currencyreturned by the preview.startDateandendDate(optional): the same inclusiveYYYY-MM-DDrange used for the preview. Send both or neither.confirmHighValuePayout(optional): set totruewhen the combined calculated amount and additional line items exceed your agency's payout confirmation threshold.additionalLineItems(optional): up to 100 one-off items to pay on top of this CCR's calculated earnings. Omit it or send[]for the existing behavior.platformFeePayerOverride(optional object): who pays the platform fee for this payout only, using the same format as Campaign quick pay.
Platform fee allocation
Each payout can use its own fee allocation. To split the platform fee equally between your agency and a selected creator, include:
{
"platformFeePayerOverride": {
"mode": "CUSTOM_SPLIT",
"agencySharePercent": 50
}
}
mode |
Meaning |
|---|---|
INHERIT |
Use the agency default, as when you omit the override. |
CREATOR_PAYS_ALL |
The creator covers the entire platform fee. |
AGENCY_PAYS_ALL |
Your agency covers the entire platform fee. |
CUSTOM_SPLIT |
Your agency covers agencySharePercent of the fee; the creator covers the remainder. |
For CUSTOM_SPLIT, agencySharePercent is required and must be a JSON number
between 0 and 100 inclusive. Other modes do not accept it. Unknown fields
inside the override are rejected. An invalid override rejects the whole batch
before any payment executes.
The override applies to this payout, including its additional line items. It
does not change the agency default, save a creator preference, or change the
fee rate or cap. Keep sending the calculated gross amount from the preview;
the override changes the creator's net receipt and your agency's wallet debit.
Retry with the same fee override and idempotency key. Changing or removing an
override while reusing the key returns 409. Omission and INHERIT are equivalent.
Additional line items
Each additional item accepts exactly two fields:
| Field | Type | Meaning |
|---|---|---|
description |
string | Required invoice label, 1–500 characters after trimming. Control characters are rejected. |
amount |
number or decimal string | Required positive amount with at most two decimal places, such as 25 or "25.00". |
Every additional item uses the payout's currency. Do not send a per-item
currency, quantity, or calculated line-item metadata. Amounts, their sum, and
the combined payout must fit within JavaScript's safe integer range in cents.
Zero, negative, non-finite, and sub-cent amounts are rejected.
The gross payout is amount + sum(additionalLineItems[].amount). Grade applies
its existing platform fees, wallet balance checks, and high-value confirmation
to that combined amount. Each description is saved as a separate line on both
invoices and in the saved payout breakdown.
The creator's net receipt and agency's debit depend on their fee allocation.
These items apply only to this payment. They do not change the contract, create recurring earnings, or replace a saved manual bonus on the CCR. This endpoint still requires payable calculated earnings; use Campaign quick pay for a standalone payment when there are none.
Retry with the same idempotency key and items. Changing either an item's
description or amount while reusing a key returns 409. Identical descriptions
are allowed and remain separate invoice lines.
Example request
curl -sS "$BASE_URL/sdk/v1/campaign-creators/payouts/bulk" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY" \
-H "X-Idempotency-Key: campaign-payout-2026-07-31-001" \
-d '{
"payouts": [
{
"campaignCreatorRecordId": "CCR_123",
"startDate": "2026-07-01",
"endDate": "2026-07-31",
"amount": 600,
"currency": "USD",
"additionalLineItems": [
{ "description": "Launch bonus", "amount": "50.00" },
{ "description": "Travel expenses", "amount": "25.00" }
],
"confirmHighValuePayout": true,
"platformFeePayerOverride": {
"mode": "CUSTOM_SPLIT",
"agencySharePercent": 50
}
}
]
}'
Response
The example pays a gross total of 675 USD: 600 USD calculated earnings plus
75 USD additional items. The successful response's amount includes the extras.
The request can contain both paid and failed items. A failure for one creator does not hide the results for the others.
{
"success": true,
"paidCount": 1,
"failedCount": 1,
"results": [
{
"campaignCreatorRecordId": "CCR_123",
"status": "PAID",
"payoutId": "pay_123",
"transactionId": "txn_123",
"amount": 675,
"currency": "USD"
},
{
"campaignCreatorRecordId": "CCR_456",
"status": "FAILED",
"reason": "The expected payout changed. Preview the payout again."
}
]
}
Common item failures include:
- the creator or campaign record was not found
- the payout is still calculating or has no payable amount
- the amount or currency no longer matches the current calculation
- high-value confirmation is required
- the agency wallet has insufficient available funds
Request errors
400: missing idempotency key, invalid body, additional line items, or fee override, or more than 100 payouts. Invalid additional items or fee overrides reject the request before any payment.401: missing or invalid SDK credentials409: the idempotency key was reused with different data, or the original request is still running409withcode: "APPROVAL_REQUIRED": the agency has approval mode on. This endpoint pays at once, so it pays nothing for that agency; submit the payouts for approval in Grade. The idempotency key is not used up, so you can retry it once approval mode is off.503: idempotency protection is temporarily unavailable
