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.Authenticated The response examples on this page show the
/v2 endpoints wrap every success response in a standard envelope: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 avariantKey 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
partner-context:update
Request body:
Example:
201 Created:
409 Conflict — there is one context per (store, app). Fetch the existing one with the list endpoint below.
List your contexts
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)
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
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:
200 OK: Same shape as GET /v2/settings/context/:id.
Delete a context
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 byvariantKey. 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
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:
201 Created:
(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
403.
Response 200 OK: Array of rule sets, same shape as the create response.
Get a cohort price set
id whose type you can’t read returns 404 (existence is hidden).
Update a cohort price set
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
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 byvariantKey. 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
Example:
201 Created:
(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
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 defaultGeneralSetting, read-only for partners.
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 onlypricing: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
200 OK:
Update a ruleset
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:
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
quote:read
Request body:
Each line item:
orderTotal or lineItems must be present. If both are sent, lineItems wins and orderTotal is ignored.
Example:
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
200 OK:
Update a widget config
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.
/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.
