Checkout Extension

​

Prerequisites

• An approved OAuth app — see Creating an app. Note your Application.id (looks like cmpn5in6p000484flmfk9ns4d).
• A partner context created for the merchant’s store — see Quickstart, Step 3.
• A price set (Step 4) and a widget config (Step 5) created for each cohort, keyed by your variantKey.
• The checkout-widget extension installed on the store — see below.

​

How the extension gets installed

​

Configure the block settings

​

Runtime cohort binding (cart attributes)

​

Session lifecycle

1. Setup, once per store: the checkout-widget block is added with Application ID set and both variant-key fields empty. One checkout-widget block — no per-variant blocks, and no checkout-editor changes per test.
2. Per test, API only: create a price set and a CHECKOUT widget config per variantKey. A control arm is a variantKey whose price set has noOp: true.
3. Per session: the widget renders nothing while it waits, and makes no cohort pricing or widget-config requests for a surface until that surface’s key exists. When your extension allocates, it writes both attributes — the widget stays hidden until both exist.
4. The widget fetches that cohort’s pricing and widget config from the partner endpoints below, renders, and applies the cohort’s auto-add behavior. A noOp cohort renders nothing and removes any protection line.
5. Re-allocation mid-session is supported — the widget refetches and, on toggle-layout cohorts, swaps the protection line (tile-layout cohorts keep the existing line until the buyer interacts) — but it never re-runs the auto-add decision (a buyer’s explicit choice is not overridden). Don’t clear the attributes after allocating, and never express the control arm by not writing them: always allocate explicitly, so “not allocated yet” and “control” stay distinguishable.
6. Cart attributes become note attributes on the resulting Shopify order (standard Shopify behavior), so the cohort keys are available in order payloads and webhooks for your per-order test attribution.

​

Rules and edge cases

• Write both attributes at allocation time. One without the other keeps the widget hidden.
• Don’t half-fill the block settings. Application ID with only one variant-key field filled leaves the other surface waiting for an attribute that may never come, so the widget stays hidden. Fill both fields (static mode) or neither (runtime mode).
• Invalid values are treated as absent (client-side validation against the key pattern), falling back to the block-setting value if one exists, otherwise back to the hold.
• Attributes override filled block settings when both are present. But leave the fields empty on runtime checkouts: a filled field pins a cohort that renders immediately on page load and then swaps when the allocation lands — the hold only engages when the fields are empty. Filled fields are useful for debugging a cohort statically, not for live tests.
• Missing cohort data falls back visibly, per surface: a key with a widget config but no SHIPPING price set renders the cohort’s appearance with the store’s merchant fallback pricing (the pricing fetch 404s); a key with a price set but no CHECKOUT widget config renders the merchant’s appearance with cohort pricing. If either half looks wrong during setup, check both resources exist for that exact variantKey.
• Wallet checkouts (Apple Pay, Google Pay) reject extension cart changes — attribute writes and protection line-adds alike — so protection can’t be sold in those sessions by any binding mode; in runtime mode they simply stay unallocated and hidden. Shop Pay is expected to work — it’s the full checkout surface, and buyer details arriving prefilled means allocation can fire immediately — but it hasn’t been verified end-to-end yet.
• Unallocated sessions stay hidden indefinitely by design. The partner owns allocation reliability; there is no timeout fallback to a default widget.

​

Impression signal (write-back)

• _op_rendered present — the impression happened. Treat this as authoritative even if a stale reason briefly coexists (the retraction is best-effort).
• Reason present, no _op_rendered — the widget ran and declined; the value says why. no_op is your control arm working correctly, not a failure.
• Neither appears — the widget never ran: missing block, misconfigured checkout, broken extension, or a wallet flow. This is the setup-problem signal, and it works precisely because it’s an absence — a missing renderer can’t self-report.

​

What the extension fetches

​

Pricing — GET /v2/quote/insurance/partner/:applicationId

curl -G https://api.production.orderprotection.com/v2/quote/insurance/partner/cmpn5in6p000484flmfk9ns4d \
  --data-urlencode "key=test-a" \
  --data-urlencode "store_url=example.myshopify.com" \
  --data-urlencode "country=US"

• 400 Bad Request — key is missing, or applicationId/key don’t match the partner key format.
• 404 Not Found — the store isn’t found, the app isn’t installed, or the cohort has no SHIPPING pricing rules.

​

Widget config — GET /v2/widget/config/partner/:applicationId

curl -G https://api.production.orderprotection.com/v2/widget/config/partner/cmpn5in6p000484flmfk9ns4d \
  --data-urlencode "key=test-a" \
  --data-urlencode "store_url=example.myshopify.com" \
  --data-urlencode "type=CHECKOUT"

{
  "id": "cmokr9v3t000284gkq2m8xw1e",
  "type": "CHECKOUT",
  "status": "ACTIVE",
  "variant": "test-a",
  "name": "Cohort A — flat-rate",
  "config": { "...": "schemaless widget configuration — the renderer validates on read" },
  "customizationValues": { "...": "read-only mirror of config, for legacy consumers" },
  "updatedAt": "2026-05-26T18:46:25.987Z"
}

• 400 Bad Request — key is missing, or applicationId/key don’t match the partner key format.
• 404 Not Found — the store isn’t found, the app has no active context on that store, or no widget config exists for that (variantKey, type).

​

Default vs. cohort render

​

Next steps