Skip to main content

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

Response

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

Common errors

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