Skip to main content
This page lists every endpoint your app can call with an OAuth access token. Each entry includes the route, the scopes it requires, the request shape, and the response shape.
Routes documented here are versioned under /v2. The /v1 quote endpoint remains available for the public widget and is documented at the end of this page. The /v1 OAuth and install routes partners also call (/v1/oauth/token, /v1/oauth/authorize/approve, /v1/auth/login) are documented in Installing Your App and the API Reference; the rest of /v1 is dashboard-only. The public, unauthenticated cohort endpoints the checkout extension calls (/v2/quote/insurance/partner/:applicationId and /v2/widget/config/partner/:applicationId) are documented in the Checkout Extension guide.
All requests must include a Bearer access token from the OAuth flow:
Authenticated /v2 endpoints wrap every success response in a standard envelope:
The response examples on this page show the data payload only. The public reads (/v1/quote/insurance and the /v2/.../partner/:applicationId endpoints) are not wrapped.

Base URL

At a glance


Partner contexts

A partner context is your app’s installation container on a store — one per (store, app) pair. It holds optional sparse overrides on the merchant’s default settings (fields you don’t override are inherited), and your A/B cohorts hang off it as child resources keyed by a variantKey you choose: cohort price sets and cohort widget configs. This is the primitive that powers parallel partner A/B testing without disturbing the merchant’s defaults.

Create a context

Required scope: partner-context:update Request body: Example:
Response 201 Created:
Creating a second context on the same store returns 409 Conflict — there is one context per (store, app). Fetch the existing one with the list endpoint below.

List your contexts

Required scope: store:read Returns only the contexts owned by the calling OAuth app for this store. Response 200 OK:

Get a context (with merged settings for a cohort)

Required scope: store:read Returns the context metadata plus the resolved settings and pricing rules for the supplied cohort — the same view a shopper assigned to that variantKey would see. Merchant defaults are layered first; partner overrides for non-null fields are layered on top. If the cohort has its own price sets they’re returned; otherwise the merchant’s rule sets are. Response 200 OK:
This endpoint does not consult the OAuth-app installation off-switch. The OAuth gate already authorises the calling app to read its own context. The off-switch only fires on the public widget read path.

Update a context

Required scope: partner-context:update (+ store-credit:update if any store-credit field is present) Every field is optional. Sparse semantics: fields you omit stay inherited from the merchant; fields you send become partner overrides. Overrides are installation-wide (one context row per store + app) — the variantKey query param only selects which cohort’s pricing the response renders. Request body: Example:
Response 200 OK: Same shape as GET /v2/settings/context/:id.

Delete a context

Required scope: partner-context:update Soft-deletes the context. Future shopper traffic resolving against any variantKey for this (store, app) falls back to merchant defaults at the resolver. Response 200 OK:

Cohort pricing

Per-cohort price rule sets, attached to your partner context and keyed by variantKey. On the header-based v1 read path, a cohort with no partner price set falls back to the merchant’s default pricing; the path-based /v2/.../partner/... endpoints return 404 instead (the checkout extension treats that as “no cohort” and renders the store default). All writes require the base scope partner-context:update plus the per-type scope below. Reads require the per-type read scope.
All pricing scopes are admin-gated — see Scopes → Price Settings.

Create a cohort price set

Request body: Each rule:
min/max are cart-subtotal bounds. type is fixed or percentage. Both customer and brand are optional but at least one is typically present. Example:
Response 201 Created:
One rule set per (variantKey, type) — creating a duplicate returns 409 Conflict. To repoint a cohort at different pricing, delete the rule set and create a new one.

List cohort price sets

Returns the context’s rule sets across all cohorts. The response includes only the types you hold a matching read scope for (others are silently filtered). A token with no matching read scope at all gets 403. Response 200 OK: Array of rule sets, same shape as the create response.

Get a cohort price set

Requires the read scope matching the rule set’s type. An id whose type you can’t read returns 404 (existence is hidden).

Update a cohort price set

Same body as create, minus variantKey (immutable). type is accepted for round-trip ergonomics but must match the existing value — changing it returns 400. Omitted fields preserve their existing values. Response 200 OK: The updated rule set.

Delete a cohort price set

Hard-deletes the rule set and its rules. The path-based partner endpoints then return 404 for that cohort (the checkout extension falls back to the store default); the v1 header read path falls back to merchant pricing. Response 200 OK:

Cohort widget configs

Per-cohort widget configuration, attached to your partner context and keyed by variantKey. This is what the checkout extension renders when a checkout’s block settings point at your cohort. All writes require the base scope partner-context:update plus the per-type scope below. Reads require the per-type read scope.

Create a cohort widget config

