> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External settlements

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

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://api-docs.usegrade.com/campaign-creators/offboarding.md),
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

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.