API ReferenceLive

Shipping Insurance API

Quote a premium, insure a shipment, and file a claim — all from your backend, with the same key as the Tracking API.

POST/v1/insurance/policy

Insure a shipment for its declared value. Call it server-to-server once you have a carrier tracking number for an order. Returns the policy id and premium. (See the quickstart below for quotes and claims too.)

💡

Rate limit

120 requests per minute per API key (shared across all APIs, falling back to per-IP for unauthenticated attempts). Exceeding it returns 429. Rate-limit headers follow the IETF draft-7 standard, so you can read RateLimit-Remaining / RateLimit-Reset to pace your calls.

Prerequisites

A ShipSlip account

You need an active ShipSlip account to generate an API key and insure shipments.

Create one at shipslip.com/create-account — no credit card required to generate a key.
Coverage and claim eligibility follow the Protect product terms; see Protect.

An API key

Generated in Dashboard → Settings → API Keys (admin only).
Format: sk_live_…. The same key works for the Tracking API.

A policy before a claim

Claims attach to a policy. Buy a policy with <code>POST /v1/insurance/policy</code> first and keep the returned <code>id</code> — you pass it as <code>policy_id</code> when filing a claim.

A policy must be active to accept a claim.
Lost and missing-content claims require a 20-day waiting period from the ship date.

Environment

Base URLs. All endpoints are relative to these.

Environment	Base URL	Notes
Production	`https://shipslip.com/api`	Use your sk_live_… key.

Authentication

Every request must send your API key as a Bearer token:

Authorization header

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

💡

One key for every API

The Shipping Insurance API uses the same account-wide key as the Tracking API. Generate or rotate it in the portal: Dashboard → Settings → API Keys. Only an admin can generate or regenerate a key. The full key is shown once at creation — we store only a fingerprint — so copy it immediately.

⚠️

Keep your key secret

The key grants access to your company account across all APIs. Store it in a server-side secret manager or environment variable — never commit it to a repository or expose it in browser/mobile code. Regenerating a key immediately invalidates the previous one.

Quickstart

Quote, insure, and claim

The three endpoints share the same key and snake_case contract. Quote a premium (nothing is created), buy a policy for a shipment, then file a claim against that policy using its id.

Request

cURL

# 1) Quote a premium — nothing is charged or created
curl -X POST https://shipslip.com/api/v1/insurance/quote \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "item_value": 250 }'

# 2) Buy a policy — keep the returned "id"
curl -X POST https://shipslip.com/api/v1/insurance/policy \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "fedex",
    "tracking_number": "784122900163",
    "order_number": "38241",
    "order_date": "2026-07-01",
    "ship_date": "2026-07-02",
    "item_value": 250
  }'

# 3) File a claim against the policy
curl -X POST https://shipslip.com/api/v1/insurance/claims \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "9b1c…",
    "claim_type": "damaged",
    "discovery_date": "2026-07-10",
    "description": "Box crushed in transit."
  }'

Response 201

200 / 201 response

{
  "id": "9b1c…",
  "premium": 3,
  "status": "active",
  "carrier": "fedex",
  "tracking_number": "784122900163",
  "order_number": "38241",
  "item_value": 250
}

✅

Good to know

Premium is $1 per $100 of declared value, rounded up (so $250 → $3), capped at $1000 of coverage. POST /v1/insurance/quote returns the same premium with 200 and creates nothing; POST /v1/insurance/claims returns 201 with the new claim id.

Endpoint reference

Request body

Field	Type	Required	Description
`carrier` e.g. "fedex"	string (enum)	Required	The shipping carrier. One of: fedex, ups, usps.
`tracking_number` e.g. "784122900163"	string	Required	The carrier tracking number for the shipment.
`order_number` e.g. "38241"	string	Required	Your internal order/reference number for the shipment.
`order_date` e.g. "2026-07-01"	string (date)	Required	When the order was placed, as YYYY-MM-DD.
`ship_date` e.g. "2026-07-02"	string (date)	Required	When the shipment was dispatched, as YYYY-MM-DD. The 20-day trace wait for lost/missing claims counts from this date.
`item_value` e.g. 250	number	Required	Declared value of the insured item in USD. Must be greater than 0 and at most 1000.

Where to find things in the portal

Screens you'll use to get set up and see the results of your calls.

**Dashboard → Settings → API Keys** — Generate, reveal, copy, and regenerate your account API key. The same key authenticates the Tracking and Shipping Insurance APIs.

**Dashboard → Protect** — Policies and claims created via the API appear here, where your team can review claims and attach evidence.

Errors

Errors return the appropriate HTTP status with a JSON body of the shape { "error": "…" }.

Status	Reason	What it means / how to fix
400	`Request body must be a JSON object`	The body was missing or not valid JSON. Send Content-Type: application/json with a JSON object.
400	`Missing or invalid fields`	One or more required fields were missing or invalid. The response includes a "fields" array naming them (e.g. item_value, tracking_number).
400	`carrier must be fedex, ups, or usps`	The carrier field was missing or not a supported value. Use one of the three supported carriers (case-insensitive).
400	`Maximum coverage is $1000`	item_value exceeded the $1000 coverage cap. Lower the declared value or split the shipment.
400	`claim_type must be lost, damaged, or missing`	The claim_type field was missing or not a supported value.
400	`trace_initiated_date is required for lost/missing claims`	Lost and missing claims require a trace_initiated_date (YYYY-MM-DD). The response lists it in "fields".
401	`Missing or invalid Authorization header`	No Bearer token was sent. Add the header: Authorization: Bearer <your key>.
401	`Invalid API key`	The key is wrong, revoked, or from the other environment. Regenerate it in the portal if unsure.
404	`Insured shipment not found`	No policy matched the policy_id (or tracking_number) for your company. Buy a policy first and pass its id.
409	`This policy is no longer active`	The policy has been cancelled or already claimed. Claims can only be filed against an active policy.
409	`Lost and missing content claims require a 20-day waiting period from the ship date.`	You filed a lost/missing claim before 20 days elapsed since the ship date. The response includes days_remaining.
429	`Too many requests. Please slow down and try again shortly.`	You exceeded the rate limit. Back off and retry; batch or throttle your calls.

Common issues

404 Insured shipment not found on a claim

Claims resolve a policy by policy_id (preferred) or tracking_number, scoped to your company.

Use the id returned by POST /v1/insurance/policy as policy_id.
If you pass only tracking_number, it resolves your most recent active policy for that number — make sure one exists.

409 waiting period on a lost/missing claim

Lost and missing-content claims can only be filed once 20 days have passed since the shipment’s ship_date.

The response includes days_remaining — retry after that many days.
Damaged claims have no waiting period and can be filed as soon as the damage is discovered.

400 Maximum coverage is $1000

Each policy covers up to $1000 of declared value.

For higher-value shipments, split the declared value across shipments or contact support about custom coverage.

Adding evidence to a claim

The public API creates claims with metadata only. Upload photos and documents (proof of value, damage, carrier trace) from the portal.

Open the claim in Dashboard → Protect and attach files there.