Skip to content

Insuring Orders

Insuring a customer's order with Onward is a 3-step process:

  1. Get a Quote from Onward during checkout and add that amount to the customer's cart
  2. Create the Order with Onward after checkout is complete
  3. Keep Onward up-to-date with shipping progress

Step 1: Get a Quote in Checkout

When your customer initiates checkout, your backend calls Onward's "Get an insurance quote" endpoint with the cart total.

In response, Onward provides the price of the insurance premium and a unique token to identify this quote. Add this amount as a line item to the customer's cart and store the token as you'll need it on the next step.

Flow diagram
curl -i -X POST \
  https://app.useonward.com/api/v1/quotes \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "cart": {
      "amount_insured": {
        "cents": 1999,
        "currency": "USD"
      }
    }
  }'
Selling digital goods?

Onward's Shipping Protection only applies to physical goods that require shipping. You only need to insure the total price of shippable goods in the order and should not include digital goods in the amount_insured.

Checkout UI

You have full control over how you present the insurance premium to the customer in checkout. Some best practices include:

  • Make the benefits clear
  • Default on: the customer must opt-out of Protection
  • Show the premium price
Example of presenting Onward in your Checkout UI

Step 2: Create the Order with Onward

Once the customer has completed checkout and you have an order in your system, use the "Create an order" endpoint to send Onward the information needed to protect that order and handle customer claims. Here you'll provide the token received from the Quote API in the purchased_quote_token field.

Flow diagram
curl -i -X POST \
  https://app.useonward.com/api/v1/orders \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_order_id": "18282",
    "shop_order_number": "W-94713",
    "subtotal_price": {
      "cents": 1999,
      "currency": "USD"
    },
    "subtotal_price_presentment": {
      "cents": 1999,
      "currency": "USD"
    },
    "total_discounts_price": {
      "cents": 599,
      "currency": "USD"
    },
    "total_discounts_price_presentment": {
      "cents": 599,
      "currency": "USD"
    },
    "total_shipping_price": {
      "cents": 299,
      "currency": "USD"
    },
    "total_shipping_price_presentment": {
      "cents": 299,
      "currency": "USD"
    },
    "total_tax_price": {
      "cents": 143,
      "currency": "USD"
    },
    "total_tax_price_presentment": {
      "cents": 143,
      "currency": "USD"
    },
    "total_price": {
      "cents": 2499,
      "currency": "USD"
    },
    "total_price_presentment": {
      "cents": 2499,
      "currency": "USD"
    },
    "amount_insured": {
      "cents": 1200,
      "currency": "USD"
    },
    "amount_insured_presentment": {
      "cents": 1200,
      "currency": "USD"
    },
    "purchased_quote_token": "c0740f7e3d4718a64fd9ce18101961d210d1c61c8c8afd62f95d62d8c433347b$$qkJClv/+sWfpOfPqp4sI46PxzBuBCW4eEDKsL4q87aFhRT9mdCpIuEWwuRuvbkX4BS8=--AUnUz8WgunyUiZ4o--nnYz0Lj5WsxSqsUxtBpIIQ==",
    "created_at": "2024-11-26T17:32:28Z",
    "financial_status": "paid",
    "customer": {
      "shop_customer_id": "7461",
      "first_name": "Sally",
      "last_name": "Loo",
      "email": "sally@example.com",
      "phone_number": "+13105551234"
    },
    "shipping_address": {
      "address1": "123 Main St",
      "address2": "Unit 50",
      "province_code": "CA",
      "city": "Los Angeles",
      "postal_code": "90210",
      "country_code": "US",
      "phone_number": "+13105551234"
    },
    "line_items": [
      {
        "shop_line_item_id": "816721",
        "shop_product_id": "142",
        "shop_variant_id": "7261",
        "name": "Cool T-shirt - Red",
        "unit_price": {
          "cents": 500,
          "currency": "USD"
        },
        "total_price": {
          "cents": 1000,
          "currency": "USD"
        },
        "total_price_presentment": {
          "cents": 1000,
          "currency": "USD"
        },
        "quantity": 2,
        "image_url": "https://placecats.com/neo/300/200.png",
        "grams": 24,
        "is_insured": true,
        "refunded_quantity": 1,
        "refunded_price": {
          "cents": 500,
          "currency": "USD"
        },
        "refunded_price_presentment": {
          "cents": 500,
          "currency": "USD"
        }
      }
    ]
  }'

Step 3: Send Shipments to Onward

In order for Onward to guarantee shipping, we need to know about the shipping progress of all shipments related to an order. When you create one or many shipments for an order, use the "Create a shipment" endpoint to send that shipment information to Onward.

Flow diagram
curl -i -X POST \
  https://app.useonward.com/api/v1/shipments \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_id": "3712",
    "shop_order_id": "18282",
    "tracking_number": "780371515850",
    "tracking_url": "https://www.fedex.com/wtrk/track/?trknbr=780371515850",
    "tracking_company": "DHL Express",
    "line_items": [
      {
        "shop_line_item_id": "816721",
        "shop_product_id": "142",
        "shop_variant_id": "7261",
        "name": "Cool T-shirt - Red",
        "unit_price": {
          "cents": 500,
          "currency": "USD"
        },
        "total_price": {
          "cents": 1000,
          "currency": "USD"
        },
        "total_price_presentment": {
          "cents": 1000,
          "currency": "USD"
        },
        "quantity": 2,
        "image_url": "https://placecats.com/neo/300/200.png",
        "grams": 24,
        "is_insured": true,
        "refunded_quantity": 1,
        "refunded_price": {
          "cents": 500,
          "currency": "USD"
        },
        "refunded_price_presentment": {
          "cents": 500,
          "currency": "USD"
        }
      }
    ],
    "created_at": "2024-11-26T17:32:28Z"
  }'

And as you receive tracking updates from the courier, use the "Create a shipment event" endpoint to send those to Onward as well.

curl -i -X POST \
  'https://app.useonward.com/api/v1/shipments/{shopShipmentId}/events' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_event_id": "817391",
    "status": "in_transit",
    "message": "string",
    "estimated_delivery_at": "2024-11-26T17:32:28Z",
    "created_at": "2024-11-26T17:32:28Z"
  }'
Previous page
Next page