payments.disputes

List the chargebacks disputing payments this shop took

Read-onlyRead budget

REST

Shipping

POST /api/v1/payments/disputes

MCP tool

Live

payments.disputes

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Payments domain.

Operating contract

THE MONEY SOMEBODY IS TRYING TO TAKE BACK. A chargeback is a customer's bank reversing a card payment, and it arrives with a deadline: evidence in by a date, or the money goes, whatever the shop can prove afterwards.

OPEN ONES FIRST, then newest first inside each group — the order a shop owner actually works the list. open_count and open_amount on the response are the whole shop's exposure, not just this page's.

total: 0 MEANS THIS SHOP HAS NEVER HAD ONE, which is a different and much better sentence than 'all resolved'. Say the right one.

amount_cents IS IN CENTS, deliberately, because it is Stripe's own figure and rounding it here would be the one place a chargeback total drifted from the bank's. Every other money field in this registry is dollars; this one is not.

reason is the bank's token — fraudulent, product_not_received, duplicate — and it decides what evidence is worth gathering. A duplicate claim is answered with the ledger; a product_not_received claim is answered with the job's completion photos and the customer's signature.

THE DEADLINE IS NOT STORED, so it is not on this list. payments.dispute reads it live from the processor for one dispute, and that is the read to make before telling anybody how long they have.

NOTHING HERE CONTESTS A DISPUTE. Submitting evidence is an argument to a bank with one shot at it, made from documents somebody has to choose — that stays a person at /invoices/disputes.

TRUNCATION: at most limit disputes come back and omitted says how many more matched.

Who may call it

Permission: invoices.accessThe caller must hold Invoices at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: readCounted against the read budget — the widest of the four.

Partial answers

omitted is how many matching records are not in the response, and 0 is a real answer meaning you have all of them. There is no cursor here — narrow the filter instead.

Do not summarise from a truncated response

When `omitted` is not 0 there are more disputes than were returned. Raise `limit`; `open_count` and `open_amount_cents` already count every open one.

Input

Field	Type	Description
status	string	Which slice: `open` (still in play), `resolved` (settled either way), or `all`. Defaults to open. Default: `"open"`One of: `open`, `resolved`, `all`
limit	integer1–100	How many to return, 1-100. Defaults to 25. Default: `25`

Output

Field	Type	Description
open_count	number	—
open_amount_cents	number	—
total_ever	number	—
items	object[]	—
items[].id	string	—
items[].status	string	—
items[].open	boolean	—
items[].reason	string \| null	—
items[].amount_cents	number	—
items[].currency	string \| null	—
items[].opened_at	string	—
items[].updated_at	string	—
items[].payment_id	string \| null	—
items[].payment_amount	number \| null	—
items[].invoice_id	string \| null	—
items[].invoice_number	number \| null	—
items[].customer_id	string \| null	—
items[].customer_name	string \| null	—
items[].funds_clawed_back	boolean	—
total	number	—
omitted	number	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/payments/disputes \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"open","limit":25}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/payments/disputes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "open",
    "limit": 25
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/payments/disputes",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "status": "open",
    "limit": 25
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "payments.disputes",
    "arguments": {
      "status": "open",
      "limit": 25
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold invoices.access.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many read calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Partial answers#

Input#

Output#

Examples#

Refusals#