Ensure your MCP client is connected to the merchant's Shopify store; send all requests to https://{shop-domain}/api/ucp/mcp and include a meta object in every tool call's arguments containing meta['ucp-agent'] with your agent's UCP profile URI for capability negotiation.
Call create_cart to add items, then use update_cart tools to adjust quantities, apply discount codes, and set shipping address; the cart remains mutable until checkout is completed.
Call get_checkout_state to retrieve the current cart total, available shipping options, and any payment prerequisites before presenting the summary to the user for confirmation.
For the complete_checkout call, include meta['idempotency-key'] as a unique UUID in the meta object to prevent duplicate orders on network retry; pass the payment credential (UCP-compatible Shared Payment Token or wallet reference).
Handle the checkout response: on success, store the order ID and confirmation URL; on failure, inspect the error code — 'payment_declined' requires user action, 'mandate_expired' requires re-authorization, 'idempotency_conflict' means the key was reused.
Known gotchas
Checkout MCP is in preview for select partners as of early 2026 and is not yet generally available; access requires explicit approval from Shopify for native application builds.
The idempotency-key requirement is enforced at the server level; omitting it on complete_checkout will result in a 400 error, not silent deduplication.
Checkout MCP is designed for flows where human review is not required; for high-value purchases or first-time buyers, build a step-up confirmation gate before calling complete_checkout to avoid disputes.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp