Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orderprotection.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide is for partners who render OrderProtection’s protection product on their own surface — for example, a third-party post-purchase platform that wants to show protection offers inside its own checkout or thank-you flow. By the end you’ll be able to:
  1. Authenticate against the OrderProtection API.
  2. Create one or more A/B-test “variants” with custom settings and pricing.
  3. Render the right variant to each shopper.
  4. Consume order and claim events as they happen.
If you’re a merchant integrating OrderProtection directly into your own storefront, see the API integration guide instead. This page is specifically for third-party partners building products on top of OrderProtection.

​
How it fits together

​
Step 1 — Register your OAuth app

Create an app in the OrderProtection dashboard and capture the client_id and client_secret. See Creating an app for the full walkthrough. When you declare scopes, request at minimum:
  • read_store — read merchant settings
  • write_settings — create and update your partner contexts
  • read_quotes — call POST /v2/quote
  • read_orders — read order data placed on the merchant’s store
Add read_widget_cart, read_widget_checkout, or any pricing scopes if you also need those resources. See the Scopes reference for the full list.

​
Step 2 — Get an access token

Follow the OAuth flow to exchange an authorization code for an access token. From here, every API call uses: 
Authorization: Bearer op_at_...

​
Step 3 — Create one or more variants

A partner context is your A/B-test cohort. It stores sparse overrides on top of the merchant’s default settings — fields you don’t override are inherited. Create one variant per arm of your test: 
curl -X POST https://api.production.orderprotection.com/v2/settings/context \
  -H "Authorization: Bearer op_at_..." \
  -H "Content-Type: application/json" \
  -d '{"variantKey": "experiment_a", "name": "Variant A — auto-add on"}'
The variantKey is a stable identifier you’ll use at render time to route a shopper into the variant. See Partner contexts for the full CRUD reference.
You don’t have to override every field. Anything you leave unset is inherited from the merchant’s defaults, which means a shopper still gets a working protection product even if your variant only overrides one field.

​
Step 4 — Route each shopper to a variant

On the shopper-facing path, call the public widget read with two headers: 
curl -G https://api.production.orderprotection.com/v1/quote/insurance \
  --data-urlencode "store_url=example.myshopify.com" \
  --data-urlencode "country=US" \
  -H "x-op-partner-app-id: app_ghi012" \
  -H "x-op-partner-variant: experiment_a"
HeaderValue
x-op-partner-app-idYour OAuth Application.id
x-op-partner-variantThe variantKey of the context you want to apply
The response is the merchant’s settings + pricing with your variant’s overrides layered on top. If either header is missing, malformed, or the merchant has uninstalled your app, the response silently falls back to merchant defaults — public widget reads must never crash a checkout.

​
Step 5 — Render protection in your UI

Use the resolved settings to drive your UI. For an arbitrary cart, you can also call the stateless POST /v2/quote to get a single customer/brand split for any subtotal: 
curl -X POST https://api.production.orderprotection.com/v2/quote \
  -H "Authorization: Bearer op_at_..." \
  -H "Content-Type: application/json" \
  -d '{"orderTotal": 49.99, "policyType": "SHIPPING"}'

​
Step 6 — Consume order and claim events

When a shopper buys protection on the merchant’s storefront, the order flows into OrderProtection through the merchant’s existing platform integration (Shopify, BigCommerce, etc.). You do not push orders to OrderProtection — we already have them. To stay in sync, you can either:
  • Read on demand via the v1 Orders and Claims APIs (requires read_orders / read_claims).
  • Subscribe to webhooks — protection.added, protection.removed, claim.created, claim.approved, claim.denied, message.created. See Webhooks and the event reference.
Order data is owned by the merchant. Your access depends on the merchant having installed your app and granted the relevant scopes — there is no way to read orders for a store that hasn’t installed you.

​
Where to go next

Partner endpoints reference

Full schema reference for every /v2 partner endpoint, including request/response shapes and scope requirements.

Authentication

OAuth flows, refresh tokens, and PKCE.

Scopes

Full list of scopes, including admin-gated pricing scopes.

Webhooks

Subscribe to claim, order, and protection events.