Documentation / Campaign management / Campaign creators

External settlements

Remove reviewed earnings from the amount payable in Grade without sending money.

external settlements · json
{
  "cutoffExclusive": "2026-11-01",
  "reason": "October balance closed by agreement"
}
All documentation

External settlement means the selected earnings are no longer payable in Grade. It does not assert that the creator received a payment. Grade sends no money, debits no wallet, and sends no creator email. These endpoints use the same settlement history, preview, confirmation, and safe undo as the dashboard.

All requests require X-Application-Id and X-Api-Key. Paths below start with /sdk/v1/campaign-creators/:campaignCreatorRecordId.

Method and path Scope Purpose
GET /external-settlements payouts:read History and eligible recurring contract periods
POST /external-settlements/preview payouts:write Review the exact items and native-currency totals
POST /external-settlements/apply payouts:write Apply the reviewed settlement
POST /external-settlements/:settlementId/undo-preview payouts:write Check whether undo is safe
POST /external-settlements/:settlementId/undo payouts:write Restore the covered amounts to payable

Preview

{
  "cutoffExclusive": "2026-11-01",
  "reason": "October balance closed by agreement"
}

cutoffExclusive is a real calendar date interpreted in the campaign timezone. This example includes earnings through October 31. For an active creator, choose a historical boundary that has already passed. reason is required, 3–1000 characters. The server determines amounts; do not submit line items or amounts.

For supported monthly recurring contracts, provide explicit whole contract periods:

{
  "cutoffExclusive": "2026-11-01",
  "reason": "October balance closed by agreement",
  "monthlyPeriods": [
    { "startDate": "2026-10-01", "endDateExclusive": "2026-11-01" }
  ]
}

Use the contractPeriods from history. Partial or overlapping periods are refused. Normal external settlement does not make deferred earnings payable or end future accrual. To close a collaboration, first offboard the creator, then settle the frozen balance. In that case omit monthlyPeriods and choose a cutoff date after the offboarding instant, including the next local day when offboarding happened today. The frozen balance can include payment-rule earnings.

The response is { "success": true, "data": ... }. data contains previewId, planHash, expiresAt, cutoffExclusive, reason, timeZone, totals by currency, and items with key, description, decimal-string amount, and currency. No settlement is applied by preview. Unused previews expire after 30 minutes.

Confirm and retry

{
  "previewId": "creator-external-00000000-0000-4000-8000-000000000001",
  "planHash": "<exact planHash from preview>",
  "confirmed": true
}

Send this to /external-settlements/apply using the same application that created the preview. Success returns data.settlementId and data.status: "APPLIED". If the response is lost, retry the same preview ID and hash. The operation is idempotent. Changed financial evidence or an expired preview returns 409; obtain a fresh preview and review it before confirming again.

Undo

Send {} to /:settlementId/undo-preview. If its status is READY_TO_UNDO, send { "confirmed": true } to /:settlementId/undo. Grade rechecks safety at apply time. Later payments or changed financial evidence can block undo with 409. Repeating a completed undo returns UNDONE. Undo never sends or reverses money. For an offboarded creator, undo restores only the frozen final balance; it does not restart earnings.

Both read and write operations derive agency ownership from the API key. Completed campaigns are read-only. Unsupported contracts and unreconciled payment evidence return a conflict explaining what needs review; nothing is partially settled.

Describe your program.

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