Before production intents can settle against Shopify orders, a tenant admin configures Shopify connectivity and the Shopify settlement rail prerequisites. Paybond resolves shop credentials and destinations server-side from this configuration — agents and SDK clients do not provide shop domains or offline access tokens.
This guide covers operator setup for Shopify, analogous to Configure settlement rails for Stripe and x402 providers.
Prerequisites
For conditional settlement on Shopify v1 rails, the merchant must enable manual payment capture in Shopify Admin. Without manual capture, Paybond cannot reliably drive capture or void after predicate evaluation.
Console workspace
Open Configuration → Settlement (/console/configuration/settlement) as a tenant admin.
From here you should be able to:
- Link a Shopify shop via OAuth (server-owned offline token)
- Confirm the stored shop domain (masked display)
- Enable the
shopify_authorized_orderrail when readiness prerequisites are satisfied - Enable
shopify_payments_appwhen the Payments app is installed and activated (see platform reference forshopify_payments_apprail details)
Supported Shopify rails
| Rail | What it settles | Requirement |
|---|---|---|
shopify_authorized_order | Authorized Shopify order holds captured on Harbor release; voided on predicate failure | Shopify manual capture enabled + Paybond app installed + shop linked |
shopify_payments_app | Checkout-native payment sessions via offsite extension | Paybond Payments app installed + activated in Settings → Payments + Shopify Payments Partner enrollment for extension deploy and live processing |
shopify_payments_app platform gate
The checkout-native rail requires Shopify Payments Partner enrollment (invitation-only) and a signed revenue-share agreement before the Paybond Payments extension can be deployed or process live payments. Paybond engineering and console onboarding are ready; pursue enrollment via Shopify Partner Support or existing Shopify relationships. The shopify_authorized_order rail works on dev stores today without this gate.
Step 1 — Install the Paybond Shopify app
Install the Paybond Shopify Partner App on the target shop (dev store for sandbox; production shop for live).
Step 2 — Link the shop to the tenant (OAuth)
Linking connects the Paybond tenant to the Shopify shop so Paybond can:
- verify and ingest Shopify webhooks for that shop
- execute capture/void operations via Shopify Admin APIs during terminal settlement
Security boundary
Agents must not hold Shopify offline access tokens. These are tenant-owned credentials stored and rotated server-side as part of settlement configuration.
Step 3 — Enable manual payment capture
In Shopify Admin, enable Manual payment capture (Settings → Payments). This is required for shopify_authorized_order so checkout produces an authorization that Paybond can later capture or void.
Step 4 — Validate binding metadata contract
For webhook preflight and tenant isolation, every agent-initiated checkout must include:
paybond_intent_idtenant_id
These should be written to checkout note_attributes (or cart attributes that propagate to the order). Webhooks missing binding are treated as unbound and must route to manual review.
Developer wiring: Protect Shopify payments from agents.
Step 5 — Sandbox smoke and readiness
Use the Shopify CLI workflow to validate local prerequisites and the checkout smoke contract:
terminal
paybond login
paybond shopify doctor
paybond shopify checkout smoke --shop paybond-agent-commerce-dev.myshopify.comSee Shopify CLI workflow and examples/shopify-dev-loop for the two-terminal dev harness (paybond dev trace + shopify app dev).
Legacy smoke (same Harbor contract):
terminal
paybond agent sandbox smoke \
--operation commerce.checkout \
--requested-spend-cents 4500 \
--evidence-preset cost_and_completion \
--result-body '{"status":"completed","cost_cents":4500,"order_id":"gid://shopify/Order/123","shop":"paybond-agent-commerce-dev.myshopify.com"}' \
--format table