Send campaign creator payouts

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.

This endpoint sends real payouts. Call Preview campaign creator payouts first and verify that calculation.readyToPay is true.

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 calculated payout.total returned by the preview, excluding any additionalLineItems.
currency (required): the exact payout.currency returned by the preview.
startDate and endDate (optional): the same inclusive YYYY-MM-DD range used for the preview. Send both or neither.
confirmHighValuePayout (optional): set to true when 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 credentials
409: the idempotency key was reused with different data, or the original request is still running
503: idempotency protection is temporarily unavailable

SDK v1

Campaign management

Send campaign creator payouts

POST /sdk/v1/campaign-creators/payouts/bulk

Headers

Body

Platform fee allocation

Additional line items

Example request

Response

Request errors

​POST /sdk/v1/campaign-creators/payouts/bulk

​Headers

​Body

​Platform fee allocation

​Additional line items

​Example request

​Response

​Request errors

POST /sdk/v1/campaign-creators/payouts/bulk

Headers

Body

Platform fee allocation

Additional line items

Example request

Response

Request errors