Documentation
Protect an order in three calls.
Quote a premium while the shopper is still in the cart, send us the order when it is placed, and send the tracking number when it ships. Covr follows every scan from there and handles the claim if something goes wrong.
Overview
The Protect API is a JSON API over HTTPS. Every request is authenticated with a store-scoped API key, and every response is JSON — including errors.
There are three things to integrate, in this order. Each one is independent of the next, so you can ship them separately.
| Field | Type | Description |
|---|---|---|
| 1. Quote | checkout | Price protection for the current cart, and show the shopper the premium. Optional — you can skip straight to orders and we will price from your configured rate. |
| 2. Orders | server | Send every protected order once it reaches a final pre-fulfilment state. This is what books the premium. |
| 3. Shipments | server | Send each tracking number as you fulfil. Protection is at the order level, so every shipment on a protected order is covered. |
Base URL
https://api.covrprotection.com
Paths below are relative to it. Note that orders create and update are /v2 while cancel and every shipment route are /v1 — that mismatch is inherited deliberately so a Route integration can repoint the host and change nothing else.
The legacy api.getarrive.app host still serves the same API — an integration built before the Covr rename needs no change.
Tell us how you integrate
Five questions. Each one changes what happens on our side, and each has a default that is right for most stores and silently wrong for some. The failures they prevent do not raise errors — orders still book, premiums still look reasonable — so they are worth answering before you go live rather than after.
| Field | Type | Description |
|---|---|---|
| Browser or backend? | rate limits | Do you call us from the shopper's browser or from your server? The browser widget is limited per IP, which is per shopper. The credentialed API is limited per merchant, because a backend routes every shopper through a handful of addresses and an IP limit would cap your whole store at once. |
| Pre-tax or tax-inclusive line prices? | price_basis | Does unit_price_cents include sales tax? Send price_basis, and send tax_cents too if it is tax-inclusive. US rates exceed our comparison tolerance, so a tax-inclusive sender that does not declare it has every quote quietly rejected and every premium priced from its own figure instead of ours. |
| What SKU carries protection? | detection | We match ARRIVEINS, COVRINS, COVR-PROTECTION and ROUTEINS by SKU before falling back to matching the product title. If yours is none of those, tell us — a title-only match breaks the day someone renames the product, and the order then books as unprotected while the shopper has already been charged. |
| What else reads your order lines? | integrations | Inventory, fulfilment, ERP, accounting, 3PL. Protection arrives as a line item with no stock, no fulfilment and no cost of goods, and anything assuming every line is a real product will break on it — in one case refusing to complete the cart after the card had already been charged. |
| How do you send test orders? | mode | Test API keys persist nothing, so they need no flag. But orders pushed to our webhooks authenticate with a shared secret that says nothing about test or live — send mode: "test" for those, or a sandbox payment lands on your invoice as real receivable. |
Why we ask rather than detect
Every one of these could be guessed, and a guess that is right most of the time is the worst kind: it works until it does not, and when it does not it produces plausible numbers rather than an error. A stated answer can be checked. An inferred one cannot.
Authentication
Send your secret key in the token request header. Authorization: Bearer … is accepted too, if your HTTP client makes that easier.
token: ak_live_9f2cA1kQ…| Field | Type | Description |
|---|---|---|
| ak_live_… | live | Writes real orders, books real premium, and is what your production storefront uses. |
| ak_test_… | test | Validates and answers with correctly-shaped objects but never writes. See Test mode below. |
Keys are scoped to one store
A key identifies the store, so no endpoint takes a store identifier as an argument. Issue keys from the merchant console under Settings → API. The plaintext is shown once and never again; only a hash is stored, so a lost key is replaced rather than recovered.
Never use a secret key in the browser. The only endpoint a storefront may call directly is POST /v2/quotes, and it should be proxied through your own server.
Quickstart
The shortest path to a protected order. This skips quoting, so the premium comes from your store's configured rate.
curl --request POST \
--url https://api.covrprotection.com/v2/orders \
--header 'Content-Type: application/json' \
--header 'token: ak_live_9f2cA1kQ…' \
--data '{
"source_order_id": "11003271211",
"source_order_number": "#9929",
"subtotal": 145.00,
"taxes": 10.50,
"shipping_total": 20.00,
"order_total": 177.50,
"currency": "USD",
"insurance_selected": true,
"quote_id": "-",
"customer_details": {
"first_name": "John",
"last_name": "Smith",
"email": "jsmith@example.com"
},
"shipping_details": {
"street_address1": "1441 Innovation Way",
"city": "Lehi",
"province": "Utah",
"zip": "84043",
"country_code": "US"
},
"line_items": [
{
"source_id": "0",
"source_product_id": "213939",
"sku": "WI30301",
"name": "Basic Product 1",
"price": 50.00,
"quantity": 2,
"is_insured": true,
"image_url": "https://example.com/basic-product.jpg"
}
],
"source_created_on": "2026-08-11T09:27:35.000Z"
}'curl --request POST \
--url https://api.covrprotection.com/v1/shipments \
--header 'Content-Type: application/json' \
--header 'token: ak_live_9f2cA1kQ…' \
--data '{
"tracking_number": "9400111899223197428490",
"source_order_id": "11003271211",
"courier_id": "usps",
"source_product_ids": ["213939"]
}'