Skip to main content
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.

Preview

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

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.