Documentation / Campaign management / Campaign creators

Send campaign creator payouts

Send calculated campaign payouts to up to 100 campaign creators in one request.

send campaign creator payouts · json
{
  "platformFeePayerOverride": {
    "mode": "CUSTOM_SPLIT",
    "agencySharePercent": 50
  }
}
All 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 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
  • 409 with code: "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

Describe your program.

Grade turns it into a program it can track and pay.