> ## 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.

# Payout disputes

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

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.

> [!WARNING]
>
> Every dispute opens with at least one link to TikTok, Instagram, YouTube, Facebook or Snapchat. Grade checks that the link is on one of those sites, not that the post belongs to the creator or to the payout. The rest of the proof is whatever the creator chose to attach, such as screenshots of bank statements or messages, so it may hold personal data. Grant `disputes:read` only to integrations that are allowed to store it.

## 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

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

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

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

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


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