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. Arrive 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.

What you build

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.getarrive.app

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.

Authentication

Send your secret key in the token request header. Authorization: Bearer … is accepted too, if your HTTP client makes that easier.

Request header

token: ak_live_9f2cA1kQ…

Key types

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.

1. Create the order

curl --request POST \
    --url https://api.getarrive.app/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"
    }'

2. Register the tracking number when it ships

curl --request POST \
    --url https://api.getarrive.app/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"]
    }'