Preview campaign creator payouts

POST /sdk/v1/campaign-creators/payout-previews/query

Calculates the fixed, CPM, and bonus parts of each creator’s payout. The response separates payable and non-payable media and tells you whether the calculation is ready to pay. All requests require X-Application-Id and X-Api-Key.

Choose creators

Send exactly one of:

campaignCreatorRecordIds: up to 500 campaign creator record IDs.
campaignId: one campaign, with optional page and limit pagination. limit defaults to 100 and cannot exceed 500.

Optional fields

startDate and endDate: an inclusive YYYY-MM-DD payment range. Send both or neither.
includeNonPayable: include non-payable calculated line items. Default: true.

Example request

curl -sS "$BASE_URL/sdk/v1/campaign-creators/payout-previews/query" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "campaignCreatorRecordIds": ["CCR_123"],
    "startDate": "2026-07-01",
    "endDate": "2026-07-31"
  }'

Response

{
  "success": true,
  "data": [
    {
      "campaignId": "camp_123",
      "campaignName": "Summer launch",
      "campaignCreatorRecordId": "CCR_123",
      "creatorProfileId": "CP_123",
      "creatorEmail": "[email protected]",
      "effectiveTimeZone": "America/New_York",
      "dateRange": {
        "startDate": "2026-07-01",
        "endDate": "2026-07-31"
      },
      "payout": {
        "currency": "USD",
        "fixed": 300,
        "cpm": 250,
        "bonus": 50,
        "total": 600
      },
      "payableMedia": [
        {
          "campaignCreatorMediaId": "CCMEDIA_123",
          "url": "https://www.tiktok.com/@jordan/video/123",
          "platform": "TIKTOK",
          "uploadedAt": "2026-07-08",
          "views": 50000,
          "amount": 300,
          "currency": "USD",
          "paymentTypes": ["CPM", "BONUS"]
        }
      ],
      "nonPayableMedia": [
        {
          "campaignCreatorMediaId": "CCMEDIA_456",
          "url": "https://www.instagram.com/p/example/",
          "platform": "INSTAGRAM",
          "uploadedAt": "2026-07-10",
          "views": 800,
          "reason": "The post has not reached the minimum views."
        }
      ],
      "otherLineItems": [],
      "calculation": {
        "status": "READY",
        "readyToPay": true,
        "message": "Ready to pay.",
        "calculatedAt": "2026-08-01T08:00:00.000Z"
      }
    }
  ],
  "failures": [],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 1,
    "totalPages": 1
  }
}

Each preview includes the campaign’s effectiveTimeZone, resolved from the campaign override, agency fallback, or UTC. Use it when interpreting payout business dates and the requested dateRange. An unknown or inaccessible creator, a creator whose requested endDate predates their first contract terms, or a creator with a payout item that predates those terms is returned in failures without stopping the rest of the request. The failure reason distinguishes the requested-date and payout-item cases.

Calculation statuses

READY: calculation is complete. readyToPay is true only when the total is greater than zero.
CALCULATING: the calculated values are refreshing. Try again later.
BLOCKED: the payout could not be calculated. Try again later.

Bonus tiers do not stack. The bonus value is the highest tier the creator or post qualifies for.

Use the returned payout.total and payout.currency when you send the payout. Grade recalculates the amount before sending and rejects the item if it changed. If you also send additionalLineItems, keep amount equal to this calculated payout.total; Grade adds those one-off items at payment time. This preview does not include request-time additional items. See Send campaign creator payouts for the combined total and invoice behavior.

Common errors

400: invalid selector, pagination, or date range
401: missing or invalid SDK credentials
404: selected campaign not found

SDK v1

Campaign management

Preview campaign creator payouts

POST /sdk/v1/campaign-creators/payout-previews/query

Choose creators

Optional fields

Example request

Response

Calculation statuses

Common errors

​POST /sdk/v1/campaign-creators/payout-previews/query

​Choose creators

​Optional fields

​Example request

​Response

​Calculation statuses

​Common errors

POST /sdk/v1/campaign-creators/payout-previews/query

Choose creators

Optional fields

Example request

Response

Calculation statuses

Common errors