Documentation / Campaign management / Campaign creators

Offboard a campaign creator

Finalize earnings at a cutoff and stop future accrual while preserving paid history.

offboard a campaign creator · json
{
  "cutoffAt": "2026-11-11T10:30:00Z",
  "reason": "Collaboration ended by agreement"
}
All documentation

Offboarding permanently ends earnings for one creator in one campaign. Grade calculates the final balance at the selected cutoff, releases earned deferred CPM and bonuses, and freezes that balance. Already-paid items stay closed. Later views, uploads, and recurring periods do not create more earnings for this record.

Offboarding does not send money or settle the balance. Use the normal payout flow to pay it, or external settlement when it should no longer be payable in Grade. Contract history and prior payments remain intact.

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 /offboarding payouts:read Status and finalization receipt
POST /offboarding/preview payouts:write Review the final earnings
POST /offboarding/apply payouts:write Freeze the reviewed result

Review final earnings

{
  "cutoffAt": "2026-11-11T10:30:00Z",
  "reason": "Collaboration ended by agreement"
}

cutoffAt is optional; omit it to use server time now. When provided, it must be an ISO timestamp with an offset, at or before now. Grade uses recorded metrics available at the cutoff and the existing contract's earning rules. Offboarding does not invent a new prorating policy. reason is required, 3–1000 characters.

The response is { "success": true, "data": ... }. data contains previewId, planHash, expiresAt, cutoffAt, reason, timeZone, numeric amount, currency, appliedAt: null, and items with key, description, amount, and currency. A zero final balance is valid. Preview creates no payment and does not freeze earnings.

Confirm

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

Send this to /offboarding/apply using the same application that previewed it. Unused previews expire after 30 minutes. Grade rechecks earnings and payment activity before applying. Success returns the receipt with status: "OFFBOARDED" and appliedAt populated. There is no undo operation for offboarding.

Retry the same preview ID and hash after a lost response. A successful retry returns the existing receipt without finalizing twice. A stale or expired preview returns 409; review a new preview before confirming.

Finish or cancel pending payouts and approvals first. Ambiguous payment evidence, completed campaigns, missing payment terms, and records already offboarded cannot be finalized again. Financial conflicts return 409; invalid input returns 400; records and previews outside the API key's agency return 404.

GET /offboarding returns campaignCreatorRecordId, campaignId, creatorName, timeZone, canChange, and offboarding (the receipt or null). The receipt's amount is the original final amount; use normal payout line items for the remaining balance after payments or external settlements.

In the dashboard, use the creator context menu → Manage creator → Offboard creator.

Describe your program.

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