> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview campaign creator payouts

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

## 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

```bash theme={null}
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

```json theme={null}
{
  "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",
        "mediaStillProcessing": 0,
        "mediaWithErrors": 0
      }
    }
  ],
  "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`.

### Calculation statuses

* `READY`: calculation is complete. `readyToPay` is `true` only when the total
  is greater than zero.
* `CALCULATING`: media is still being updated or the calculated values are
  refreshing. Try again later.
* `BLOCKED`: one or more media items could not be evaluated. The message and
  counters explain what needs attention.

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

Use the returned `payout.total` and `payout.currency` when you
[send the payout](/campaign-creators/send-payouts). Grade recalculates the
amount before sending and rejects the item if it changed.

### Common errors

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