warranties.claims

List the comeback claims raised against the shop's warranty work

Read-onlyRead budget

REST

Shipping

POST /api/v1/warranties/claims

MCP tool

Live

warranties.claims

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

Operating contract

The claims board: work that came back. Each row carries what the customer reported, what the shop found, what it did about it, and the remedial job if one was raised.

status of open, triaged or scheduled is live work somebody has to deal with. resolved and declined are finished. status: active on the input is the shortcut for the first three, which is the list a shop actually works.

root_cause is the shop's own finding about why its work failed, and it sometimes names a responsible installer. TREAT THAT AS AN EMPLOYMENT RECORD: do not repeat it to a customer, and do not put it in a message or a document.

days_to_comeback is how long after the original job the problem appeared. It is the number the failure analysis is built on — a comeback at three days and one at three years are different stories about the same product.

schema_missing: true means this shop's database has not had the claims migration applied, so there is nothing to read and an empty list is not evidence of no claims. Say so.

READ ONLY. Raising, triaging, resolving and reopening a claim are all a person's judgement about the shop's own work, and one of the fields they set attributes a failure to a named installer.

TRUNCATION: omitted is how many further matching claims exist beyond limit. When it is not 0, narrow by status or customer rather than summarising a partial board.

Who may call it

Permission: customers.accessThe caller must hold Customers 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 claims than came back. Narrow by `status`, `customer_id` or `job_id` rather than summarising a partial board.

Input

Field	Type	Description
status	string	One claim status, `active` for open/triaged/scheduled, or `all`. Default: `"active"`One of: `open`, `triaged`, `scheduled`, `resolved`, `declined`, `active`, `all`
customer_id	stringuuid	One customer's id, as returned by customers.list or customers.get.
job_id	stringuuid	One job's id, as returned by jobs.list — claims against that work.
limit	integer1–200	How many claims to return, 1-200. Defaults to 50. Default: `50`

Output

Field	Type	Description
schema_missing	boolean	—
items	object[]	—
items[].id	string	—
items[].number	string	—
items[].status	string	—
items[].reported_at	string	—
items[].customer_report	string \| null	—
items[].root_cause	string \| null	—
items[].resolution	string \| null	—
items[].resolved_at	string \| null	—
items[].customer_id	string	—
items[].customer_name	string	—
items[].job_id	string \| null	—
items[].remedial_job_id	string \| null	—
items[].warranty_id	string \| null	—
items[].panel_codes	string[]	—
items[].days_to_comeback	number \| null	—
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/warranties/claims \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","limit":50}'

TypeScript (fetch)

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

// 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/warranties/claims",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "status": "active",
    "limit": 50
},
    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": "warranties.claims",
    "arguments": {
      "status": "active",
      "limit": 50
    }
  }
}

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