Documentation / SDK v1

Payout disputes

Read the disputes creators open on payouts, reply to them, and resolve or reject them.

payout disputes · bash
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"
All 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_PAYOUT payouts have campaignId: null, and a campaign filter leaves them out.
  • Reopen once. A creator's reply to a rejected dispute reopens it. A second rejection is final, and so is resolved. canReopen says 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.

  1. Note the current time before you start.
  2. Read every page with since set to the time you noted on the previous run. The list is not in update order, so do not stop early.
  3. 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.

Describe your program.

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