Platform implementation guide

Shopify: build a controlled agentic-commerce path

Map product discovery, cart state and checkout handoff to Shopify's documented UCP and MCP surfaces before treating a store as agent-ready.

Official sources reviewed 2026-08-27. This date records the documentation review, not a test of a specific merchant store.

Capabilities confirmed in official documentation

• Global Catalog searches across Shopify merchants; Storefront Catalog is scoped to one merchant. Both expose search_catalog, lookup_catalog and get_product.
• The documented lookup limit is up to 50 identifiers per Global Catalog request and up to 10 for Storefront Catalog.
• get_product returns option combinations, availability signals and checkout links. Shopify instructs clients to fetch fresh product data after selection.
• The cart flow supports line items, localization and buyer context across turns, then converts the cart to a checkout for merchant handoff.
• Shopify states that broader access, including direct checkout completion, depends on the agent profile and trust tier.
• Order state can be monitored through UCP-shaped webhooks and fetched on demand with get_order.

Implementation sequence

1. Choose Global Catalog only for cross-merchant discovery; use Storefront Catalog when the task must remain inside one merchant.
2. Host and reference the required agent profile, then record the capability and rate-limit response actually granted to that profile.
3. Call get_product after selection instead of reusing a search result. Preserve the selected variant, shipping country and localization inputs when the cart is created.
4. Keep discovery, cart creation, checkout handoff, direct checkout and order monitoring as separate capabilities in the implementation record.
5. Treat checkout completion as a controlled capability. Fall back to the merchant handoff URL unless the tested profile is explicitly permitted to complete checkout.

Scenarios to test before claiming support

• A variant goes out of stock between discovery and checkout.
• A buyer changes country or currency after a cart has been created.
• A catalog response contains an inferred field or a relaxed variant selection. The interface must label it and request confirmation instead of silently substituting.
• An agent without the required trust tier is handed off to a merchant checkout instead of completing payment.
• A webhook is missed and get_order returns a newer fulfillment, refund or cancellation state.

Evidence to retain from the test

• Capture the catalog endpoint, profile used, request context, selected product and variant IDs, and response timestamp.
• Record the cart ID, line items, localization, totals and checkout handoff URL before and after every mutation.
• For direct checkout, retain the capability response that permits it and a redacted result from a controlled test. A documentation page alone is not proof of merchant eligibility.

What the documentation does not establish

• A product appearing in Global Catalog does not prove that a specific merchant supports direct checkout.
• Universal Cart is described separately as early access; it is not treated here as generally available.
• Shopify prohibits caching catalog results and reusing downloaded catalog images. Inferred fields can vary in presence and accuracy, rate limits apply and endpoint URLs may change.

Evidence boundary

Catalog visibility, checkout handoff and direct checkout are distinct states. The current profile response, live product data and controlled checkout result are the source of truth.

Use the public signal scanner for a limited external check, then run the test cases above in a controlled environment. Review common failure modes before extending credentials or payment access.