paybondpaybond
Sign in

Integration · Shopify

Beta Preview

Configure Shopify settlement

Tenant-admin guide: link a Shopify shop to Paybond, enable manual capture, and prepare the shopify_authorized_order rail for conditional settlement.

  • OAuth link
  • manual capture
  • shopify_authorized_order
  1. 01Connect
  2. 02Configure
  3. 03Verify
  4. 04Go live

In short: this links a Shopify store so Paybond can hold and release the order's payment until the completion rule passes. 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.

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_order rail when readiness prerequisites are satisfied
  • Enable shopify_payments_app when the Payments app is installed and activated (see platform reference for shopify_payments_app rail details)

Supported Shopify rails

RailWhat it settlesRequirement
shopify_authorized_orderAuthorized Shopify order holds captured on proof-gated release; voided on predicate failureShopify manual capture enabled, Paybond app installed, and shop linked
shopify_payments_appCheckout-native payment sessions via offsite extensionPaybond Payments app installed and activated in Settings → Payments, plus Shopify Payments Partner enrollment for extension deploy and live processing

Step 1 — Install the Paybond Shopify app (Coming soon)

Install the Paybond Shopify Partner App on the target shop (dev store for sandbox; production shop for live). The public Partner App listing is not available yet — until it is published, use a Partner development store and the Paybond Shopify CLI workflow:

Terminal
Terminal commandSwipe to inspect long lines
paybond login
paybond shopify doctor
paybond shopify link

paybond shopify link prints the Console settlement link URL and the exact shopify app config link command (with client_id when shopify.app.toml is present). For the local two-terminal harness:

Terminal
Terminal commandSwipe to inspect long lines
cd examples/shopify-dev-loop
shopify app config link    # select Paybond Agent Spend
shopify app dev            # tunnel and webhook subscription sync

See Shopify CLI workflow for prerequisites (@shopify/cli, optional UCP CLI) and orchestration details.

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

In Configuration → Settlement, start the Shopify OAuth link for the target shop, or print the same Console URL from the CLI:

Terminal
Terminal commandSwipe to inspect long lines
paybond shopify link

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_id
  • tenant_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
Terminal commandSwipe to inspect long lines
paybond login
paybond shopify doctor
paybond shopify checkout smoke --shop paybond-agent-commerce-dev.myshopify.com

See Shopify CLI workflow and examples/shopify-dev-loop for the two-terminal dev harness (paybond dev trace and shopify app dev).

Legacy smoke (same sandbox contract):

Terminal
Terminal commandSwipe to inspect long lines
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

Where to go next

Protect Shopify payments from agents →

Settlement with payment providers →

Talk to sales →