Disputes, evidence & brands

All endpoints here are GET requests under https://app.disputedash.com/api/v1. See Overview & authentication for keys, scopes and pagination.

The dispute object

{
  "id": "0b6c2f5e-6f3a-4a52-9a77-3f2a8e1d9c10",
  "object": "dispute",
  "status": "SUBMITTED",
  "dispute_type": "CHARGEBACK",
  "processor": "BRAINTREE",
  "processor_dispute_id": "abc123xyz",
  "processor_case_number": "CB-778812",
  "brand": { "id": "5f0e...", "name": "Acme Supplements" },
  "order_id": "AB1-104422",
  "amount": 89.95,
  "currency": "USD",
  "amount_base": 89.95,
  "base_currency": "USD",
  "reason_code": "13.1",
  "reason_category": "ITEM_NOT_RECEIVED",
  "card_brand": "Visa",
  "order_type": "SUBSCRIPTION",
  "is_digital": false,
  "delivery_status": "DELIVERED",
  "billing_country": "US",
  "auto_accepted": false,
  "reply_by": "2026-11-20T00:00:00.000Z",
  "opened_at": "2026-11-02T14:11:09.000Z",
  "submitted_at": "2026-11-03T08:40:51.000Z",
  "won_at": null,
  "lost_at": null,
  "created_at": "2026-11-02T14:12:30.000Z",
  "updated_at": "2026-11-03T08:40:51.000Z",
  "customer": null,
  "dashboard_url": "https://app.disputedash.com/cases/0b6c2f5e-6f3a-4a52-9a77-3f2a8e1d9c10"
}

Field	Notes
status	GATHERING_EVIDENCE, NEEDS_ATTENTION, AWAITING_REVIEW, SUBMITTING, SUBMITTED, UNDER_REVIEW, WON, LOST, EXPIRED, SKIPPED, UNMAPPED_REASON, UPGRADE_REQUIRED. See Case statuses.
dispute_type	CHARGEBACK, PRE_ARBITRATION, ARBITRATION, RETRIEVAL, INQUIRY.
processor	BRAINTREE, PAYPAL, STRIPE, PAYARC, SHOPIFY_PAYMENTS, SQUARE, ADYEN, CHECKOUT_COM, KLARNA, AIRWALLEX, FINIX, AFTERPAY (more may be added).
reason_category	DisputeDash’s normalised reason: FRAUD, UNAUTHORIZED, NOT_RECOGNIZED, ITEM_NOT_RECEIVED, PRODUCT_UNSATISFACTORY, CANCELLED_SUBSCRIPTION, CREDIT_NOT_PROCESSED, ALREADY_REFUNDED, DUPLICATE, INCORRECT_AMOUNT, INVALID_ACCOUNT, GENERAL. reason_code is the raw network/processor code.
amount_base	The amount converted to your workspace’s reporting currency (base_currency).
reply_by	The response deadline from the processor, if known.
customer	{ name, email, city, state, country } when the key has the pii:read scope, otherwise always null.

Any field can be null when the processor or your store didn’t provide it. New fields may be added over time.

List disputes

GET /v1/disputes

Scope: disputes:read. Sorted by updated_at, newest first by default. Test cases are never included.

Parameter	Description
status	One or more statuses, comma-separated, e.g. WON,LOST.
processor	One or more processors, comma-separated.
reason_category	One or more reason categories, comma-separated.
brand_id	Only disputes for this brand.
order_id	Only disputes for this order ID.
opened_after, opened_before	ISO 8601 date or timestamp. Filters on when the dispute was opened.
updated_after, updated_before	ISO 8601 date or timestamp. Filters on the last change.
order	desc (default) or asc.
limit	1–100, default 25.
cursor	next_cursor from the previous page.

Incremental sync

To keep a copy of your disputes up to date, poll with order=asc and updated_after set to the largest updated_at you’ve stored, and follow next_cursor until has_more is false:

curl -G https://app.disputedash.com/api/v1/disputes \
  -H "Authorization: Bearer $DISPUTEDASH_KEY" \
  --data-urlencode "updated_after=2026-11-05T00:00:00Z" \
  -d order=asc -d limit=100

Or, for near-real-time updates, use webhooks or the events feed.

Retrieve a dispute

GET /v1/disputes/{id}

Scope: disputes:read. Returns the dispute object plus an evidence array (see below). Evidence download_urls are only filled in when the key also has evidence:read.

List a dispute’s evidence

GET /v1/disputes/{id}/evidence

Scope: evidence:read.

{
  "object": "list",
  "data": [
    {
      "id": "e41a...",
      "object": "evidence",
      "type": "SHIPPING_DETAILS",
      "status": "GATHERED",
      "gathered_at": "2026-11-02T14:15:02.000Z",
      "updated_at": "2026-11-02T14:15:02.000Z",
      "download_url": "https://...",
      "download_expires_at": "2026-11-06T10:17:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

status is PENDING, GATHERED, FAILED, SKIPPED or NO_DATA. Only GATHERED items have a file. Download links are signed and expire after 15 minutes — request the evidence again for a fresh link rather than storing the URL. The evidence types are described in the Evidence catalog.

List brands

GET /v1/brands

Scope: disputes:read. Returns { id, object: "brand", name, created_at } for each brand in the workspace — use the id with the brand_id filter.