What each API is for

warrantini models one thing — a specific unit somebody bought, and what you owe them for it. Every resource below is a step in getting from a purchase to that obligation, and then to a claim against it. The endpoints make more sense once the chain does.

The chain, in one paragraph

An order arrives, carrying line items. A warranty rule decides which of those line items are covered and for how long. That decision, applied to one line item, becomes a registration — the coverage record. When something goes wrong, the customer files a claim against that registration. Products are the catalogue the rules match against.

If you only remember one thing: a registration is not an order and not a product. It is the coverage on one unit, and it is the thing claims attach to.

Order

A customer's purchase, with its line items. Orders arrive one of three ways: a direct connector (Shopify), a connector-platform sync, or POST /api/v1/orders from your own system.

An order is evidence, not coverage. Ingesting one grants nobody anything — it is the record that lets warrantini answer *did this person actually buy this, and when*. The purchase date is what coverage windows are measured from, which is why ordered_at matters more than when you happened to send it.

• IDs are prefixed ord_.
• external_id is yours, and it is what makes ingestion idempotent — re-posting the same one upserts rather than duplicating.
• Orders carry customer_email, which is how the customer later finds their own coverage in the portal.

Line item

One product on one order, prefixed oli_. This is the level everything real happens at: rules match line items, and registrations are created per line item, not per order. A three-item order can produce three registrations with three different coverage lengths.

The one field you must get right is the upstream identifier. Persist the source platform's own line-item ID, never a synthetic one your integration invented and never a connector's internal ID. Coverage is resolved against it for the entire life of the warranty — one to ten years — so an identifier that changes when you swap systems orphans every warranty behind it, silently and without an error anywhere.

Product

Your catalogue, prefixed prd_. Products are not decoration and ingestion is not complete without them: rules match on sku, product_type, category and vendor, and those live on the product. Orders without products means no rule can match, which means no coverage term.

Warranty rule

The policy, expressed as data rather than code. A rule is include or exclude, carries match conditions, and sets coverage_months — null meaning lifetime. Prefixed wru_.

Rules are read-only over the API (rules:read). They are written in the dashboard, deliberately: a rule change silently re-terms future coverage, and that is a decision a merchant makes with their eyes open, not something an integration drifts into.

Registration

The coverage record — the centre of the model, prefixed reg_. It binds a customer, a line item, a rule, and a window (coverage_starts to coverage_ends, the latter null for lifetime).

Its status is the answer to *is this covered right now*:

• active — in force.
• expired — the window passed.
• voided — cancelled, typically by a refund.
• replaced — superseded by a replacement unit's registration.
• rejected — a self-attested claim of ownership that was refused.
• pending_review — a self-attested registration awaiting a human. It never auto-promotes to active, and claims against it are blocked from AI auto-resolution regardless of confidence.

is_self_attested is true when a customer asserted ownership without a matching order — no receipt. Treat it as lower-trust in your own logic; the platform already does.

Claim

A request made against a registration, prefixed clm_. Claims never attach to an order or a product directly — always to the coverage record, because that is the thing that says whether they are entitled to anything.

status runs submitted → in_review → one of approved / rejected, with info_requested and escalated as side states. Transitions are validated: you cannot jump the state machine, and an illegal move returns 422 with an invalid-transition type rather than quietly succeeding.

resolution_type (repair, replace_part, replace_full, refund) is what was decided, and is_return_required is whether the unit has to come back before it happens.

Where each one is written from

Not everything is writable over the API, and the split is intentional rather than incidental.

• You write: orders, products (ingestion), registrations, claims.
• The dashboard writes: warranty rules, webhook endpoints, API keys.
• The platform writes: registration expiry, AI triage outcomes, claim escalation.

So an integration's normal job is: keep orders and products current, and read registrations and claims. Creating registrations directly is for the cases where no order exists to derive one from.

A first look at the chain

Two reads that show the model better than any diagram — an order with its line items, then the coverage that came out of it.

# The purchase
curl -s https://api.warrantini.com/api/v1/orders/ord_01hxyz \
  -H "Authorization: Bearer $WARRANTINI_API_KEY"

# The coverage it produced
curl -s "https://api.warrantini.com/api/v1/registrations?limit=10" \
  -H "Authorization: Bearer $WARRANTINI_API_KEY"

Next: Authentication and your first request for keys and scopes, or Ingesting orders and products if you are pushing data in from your own system.