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

# Partner Integration Quickstart

> End-to-end walkthrough for partners building on top of OrderProtection — install an OAuth app, create A/B variants, render protection in your own UI, and consume order data.

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.

<Note>
  If you're a merchant integrating OrderProtection directly into your own storefront, see the [API integration guide](/guides/how-api-integration-works) instead. This page is specifically for **third-party partners** building products on top of OrderProtection.
</Note>

## How it fits together

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Partner as Partner backend
    participant OP as OrderProtection API
    participant Shopper as Shopper (in partner UI)
    participant Store as Merchant storefront

    Note over Partner,OP: One-time setup
    Partner->>OP: POST /v1/oauth/token (exchange code)
    OP-->>Partner: access_token (op_at_...)
    Partner->>OP: POST /v2/settings/context (variantKey: "A")
    Partner->>OP: POST /v2/settings/context (variantKey: "B")
    OP-->>Partner: contexts created

    Note over Shopper,OP: Per-shopper render
    Shopper->>Partner: Loads page in partner UI
    Partner->>Partner: Decide variant for this shopper
    Partner->>OP: GET /v1/quote/insurance<br/>x-op-partner-app-id, x-op-partner-variant
    OP-->>Partner: Resolved settings + pricing<br/>(merchant defaults overlaid with variant)
    Partner-->>Shopper: Render protection UI

    Note over Store,Partner: Post-purchase
    Store->>OP: Order placed (via merchant integration)
    OP->>Partner: webhook: protection.added / claim.created
    Partner->>OP: GET /v1/orders/{id} (as needed)
```

## 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](/developer/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](/developer/scopes) for the full list.

## Step 2 — Get an access token

Follow the [OAuth flow](/developer/authentication) to exchange an authorization code for an access token. From here, every API call uses:

```bash theme={null}
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:

```bash theme={null}
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](/developer/endpoints#partner-contexts) for the full CRUD reference.

<Tip>
  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.
</Tip>

## Step 4 — Route each shopper to a variant

On the shopper-facing path, call the **public widget read** with two headers:

```bash theme={null}
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"
```

| Header                 | Value                                             |
| ---------------------- | ------------------------------------------------- |
| `x-op-partner-app-id`  | Your OAuth `Application.id`                       |
| `x-op-partner-variant` | The `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`](/developer/endpoints#quote) to get a single customer/brand split for any subtotal:

```bash theme={null}
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](/api-reference/orders/get-all-orders) and [Claims](/api-reference/claims/get-claims) APIs (requires `read_orders` / `read_claims`).
* **Subscribe to webhooks** — `protection.added`, `protection.removed`, `claim.created`, `claim.approved`, `claim.denied`, `message.created`. See [Webhooks](/developer/webhooks) and the [event reference](/webhooks/introduction).

<Note>
  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.
</Note>

## Where to go next

<CardGroup cols={2}>
  <Card title="Partner endpoints reference" icon="key" href="/developer/endpoints">
    Full schema reference for every `/v2` partner endpoint, including request/response shapes and scope requirements.
  </Card>

  <Card title="Authentication" icon="lock" href="/developer/authentication">
    OAuth flows, refresh tokens, and PKCE.
  </Card>

  <Card title="Scopes" icon="shield-halved" href="/developer/scopes">
    Full list of scopes, including admin-gated pricing scopes.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer/webhooks">
    Subscribe to claim, order, and protection events.
  </Card>
</CardGroup>