--- title: Checkout MCP server description: >- Use the Checkout MCP server to create and manage checkout sessions for purchases on Shopify merchants. source_url: html: 'https://shopify.dev/docs/agents/checkout/mcp' md: 'https://shopify.dev/docs/agents/checkout/mcp.md' --- # Checkout MCP The Checkout MCP server enables AI agents to create and manage checkout sessions, allowing buyers to complete purchases through a trusted UI after product discovery. ## How it works The Checkout MCP server lets your AI agent facilitate purchases on behalf of buyers: * Create checkout sessions with line items, buyer information, and fulfillment details. * Retrieve and update checkout state as buyers make selections. * Complete orders through a trusted UI handoff for payment collection. * Cancel sessions that are no longer needed. For usage guidelines, see [About Checkout](https://shopify.dev/docs/agents/checkout). For the full UCP specification, see [Checkout capability](https://ucp.dev/specification/checkout/) and [MCP binding](https://ucp.dev/specification/checkout-mcp/). ## Authenticate Obtain your client credentials (client ID and secret) from [the **Catalog** section of Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard). Then use those credentials to retrieve a token for subsequent requests. All requests require the `Authorization: Bearer {token}` header. POST ## https://api.shopify.com/auth/access\_token ```bash curl --request POST \ --url https://api.shopify.com/auth/access_token \ --header 'Content-Type: application/json' \ --data '{ "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", "grant_type": "client_credentials" }' ``` The response will contain: * `access_token`: A JWT access token that can be used to interact with the MCP server. * `scope`: The list of access scopes that were granted to your API key. * `expires_in`: The number of seconds until the access token expires. JWT tokens created from Dev Dashboard credentials have a 60-minute TTL. You can use a JWT decoder tool like [`jwt.io`](https://www.jwt.io/) to investigate more details related to how Shopify issues this token. ## {} Response ```json { "access_token": "f8563253df0bf277ec9ac6f649fc3f17", "scope": "read_global_api_catalog_search", "expires_in": 86399 } ``` All requests follow the JSON-RPC 2.0 protocol. Send POST requests to the merchant's UCP endpoint: ```text https://{shop-domain}/api/ucp/mcp ``` Learn more about [building agentic commerce experiences](https://shopify.dev/docs/agents/get-started/authentication). POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "tool_name", "arguments": { // tool-specific arguments } } } ``` ## Available tools Checkout MCP provides tools for managing the checkout lifecycle: * [`create_checkout`](#create_checkout): Create a new checkout session with line items and buyer information. * [`get_checkout`](#get_checkout): Retrieve the current state of a checkout session. * [`update_checkout`](#update_checkout): Update a checkout session with new information. * [`complete_checkout`](#complete_checkout): Submit payment and place the order. * [`cancel_checkout`](#cancel_checkout): Cancel an active checkout session. ### `create_checkout` Create a new checkout session with line items, buyer information, and fulfillment preferences. Use this tool when a buyer is ready to purchase items and you need to initiate the checkout process. The response includes a `continue_url` for handing off to a trusted UI. When to use: * Buyer says "I want to buy this item" * Agent has collected enough information to start checkout * Buyer confirms their cart and wants to proceed #### Parameters \_meta•objectRequired (critical) Metadata object containing `ucp.profile`, the URI to your agent's UCP profile for version compatibility. currency•stringRequired (critical) ISO 4217 currency code for the checkout (e.g., `USD`, `EUR`, `GBP`). line\_items•arrayRequired (critical) Array of items to purchase. Each item must include `quantity` and an `item` object with the product variant `id`. buyer•object Buyer information including `email` for order confirmation and communication. fulfillment•object Fulfillment preferences including shipping `methods` and `destinations` (delivery addresses). payment•object Payment configuration including available `instruments` and `selected_instrument_id`. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "create_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://agent.example/profiles/shopping-agent.json" } }, "currency": "USD", "line_items": [ { "quantity": 2, "item": { "id": "gid://shopify/ProductVariant/12345678901" } } ], "buyer": { "email": "buyer@example.com" }, "fulfillment": { "methods": [ { "type": "shipping", "destinations": [ { "first_name": "Jane", "last_name": "Smith", "street_address": "123 Main Street", "address_locality": "Brooklyn", "address_region": "NY", "postal_code": "11201", "address_country": "US" } ] } ] } } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "ucp": { "version": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "requires_escalation", "currency": "USD", "line_items": [ { "id": "li_1", "quantity": 2, "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900 }, "base_amount": 17800, "subtotal": 17800, "total": 17800 } ], "totals": [ { "type": "subtotal", "amount": 17800 }, { "type": "fulfillment", "amount": 500, "display_text": "Shipping" }, { "type": "total", "amount": 18300 } ], "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "handlers": [ { "id": "gpay", "name": "com.google.pay", "version": "2026-01-11", "config": { "api_version": 2, "allowed_payment_methods": [ { "type": "CARD", "parameters": { "allowed_auth_methods": ["PAN_ONLY"], "allowed_card_networks": ["VISA", "MASTERCARD", "AMEX"] } } ] } } ], "instruments": [], "selected_instrument_id": null }, "continue_url": "https://shop.example.com/cart/c/abc123?key=xyz789" } } ], "isError": false } } ``` ### `get_checkout` Retrieve the current state of an existing checkout session. Use this tool to check the status of a checkout, see updated totals after changes, or verify what information is still needed before completion. When to use: * Need to refresh checkout state after buyer returns * Want to show current totals and line items * Checking if checkout is ready for payment #### Parameters \_meta•objectRequired (critical) Metadata object containing `ucp.profile`, the URI to your agent's UCP profile for version compatibility. id•stringRequired (critical) The ID of the checkout session to retrieve. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "get_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://agent.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789" } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "ucp": { "version": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "incomplete", "currency": "USD", "line_items": [ { "id": "li_1", "quantity": 2, "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900 }, "base_amount": 17800, "subtotal": 17800, "total": 17800 } ], "totals": [ { "type": "subtotal", "amount": 17800 } ], "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "handlers": [ { "id": "gpay", "name": "com.google.pay", "version": "2026-01-11" } ] }, "messages": [ { "type": "error", "code": "missing_shipping_address", "severity": "recoverable", "content": "Shipping address is required" } ] } } ], "isError": false } } ``` ### `update_checkout` Update an existing checkout session with new information. Use this tool to modify line items, update shipping address, change fulfillment method, or add buyer information before completing the checkout. When to use: * Buyer wants to change quantity or remove items * Buyer provides or updates shipping address * Need to update buyer email or contact info * Changing fulfillment method (shipping vs pickup) #### Parameters \_meta•objectRequired (critical) Metadata object containing `ucp.profile`, the URI to your agent's UCP profile for version compatibility. id•stringRequired (critical) The ID of the checkout session to update. buyer•object Updated buyer information. fulfillment•object Updated fulfillment preferences. line\_items•array Updated array of items. Replaces the existing line items. payment•object Updated payment configuration. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "update_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://agent.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "line_items": [ { "quantity": 1, "item": { "id": "gid://shopify/ProductVariant/12345678901" } } ], "fulfillment": { "methods": [ { "type": "shipping", "destinations": [ { "first_name": "Jane", "last_name": "Smith", "street_address": "456 Oak Avenue", "address_locality": "Manhattan", "address_region": "NY", "postal_code": "10001", "address_country": "US" } ] } ] } } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "ucp": { "version": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "requires_escalation", "currency": "USD", "line_items": [ { "id": "li_1", "quantity": 1, "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900 }, "base_amount": 8900, "subtotal": 8900, "total": 8900 } ], "totals": [ { "type": "subtotal", "amount": 8900 }, { "type": "fulfillment", "amount": 500, "display_text": "Shipping" }, { "type": "total", "amount": 9400 } ], "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "handlers": [ { "id": "gpay", "name": "com.google.pay", "version": "2026-01-11", "config": { "api_version": 2, "allowed_payment_methods": [ { "type": "CARD", "parameters": { "allowed_auth_methods": ["PAN_ONLY"], "allowed_card_networks": ["VISA", "MASTERCARD", "AMEX"] } } ] } } ] }, "continue_url": "https://shop.example.com/cart/c/abc123?key=xyz789" } } ], "isError": false } } ``` ### `complete_checkout` Submit payment and place the order. Use this tool when the checkout is ready and the buyer has authorized payment. This finalizes the transaction and creates an order. When to use: * Checkout status is `ready_for_complete` * Buyer has reviewed and confirmed the order * Payment credential has been collected #### Parameters \_meta•objectRequired (critical) Metadata object containing `ucp.profile`, the URI to your agent's UCP profile for version compatibility. id•stringRequired (critical) The ID of the checkout session to complete. idempotency\_key•stringRequired (critical) A unique UUID for retry safety. Prevents duplicate order placement. payment•objectRequired (critical) Payment instrument instance with credential data submitted by the buyer through the trusted UI. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "complete_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://agent.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "idempotency_key": "661e9500-f39c-52e5-b827-557766551111", "payment": { "instrument_id": "pm_1234567890abc", "credential": { "type": "payment_gateway", "token": "tok_visa_4242" } } } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "ucp": { "version": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "completed", "currency": "USD", "line_items": [ { "id": "li_1", "quantity": 2, "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900 }, "base_amount": 17800, "subtotal": 17800, "total": 17800 } ], "totals": [ { "type": "subtotal", "amount": 17800 }, { "type": "fulfillment", "amount": 500 }, { "type": "total", "amount": 18300 } ], "links": [], "payment": { "handlers": [], "instruments": [ { "id": "pm_1234567890abc", "handler_id": "gpay", "type": "card" } ], "selected_instrument_id": "pm_1234567890abc" }, "order_id": "gid://shopify/Order/9876543210", "order_permalink_url": "https://shop.example.com/orders/9876543210" } } ], "isError": false } } ``` ### `cancel_checkout` Cancel an active checkout session. Use this tool when a buyer abandons the checkout or explicitly requests cancellation. Canceled checkouts cannot be resumed. When to use: * Buyer explicitly cancels the order * Session has been abandoned * Need to start fresh with a new checkout #### Parameters \_meta•objectRequired (critical) Metadata object containing `ucp.profile`, the URI to your agent's UCP profile for version compatibility. id•stringRequired (critical) The ID of the checkout session to cancel. idempotency\_key•stringRequired (critical) A unique UUID for retry safety. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "cancel_checkout", "arguments": { "_meta": { "ucp": { "profile": "https://agent.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "idempotency_key": "772f0611-g40d-63f6-c938-668877662222" } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": { "ucp": { "version": "2026-01-11", "capabilities": [ { "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" } ] }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "canceled", "currency": "USD", "line_items": [], "totals": [], "links": [], "payment": { "handlers": [] } } } ], "isError": false } } ``` ## Checkout status Checkout sessions transition through the following statuses: | Status | Description | | - | - | | `incomplete` | Checkout is missing required information. Agent should inspect `messages` and resolve via Update Checkout. | | `requires_escalation` | Checkout requires buyer input not available via API. Hand off to buyer via `continue_url`. | | `ready_for_complete` | All information collected. Agent can call Complete Checkout. | | `complete_in_progress` | Merchant is processing the Complete Checkout request. | | `completed` | Order placed successfully. | | `canceled` | Checkout session is invalid or expired. Start a new session if needed. | The `status` field is included in the response of every tool call. You cannot call `complete_checkout` until the status reads `ready_for_complete`. Until then, use `update_checkout` to address `incomplete` statuses, or open an embedded checkout using `continue_url` for `requires_escalation` statuses. ## Error handling Errors follow JSON-RPC 2.0 format with UCP-specific error codes in the `data` field: Common error codes: * `MERCHANDISE_NOT_AVAILABLE`: One or more items are out of stock * `INVALID_SHIPPING_ADDRESS`: The provided address cannot be shipped to * `PAYMENT_DECLINED`: Payment was declined by the processor * `CHECKOUT_EXPIRED`: The checkout session has expired ## {} Error Response ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32603, "message": "Internal error", "data": { "status": "error", "errors": [ { "code": "MERCHANDISE_NOT_AVAILABLE", "message": "One or more cart items are not available", "severity": "requires_buyer_input", "details": { "invalid_items": ["gid://shopify/ProductVariant/999"] } } ] } } } ``` ## Best practices * **Idempotency keys**: Always provide unique UUIDs for `create_checkout`, `complete_checkout`, and `cancel_checkout` to prevent duplicate operations. * **Status checks**: Poll `get_checkout` to verify status before attempting completion. * **Error recovery**: Handle `MERCHANDISE_NOT_AVAILABLE` by prompting the buyer to select alternatives. * **Trusted UI handoff**: Use `continue_url` to redirect buyers to a secure checkout UI for payment. * **Session management**: Cancel abandoned checkouts to free up inventory holds. * **Payment security**: Never collect or transmit raw payment credentials through the agent.