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