warranties.claim_insights

Break the shop's warranty claims down by cause and outcome

Read-onlyExpensive budget

REST

Shipping

POST /api/v1/warranties/claim_insights

MCP tool

Live

warranties.claim_insights

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

Operating contract

What the shop's comebacks add up to over a window: how many, what caused them, how they were resolved, and how long after the original work they appeared.

THIS IS ABOUT THE SHOP'S OWN WORK, not about any customer. It is the read behind 'are we getting better' and 'is one product failing more than another'.

by_root_cause is the interesting cut and it separates two very different things: a material that failed and an install that did. Report which, because they lead to different actions — a supplier conversation or a training one. by_panel and by_material are the same question asked of the car and of the product.

COSTS ARE ATTRIBUTED WHOLE TO EVERY BUCKET A CLAIM BELONGS TO, deliberately. A comeback naming the hood and both fenders cost what it cost, and splitting it three ways would understate the hood's real burden on each row. So the rows answer 'how much has this panel cost me' and their sum legitimately EXCEEDS total_cost — do not add them up and report the result as a total.

A small window produces small numbers, and a rate computed from three claims is noise. Say the count alongside any percentage.

schema_missing: true means the claims migration has not been applied here, so there is nothing to analyse — an empty result is not a claim-free shop.

This is a rollup over every claim in the window, 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: expensiveCounted against the expensive budget — a model call, a document render or a fan-out scan.

Input

Field	Type	Description
days	integer7–1095	How many days back to analyse, 7-1095. Defaults to 365. Default: `365`

Output

Field	Type	Description
schema_missing	boolean	—
window_days	number	—
total_claims	number	—
open_claims	number	—
total_cost	number	—
average_cost	number	—
currency	string	—
by_root_cause	object[]	—
by_root_cause[].key	string	—
by_root_cause[].label	string	—
by_root_cause[].claims	number	—
by_root_cause[].cost	number	—
by_panel	object[]	—
by_panel[].key	string	—
by_panel[].label	string	—
by_panel[].claims	number	—
by_panel[].cost	number	—
by_material	object[]	—
by_material[].key	string	—
by_material[].label	string	—
by_material[].claims	number	—
by_material[].cost	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_insights \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":365}'

TypeScript (fetch)

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

// 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_insights",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "days": 365
},
    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_insights",
    "arguments": {
      "days": 365
    }
  }
}

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