Documentation / Campaign management / Campaign creators

Preview campaign creator payouts

Calculate campaign creator payouts and see whether each one is ready to send.

preview campaign creator payouts · bash
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"
  }'
All documentation

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": "jordan@example.com",
      "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.

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

Describe your program.

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