Request body: Example:
Response 201 Created:
One config per (variantKey, type) — a duplicate returns 409 Conflict. CHECKOUT, CART, and INFO_MODAL configs can coexist under the same variantKey because they differ on type.
Write your configuration to config only. customizationValues is a legacy read-only mirror kept in lockstep server-side — sending it in a request body is rejected. For checkout rendering, use the field vocabulary shown in the Quickstart, Step 5 — the checkout extension renders a defined subset of the schema (copy, colors, borders, disclaimer, and layout fields).

List cohort widget configs

Returns the context’s widget configs across all cohorts, filtered to the types you hold a read scope for. A token with no matching read scope at all gets 403.

Get / update / delete a cohort widget config

PUT accepts status, variant, name, and config (same strict schema; variantKey and type are immutable — delete and recreate to repoint a cohort). An id whose type you can’t access returns 404. DELETE hard-deletes.

Merchant settings

The merchant’s default GeneralSetting, read-only for partners.
Required scope: store:read Response 200 OK:
updatedByApplicationId reflects the OAuth application that last wrote these settings, or null if the most recent write was made through the OP dashboard.
There is no partner write path for merchant defaults — the former PUT /v2/settings endpoint has been removed. Partner setting overrides are written per-installation via PATCH /v2/settings/context/:id, leaving the merchant’s defaults untouched.

Pricing rules (merchant)

The merchant’s default rule sets, readable and writable with per-ruleset-type scopes. A token with only pricing:shipping-insurance:read will see only SHIPPING rulesets; the others are silently filtered out (not 403’d) so a single token can be used for multiple resource types without surfacing access errors.
All pricing scopes are admin-gated — see Scopes → Price Settings. For A/B testing, prefer cohort price sets — writing here changes pricing for every shopper outside a partner cohort.

List pricing rules

Required scope: any of the per-type read scopes above. The response includes only the rulesets you have a matching read scope for. Response 200 OK:

Update a ruleset

Required scope: matching write scope for the ruleset’s type. Passing an id whose type you don’t have a write scope for returns 404 (existence is hidden). Request body: Each rule:
type is one of fixed or percentage. Both customer and brand are optional but at least one is typically present. Example:
Response 200 OK: Array containing the updated ruleset, same shape as GET /v2/pricing/rules.
ISO codes are normalised to upper case server-side, so "ca" and "CA" are equivalent on writes. Reads always return uppercase.

Quote

A stateless protection quote computation. Use this to preview the customer/brand split for a given subtotal before writing it into a cart.

Generate a quote

Required scope: quote:read Request body: Each line item:
At least one of orderTotal or lineItems must be present. If both are sent, lineItems wins and orderTotal is ignored. Example:
Response 201 Created:

Widget config (merchant)

The merchant’s default widget configs, with per-widget-type scopes. As with pricing, a narrow token only sees the widget types it can read; the rest are silently filtered.
For A/B testing, prefer cohort widget configs — writing here changes the widget for every shopper outside a partner cohort.

List widget configs

Required scope: any of the per-type read scopes. Response 200 OK:

Update a widget config

Required scope: matching write scope for the widget’s type. As with pricing, an id whose type you can’t write returns 404 — existence and scope are not distinguishable. Request body: Response 200 OK: Same shape as a single entry in GET /v2/widget/config.

Public widget read (with cohort)

The shopper-facing widget read path (GET /v1/quote/insurance) is unauthenticated, but it accepts two optional headers that route the read to a partner context. This is useful for verifying cohort resolution and for surfaces where OrderProtection’s rendering reads through the v1 path. Both headers must match ^[a-zA-Z0-9_.:-]{1,64}$. If either is missing, malformed, or the indicated context doesn’t exist for this store, the response silently falls back to merchant defaults — public widget reads must never crash a checkout. The off-switch fires when the OAuth app has been uninstalled (or never installed) on the store: in that case the cohort headers are ignored and the merchant’s defaults are returned. Install / uninstall events propagate within seconds via Kafka and bust the install-status cache, but already-cached cohort responses (the public reads are cached for up to an hour) can keep serving until their TTL expires.
The response follows the existing /v1/quote/insurance documentation, with the resolved settings + pricing swapped for the cohort’s. When a cohort resolves, the response additionally carries source, partnerApplicationId, and partnerVariantKey so you can confirm which cohort was applied.
The Shopify checkout extension uses the path-based public endpoints instead (/v2/quote/insurance/partner/:applicationId and /v2/widget/config/partner/:applicationId) — those throw 400/404 rather than silently falling back, and are documented in the Checkout Extension guide.

Error responses

Standard JSON error envelope (same as the rest of the OrderProtection API):