Shopify CLI workflow

Paybond composes with Shopify CLI and the optional UCP CLI — it does not fork or vendor them. Use paybond shopify to validate prerequisites, print the two-terminal dev workflow, wrap webhook triggers, and smoke the commerce.checkout contract with Shopify-shaped results.

Prerequisites

Tool	Install	Role
Paybond Kit	`npm install -g @paybond/kit` or project dependency	Harbor middleware, binding helpers, CLI
Shopify CLI	`npm install -g @shopify/cli@latest`	`shopify app dev`, `shopify app config link`, `shopify app webhook trigger`
UCP CLI (optional)	`npm install -g @shopify/ucp-cli`	Agentic cart → checkout → order for live sandbox
Paybond sandbox tenant	`paybond login`	Intent bind, settlement config, webhook ingest
Linked Shopify shop	Console → Configuration → Settlement	Tenant-owned offline token (never in agent tools)
Manual payment capture	Shopify Admin → Payments	Required for `shopify_authorized_order` v1

paybond shopify doctor prints install instructions when shopify or ucp are missing — it does not auto-install global CLIs.

Readiness: `paybond shopify doctor`

paybond login
paybond shopify doctor
paybond login
paybond shopify doctor

Checks:

shopify and ucp on PATH
shopify.app.toml in the current directory
SHOPIFY_DEV_STORE (or --shop)
Paybond shop linked via settlement config
Manual capture prerequisite
shopify_authorized_order rail readiness

Alias: paybond doctor --shopify runs the same Shopify checks alongside the standard doctor suite.

Link workflow: `paybond shopify link`

paybond shopify link
paybond shopify link

Prints:

paybond login
Console settlement link URL
Exact shopify app config link command (with client_id when shopify.app.toml is present)

Local dev: two terminals

Terminal 1 — Paybond trace

paybond dev trace
# http://127.0.0.1:9477
paybond dev trace
# http://127.0.0.1:9477

Terminal 2 — Shopify app dev

cd examples/shopify-dev-loop
shopify app config link    # Paybond Agent Spend
shopify app dev            # tunnel and webhook subscription sync
cd examples/shopify-dev-loop
shopify app config link    # Paybond Agent Spend
shopify app dev            # tunnel and webhook subscription sync

Or print the orchestration banner without starting servers:

paybond shopify dev
paybond shopify dev --tunnel https://your-tunnel.example
paybond shopify dev
paybond shopify dev --tunnel https://your-tunnel.example

Webhooks target /webhooks/sandbox/shopify on your gateway origin.

Webhook test: `paybond shopify webhook trigger`

Wraps shopify app webhook trigger with the Paybond sandbox path pre-filled:

paybond shopify webhook trigger \
  --topic orders/paid \
  --gateway https://api.paybond.ai

# Local gateway
paybond shopify webhook trigger \
  --address http://127.0.0.1:8081/webhooks/sandbox/shopify

# Inspect resolved command without spawning Shopify CLI
paybond shopify webhook trigger --dry-run --topic orders/paid
paybond shopify webhook trigger \
  --topic orders/paid \
  --gateway https://api.paybond.ai

# Local gateway
paybond shopify webhook trigger \
  --address http://127.0.0.1:8081/webhooks/sandbox/shopify

# Inspect resolved command without spawning Shopify CLI
paybond shopify webhook trigger --dry-run --topic orders/paid

Checkout smoke: `paybond shopify checkout smoke`

Validates Harbor middleware and evidence with a Shopify-shaped tool result (no Shopify offline token in the agent):

paybond shopify checkout smoke \
  --shop paybond-agent-commerce-dev.myshopify.com \
  --requested-spend-cents 4500
paybond shopify checkout smoke \
  --shop paybond-agent-commerce-dev.myshopify.com \
  --requested-spend-cents 4500

When ucp is on PATH, the command notes that live checkout should use Kit createCheckoutWithBinding with note_attributes for paybond_intent_id and tenant_id. Otherwise it falls back to paybond agent sandbox smoke with the shopping preset.

Offline (no API key):

paybond shopify checkout smoke --offline
paybond shopify checkout smoke --offline

Capture readiness

paybond shopify capture ready
paybond shopify capture ready

Confirms linked shop, manual capture, and shopify_authorized_order rail readiness from settlement config.

Order inspection (dev)

paybond shopify order show gid://shopify/Order/123 \
  --shop paybond-agent-commerce-dev.myshopify.com
paybond shopify order show gid://shopify/Order/123 \
  --shop paybond-agent-commerce-dev.myshopify.com

Fetches order metadata via Shopify UCP Order MCP and displays binding fields from note_attributes.

Scaffold a project

paybond init --template paybond-shopify-shopping-agent
# or
paybond init --solution shopping --framework shopify
paybond init --template paybond-shopify-shopping-agent
# or
paybond init --solution shopping --framework shopify

Ships shopify.app.toml, paybond.policy.yaml, npm scripts (smoke, doctor), and a guarded commerce.checkout demo.

Guided shopping loop

paybond dev loop --preset shopping --shopify
paybond dev loop --preset shopping --shopify

Runs the standard dev loop with the shopping policy preset and prints Shopify next-steps after smoke.

Side-by-side with Shopify CLI

Task	Shopify CLI	Paybond CLI
Link Partner app	`shopify app config link`	`paybond shopify link` (prints exact command and Console steps)
Local app and tunnel	`shopify app dev`	`paybond shopify dev` (orchestration banner; run both terminals)
Trigger test webhook	`shopify app webhook trigger`	`paybond shopify webhook trigger` (gateway path pre-filled)
Agentic checkout	`ucp checkout create\|complete`	`paybond shopify checkout smoke` and Kit binding helpers
Spend guardrails	—	`paybond agent sandbox smoke`, `instrumentShopifyCheckout`

Prerequisites

Readiness: paybond shopify doctor

Link workflow: paybond shopify link