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
Reasons
video_missing, crosspost_not_counted, wrong_amount, other.
List disputes
GET /sdk/v1/disputes requires disputes:read.
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:
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 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 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
Stay up to date
PollGET /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.
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.