All documentation
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 optionalpageandlimitpagination.limitdefaults to100and cannot exceed500.
Optional fields
startDateandendDate: an inclusiveYYYY-MM-DDpayment 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.readyToPayistrueonly 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 range401: missing or invalid SDK credentials404: selected campaign not found
