agentic-commerce-for-shopify

Multi-protocol agentic-commerce layer for Shopify. Speaks ACP, UCP, AP2 on top of Shopify's existing storefront flow; emits real-standard discovery files; signed-JWT cart-deeplinks; rail-agnostic (your merchant's existing PSP completes payment).

Runs as a Node sidecar talking to the Shopify Admin GraphQL API. Implements @xpaysh/adapter-contract — same contract as the WooCommerce, commercetools, BigCommerce, Magento, Saleor, and PrestaShop siblings.

v0.1 ships with Custom App auth (single Shopify store). The App OAuth flow + App Store packaging (so merchants can install with one click from the Shopify App Store) lands in v0.2.

What v0.1 ships

Discovery

Path	Standard
GET /llms.txt	llmstxt.org
GET /.well-known/ucp	UCP profile
GET /.well-known/oauth-protected-resource	RFC 9728 (opt-in)
GET /.well-known/agent-card.json	A2A 1.0 (opt-in)
GET /robots.txt	RFC 9309 + AI-bot allowlist
GET /api/v1/jsonld/product/:id-or-handle	schema.org JSON-LD

Protocols

• UCP: catalog search/lookup, cart CRUD (via Shopify Draft Orders), checkout, order lookup
• ACP: checkout_sessions create / get / update / complete, order lookup
• AP2: structural mandate verification, mandate-bound checkout

Why Draft Orders?

Shopify's Admin GraphQL API doesn't expose a Cart type — carts live in the Storefront API, which uses a different token (and the merchant's storefront usually owns that). For server-side cart construction by AI agents we use Draft Orders: they accept line items by variantId, can carry shipping/billing addresses, surface a hosted invoiceUrl for the buyer to complete payment, and convert to real Orders on payment capture. Same auth token as everything else, no Storefront API token needed.

Capabilities

cart                ✓
checkout            ✓  (hands off to draft-order invoiceUrl)
catalogSearch       ✓
catalogLookup       ✓
order               ✓
inventoryRealtime   ✓
refunds             —  v0.3
disputes            —  v0.3
webhooks            —  v0.3 (Shopify webhook subscriptions)

Quickstart (Docker, Custom App)

git clone https://github.com/xpaysh/agentic-commerce-for-shopify.git
cd agentic-commerce-for-shopify
cp .env.example .env
# Fill in XPAY_MERCHANT_SLUG, SITE_URL, XPAY_API_KEY,
# SHOPIFY_SHOP, SHOPIFY_ADMIN_ACCESS_TOKEN

docker compose -f examples/docker-compose.yml up --build

Manual run

npm install
cp .env.example .env       # fill in
npm run build
node --env-file=.env dist/server.js

Get a Shopify Custom App token

1. Shopify admin → Settings → Apps and sales channels → Develop apps
2. Create an app → name it xpay agentic commerce
3. Configuration → Admin API integration → Configure, then enable scopes:
   • read_products, read_inventory
   • read_orders, write_draft_orders
   • read_locales, read_shipping, read_locations
4. Save → Install app
5. API credentials → Admin API access token → Reveal token once → copy into SHOPIFY_ADMIN_ACCESS_TOKEN (starts with shpat_)
6. Also copy your shop domain (e.g. acme-outdoors.myshopify.com) into SHOPIFY_SHOP

v0.2 distribution split

The OSS protocol/adapter layer (this repo) stays public so anyone can self-host a Shopify sidecar with a Custom App token. The Shopify App Store packaging — App OAuth flow, billing-API integration, Functions for storefront-side attribution, App Store listing copy — lives in a separate private repo (xpaysh/shopify-app-listing) to protect the App Store distribution moat.

This mirrors the Plausible Analytics pattern: OSS protocol implementation + paid hosted distribution.

v0.2 roadmap (OSS — this repo)

• RFC 9421 signature verification middleware on /ucp/* + /acp/* (lands in v0.2.1; gated by VERIFY_UCP_SIGNATURES=1 env)
• DDB-backed ACP session storage via @xpaysh/acp-session-store (lands in v0.2.2 — needs xpay-acp-sessions table)
• Webhook-handler module for orders/create, orders/updated, orders/fulfilled, refunds/create — emits a normalized OrderStateChanged event (lands in v0.2.3)

v0.2 work (private — xpaysh/shopify-app-listing)

• Shopify App OAuth flow (/auth + /auth/callback)
• App Store metadata + listing copy + billing API integration
• Shopify Functions for storefront-side attribution tagging

Architecture

This package is one of a family of agentic-commerce-for-<platform> repos under xpaysh that all implement the same @xpaysh/adapter-contract:

• agentic-commerce-for-woocommerce — PHP-native reference
• agentic-commerce-for-commercetools
• agentic-commerce-for-bigcommerce
• agentic-commerce-for-magento
• agentic-commerce-for-saleor
• agentic-commerce-for-prestashop
• agentic-commerce-for-shopify — this repo

Per-platform delta is ~4 files (shopify-client.ts, queries.ts, adapter.ts, mappers.ts); every protocol route handler and discovery emitter is shared.

License

Apache-2.0