All documentation
Documentation
A creator who thinks a payout is wrong can open a dispute on it. Your brand answers in Grade or through these endpoints.
Grant disputes:read to read disputes and download proof, and disputes:write to reply and resolve. Existing keys do not gain these permissions automatically, and payouts:write alone is not enough. Write does not imply read.
How disputes work
- One dispute per payout. A payout has at most one dispute, ever. Later messages go in the same thread.
- Disputes never move or block money. Opening, resolving or rejecting a dispute does not cancel, refund, hold or send anything. If the outcome means paying more, send that payout separately.
- A dispute may have no campaign. Disputes on
AGENCY_CREATOR_ROLE_PAYOUTpayouts havecampaignId: null, and acampaignfilter leaves them out. - Reopen once. A creator's reply to a rejected dispute reopens it. A second rejection is final, and so is
resolved.canReopensays whether a reply can still reopen the dispute.
Statuses
| Status | Meaning |
|---|---|
open |
Waiting for an answer. awaitingBrandSince is set while the last word is the creator's. |
resolved |
Your brand accepted the dispute. Final. |
rejected |
Your brand rejected the dispute, with a reason sent to the creator. |
Reasons
video_missing, crosspost_not_counted, wrong_amount, other.
List disputes
curl "$BASE_URL/sdk/v1/disputes?status=open&since=2026-10-01T00:00:00Z&page=1&limit=50" \
-H "X-Application-Id: $APPLICATION_ID" \
-H "X-Api-Key: $API_KEY"
GET /sdk/v1/disputes requires disputes:read.
| Parameter | Description |
|---|---|
campaign |
Campaign ID. |
status |
open, resolved, or rejected. |
since |
ISO 8601 time with Z or an offset. Filters on the last update, inclusive: updatedAt at or after this time. URL-encode a + in an offset. |
page |
Default 1. |
limit |
Default 50, maximum 100. |
Open disputes come first, then oldest first. The response is { success: true, data: [...], pagination: { page, limit, total, totalPages } }.
Read a dispute
GET /sdk/v1/disputes/:id requires disputes:read and adds description and messages to the list fields:
{
"success": true,
"data": {
"id": "00000000-0000-4000-8000-000000000001",
"payoutId": "CCPAY_example",
"payoutType": "CAMPAIGN_CREATOR_PAYOUT",
"campaignId": "campaign_example",
"campaignName": "Summer Launch",
"creatorProfileId": "creator_example",
"creatorName": "Casey",
"agencyId": "agency_example",
"agencyName": "Example Brand",
"reason": "video_missing",
"status": "open",
"canReopen": false,
"awaitingBrandSince": "2026-10-01T10:00:00.000Z",
"brandRemindedAt": null,
"escalatedAt": null,
"createdAt": "2026-10-01T10:00:00.000Z",
"updatedAt": "2026-10-01T10:00:00.000Z",
"resolvedAt": null,
"description": "My second video is not on this payout.",
"messages": [
{
"id": "00000000-0000-4000-8000-000000000002",
"author": "creator",
"event": "opened",
"body": "My second video is not on this payout.",
"attachments": [
{ "id": "00000000-0000-4000-8000-000000000003", "kind": "link", "url": "https://example.com/video" },
{ "id": "00000000-0000-4000-8000-000000000004", "kind": "file", "name": "proof.png", "contentType": "image/png", "sizeBytes": 20480 }
],
"createdAt": "2026-10-01T10:00:00.000Z"
}
]
}
}
author is creator, brand, or grade. event is opened, message, reopened, resolved, or rejected. escalatedAt is set when a dispute goes 14 days without an answer from your brand; Grade support sees those disputes.
Download proof
GET /sdk/v1/disputes/:id/attachments/:attachmentId requires disputes:read and returns a file attachment as a download: a JPEG, PNG, or WebP image of up to 10 MB. Link attachments already carry their url in the thread and have no file.
Reply
POST /sdk/v1/disputes/:id/reply requires disputes:write and X-Idempotency-Key. It emails the creator and leaves the dispute open. Replies carry text only.
{ "body": "We are checking this video with the campaign team." }
body is required, up to 5,000 characters. The response is 201 with the dispute as it is now.
Resolve or reject
POST /sdk/v1/disputes/:id/resolve requires disputes:write and X-Idempotency-Key. It closes an open dispute and emails the creator.
{ "outcome": "rejected", "message": "This video was uploaded after the payout period." }
outcome is resolved or rejected. message goes to the creator, up to 5,000 characters. It is optional for resolved and required for rejected. The response is 200 with the dispute as it is now.
Retries
X-Idempotency-Key is required on both writes, up to 128 characters, and is scoped to the dispute. Retrying with the same key and body returns the dispute as it is now, without adding a second message or emailing again. The same key with a different body answers 409 with IDEMPOTENCY_PAYLOAD_MISMATCH.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
INVALID_REQUEST, DISPUTE_INVALID |
Invalid parameters or body, such as a rejection without a message. |
400 |
INVALID_IDEMPOTENCY_KEY |
X-Idempotency-Key is missing or too long. |
403 |
The key is missing the required scope. | |
404 |
DISPUTE_NOT_FOUND, DISPUTE_ATTACHMENT_NOT_FOUND |
Not found in your agency. |
404 |
DISPUTES_NOT_ENABLED |
Payout disputes are not available yet. |
409 |
DISPUTE_CLOSED |
The dispute is already closed. |
409 |
IDEMPOTENCY_PAYLOAD_MISMATCH |
The key was used with a different body. |
503 |
DISPUTE_UNAVAILABLE |
Temporarily unavailable. Retry with the same key. |
Stay up to date
Poll GET /sdk/v1/disputes with since. A new dispute, a creator's message, a reopening, and your own answers all change updatedAt.
- Note the current time before you start.
- Read every page with
sinceset to the time you noted on the previous run. The list is not in update order, so do not stop early. - Handle each dispute by
id. The filter is inclusive, so you can see the same dispute twice.
There is no webhook for SDK keys. If you need a push, dispute.created is available through your agency's chat integrations, using the generic webhook. Those webhooks are configured in the Grade dashboard and are unsigned, so treat the call as a hint and read the dispute through this API.
