warranties.claim

Get one warranty claim with its panels and what it cost

Read-onlyRead budget

REST

Shipping

POST /api/v1/warranties/claim

MCP tool

Live

warranties.claim

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

Operating contract

ONE COMEBACK IN FULL: what the customer reported, what the shop found, which panels are named on it, who did the original work, and what putting it right actually cost.

root_cause IS THE LEARNING and it is why this read exists. installer_error, material_defect, customer_damage and unknown are four completely different conversations — one is training, one is a supplier claim, one is a chargeable repair, and one is an open question. Never assert a cause the claim has not recorded.

panels NAMES THE INSTALLER WHO DID THE ORIGINAL WORK, per panel. Handle that carefully: it is a person's name attached to a job that came back, and it belongs in a conversation about training rather than in a message to a customer.

COSTS ARE IN CENTS and labour is pay actually BOOKED against the remedial job — real ledger lines, not an estimate off an hourly rate. bonus_reversed is reported apart from the total on purpose: it is money the shop did NOT pay out, so folding it into the cost would double-count the pain.

schema_missing: true means the claims migration is not applied to this shop's database. There is then nothing to read, and an empty answer is not evidence that the shop has no comebacks.

DECIDING A CLAIM IS NOT HERE. Triaging one assigns blame to a named installer, resolving it commits the shop to a remedy, and scheduling the remedial work books a bay for free — all three are the shop's judgement about its own work.

One claim, entirely returned, so nothing is truncated.

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.

Input

Field	Type	Description
warranty_idrequired	stringuuid	The claim's own id, as returned by warranties.claims. (A claim is a warranty record — the id is the claim's, not the warranty it was raised against.)

Output

Field	Type	Description
id	string	—
number	string	—
status	string	—
reported_at	string	—
reported_via	string	—
customer_report	string \| null	—
root_cause	string \| null	—
root_cause_note	string \| null	—
resolution	string \| null	—
resolution_note	string \| null	—
resolved_at	string \| null	—
days_to_comeback	number \| null	—
customer	object	—
customer.id	string	—
customer.name	string	—
vehicle	object \| null	—
vehicle.id	string	—
vehicle.label	string	—
job	object \| null	—
job.id	string	—
job.number	number \| null	—
remedial_job	object \| null	—
remedial_job.id	string	—
remedial_job.number	number \| null	—
warranty	object \| null	—
warranty.id	string	—
warranty.number	string	—
material	object \| null	—
material.id	string	—
material.label	string	—
panels	object[]	—
panels[].panel_code	string	—
panels[].label	string	—
panels[].note	string \| null	—
panels[].original_installer	string \| null	—
cost	object	—
cost.labour_cents	number	—
cost.material_cents	number	—
cost.total_cents	number	—
cost.bonus_reversed_cents	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/claim \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"warranty_id":"9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/warranties/claim", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "warranty_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
  }),
});

// 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/claim",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "warranty_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
},
    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.claim",
    "arguments": {
      "warranty_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
    }
  }
}

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#

Input#

Output#

Examples#