--- 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. The response contains: * `access_token`: A JWT access token used to interact with the MCP server. * `scope`: The list of access scopes 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 decoder tool like [`jwt.io`](https://www.jwt.io/) to view more details related to how Shopify issues this token. 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" }' ``` ## {} Response ```json { "access_token": "f8563253df0bf277ec9ac6f649fc3f17", "scope": "read_global_api_catalog_search", "expires_in": 86399 } ``` ## Make requests All requests follow the JSON-RPC 2.0 protocol. Send POST requests to the merchant's UCP endpoint: `https://{shop-domain}/api/ucp/mcp` Every request must include a `meta` object in `arguments`. Include `meta["ucp-agent"]` with a `profile` URI (your agent's [UCP profile at `/.well-known/ucp`](https://ucp.dev/specification/overview)) for [capability negotiation](https://ucp.dev/latest/specification/checkout-mcp/#discovery). For `complete_checkout` and `cancel_checkout`, you must also include `meta["idempotency-key"]` with a unique UUID for retry safety. The checkout is returned in `result.structuredContent`. The `result.content` array may also be present with a text representation of the checkout. Platforms may use [HTTP Message Signatures](https://ucp.dev/specification/signatures) (for example, RFC 9421) for agent authentication in addition to or instead of Bearer tokens. 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": { "meta": { "ucp-agent": { "profile": "https://example.com/.well-known/ucp" } } } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] } }, "id": "checkout_abc123", "status": "incomplete", "continue_url": "https://shop.example.com/checkout/checkout_abc123" }, "content": [ { "type": "text", "text": "{\"ucp\":{...},\"id\":\"checkout_abc123\",...}" } ] } } ``` ## Available tools Checkout MCP provides tools for managing the checkout lifecycle. For get, update, complete, and cancel operations, pass the checkout session ID as the top-level `id` in `arguments` rather than within the `checkout` object. The UCP spec treats resource identification and payload separately so the server can validate requests correctly. * [`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) Request metadata. You're required to include `ucp-agent.profile`, the URI to your agent's UCP profile for capability negotiation. checkout•objectRequired (critical) The checkout object containing all checkout data. Includes the following fields: * `currency` (required): ISO 4217 currency code (for example, `USD`, `EUR`, `GBP`). * `line_items` (required): Array of items to purchase. Each item must include `quantity` and an `item` object with the product variant `id`. * `buyer`: Buyer information including `email` for order confirmation. * `fulfillment`: Fulfillment preferences including shipping `methods` and `destinations`. * `payment`: 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-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" } }, "checkout": { "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": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] }, "payment_handlers": { "com.google.pay": [{ "id": "gpay", "version": "2026-01-23", "config": {} }] } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "requires_escalation", "currency": "USD", "buyer": { "email": "buyer@example.com" }, "line_items": [ { "id": "gid://shopify/CartLine/li_1?cart=abc123", "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900, "image_url": "https://cdn.shopify.com/example/sweater.jpg" }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 17800, "display_text": "Subtotal" }, { "type": "items_discount", "amount": 0, "display_text": "Discount" }, { "type": "total", "amount": 17800, "display_text": "Total" } ] } ], "totals": [ { "type": "subtotal", "amount": 17800, "display_text": "Subtotal" }, { "type": "fulfillment", "amount": 500, "display_text": "Shipping" }, { "type": "tax", "amount": 1466, "display_text": "Tax" }, { "type": "total", "amount": 19766, "display_text": "Total" } ], "fulfillment": {}, "expires_at": "2026-02-20T15:17:07Z", "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "instruments": [] }, "messages": [], "continue_url": "https://shop.example.com/cart/c/abc123?key=xyz789" }, "content": [ { "type": "text", "text": "{\"ucp\":{...},\"id\":\"gid://shopify/Checkout/abc123?key=xyz789\",...}" } ] } } ``` ### `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) Request metadata. You're required to include `ucp-agent.profile`, the URI to your agent's UCP profile for capability negotiation. 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-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789" } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] }, "payment_handlers": { "com.google.pay": [{ "id": "gpay", "version": "2026-01-23", "config": {} }] } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "incomplete", "currency": "USD", "buyer": { "email": "buyer@example.com" }, "line_items": [ { "id": "gid://shopify/CartLine/li_1?cart=abc123", "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900, "image_url": "https://cdn.shopify.com/example/sweater.jpg" }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 17800, "display_text": "Subtotal" }, { "type": "items_discount", "amount": 0, "display_text": "Discount" }, { "type": "total", "amount": 17800, "display_text": "Total" } ] } ], "totals": [ { "type": "subtotal", "amount": 17800, "display_text": "Subtotal" } ], "fulfillment": {}, "expires_at": "2026-02-20T15:17:07Z", "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "instruments": [] }, "messages": [ { "type": "warning", "code": "missing_shipping_address", "content": "Shipping address is required", "path": "$.fulfillment" } ], "continue_url": "https://shop.example.com/cart/c/abc123?key=xyz789" } } } ``` ### `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) **Caution:** This tool requires the complete checkout state on every request. `update_checkout` replaces the entire checkout with the data you provide, so if you omit fields like `line_items` or `buyer` previously included in a `create_checkout` call, they're removed from the checkout. #### Parameters meta•objectRequired (critical) Request metadata. You're required to include `ucp-agent.profile`, the URI to your agent's UCP profile for capability negotiation. id•stringRequired (critical) The ID of the checkout session to update. checkout•objectRequired (critical) The checkout object containing the complete updated checkout state. Includes the following fields: * `line_items`: Updated array of items. Replaces existing line items. * `buyer`: Updated buyer information. * `fulfillment`: Updated fulfillment preferences. * `payment`: 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-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "checkout": { "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": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] }, "payment_handlers": { "com.google.pay": [{ "id": "gpay", "version": "2026-01-23", "config": {} }] } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "requires_escalation", "currency": "USD", "buyer": { "email": "buyer@example.com" }, "line_items": [ { "id": "gid://shopify/CartLine/li_1?cart=abc123", "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900, "image_url": "https://cdn.shopify.com/example/sweater.jpg" }, "quantity": 1, "totals": [ { "type": "subtotal", "amount": 8900, "display_text": "Subtotal" }, { "type": "items_discount", "amount": 0, "display_text": "Discount" }, { "type": "total", "amount": 8900, "display_text": "Total" } ] } ], "totals": [ { "type": "subtotal", "amount": 8900, "display_text": "Subtotal" }, { "type": "fulfillment", "amount": 500, "display_text": "Shipping" }, { "type": "tax", "amount": 752, "display_text": "Tax" }, { "type": "total", "amount": 10052, "display_text": "Total" } ], "fulfillment": {}, "expires_at": "2026-02-20T15:17:07Z", "links": [ { "type": "privacy_policy", "url": "https://shop.example.com/policies/privacy" }, { "type": "terms_of_service", "url": "https://shop.example.com/policies/terms" } ], "payment": { "instruments": [] }, "messages": [], "continue_url": "https://shop.example.com/cart/c/abc123?key=xyz789" } } } ``` ### `complete_checkout` Submit payment and place the order. Requires `meta["idempotency-key"]` (UUID) in addition to `meta["ucp-agent"]`. 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) Request metadata. You're required to include `ucp-agent.profile`, the URI to your agent's UCP profile for capability negotiation, and an `idempotency-key`. id•stringRequired (critical) The ID of the checkout session to complete. checkout•objectRequired (critical) Checkout object containing payment credentials and finalization data. Include `checkout.payment` with the payment instrument and credential from 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-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" }, "idempotency-key": "661e9500-f39c-52e5-b827-557766551111" }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "checkout": { "payment": { "instruments": [ "id": "pm_1234567890abc", "handler_id": "gpay_7k2m", "type": "card" ] } } } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23" }] } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "completed", "currency": "USD", "buyer": { "email": "buyer@example.com" }, "line_items": [ { "id": "gid://shopify/CartLine/li_1?cart=abc123", "item": { "id": "gid://shopify/ProductVariant/12345678901", "title": "Organic Cotton Sweater", "price": 8900 }, "quantity": 2, "totals": [ { "type": "subtotal", "amount": 17800 }, { "type": "total", "amount": 17800 } ] } ], "totals": [ { "type": "subtotal", "amount": 17800 }, { "type": "fulfillment", "amount": 500 }, { "type": "tax", "amount": 1466 }, { "type": "total", "amount": 19766 } ], "order": { "id": "gid://shopify/Order/9876543210", "permalink_url": "https://shop.example.com/orders/9876543210" }, "messages": [] } } } ``` ### `cancel_checkout` Cancel an active checkout session. Requires `meta["idempotency-key"]` (UUID) in addition to `meta["ucp-agent"]`. 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) Request metadata. You're required to include `ucp-agent.profile`, the URI to your agent's UCP profile for capability negotiation, and an `idempotency-key`. id•stringRequired (critical) The ID of the checkout session to cancel. POST ## https://{shop-domain}/api/ucp/mcp ```json { "jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": { "name": "cancel_checkout", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" }, "idempotency-key": "772f0611-g40d-63f6-c938-668877662222" }, "id": "gid://shopify/Checkout/abc123?key=xyz789" } } } ``` ## {} Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] } }, "id": "gid://shopify/Checkout/abc123?key=xyz789", "status": "canceled", "currency": "USD", "line_items": [], "totals": [], "fulfillment": {}, "links": [], "payment": { "instruments": [] }, "messages": [] } } } ``` ## 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 can't 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 UCP distinguishes between protocol errors (transport-level) and business outcomes (application-level). Your agent should handle both. ### Protocol errors Transport-level failures (for example errors relating to authentication, rate limiting, or unavailability) are returned as JSON-RPC `error` with code `-32000` (or `-32001` for discovery errors). These prevent the request from being processed. Common error codes you might see in `error.data`: * `CHECKOUT_EXPIRED`: The checkout session has expired. * `INVALID_SHIPPING_ADDRESS`: The provided address cannot be shipped to. * `MERCHANDISE_NOT_AVAILABLE`: One or more items are out of stock. * `PAYMENT_DECLINED`: Payment was declined by the processor. ## Protocol error (JSON-RPC error) ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Unauthorized" } } ``` ### Business outcomes Application-level results (for example errors relating to quantities adjusted or items unavailable) are returned as JSON-RPC `result` with `structuredContent` and a `messages` array on the checkout. Inspect `result.structuredContent.messages` and adjust your flow (for example, prompt the buyer to choose alternatives). ## Business outcome (result with messages) ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-23", "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/checkout", "schema": "https://ucp.dev/services/shopping/openrpc.json" }], "dev.ucp.shopping.fulfillment": [{ "version": "2026-01-23", "spec": "https://ucp.dev/specs/shopping/fulfillment", "schema": "https://ucp.dev/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout" }] } }, "id": "checkout_abc123", "status": "incomplete", "line_items": [ { "id": "item_456", "quantity": 100, "available_quantity": 12 } ], "messages": [ { "type": "warning", "code": "quantity_adjusted", "content": "Quantity adjusted; requested 100 units but only 12 available", "path": "$.line_items[0].quantity" } ], "continue_url": "https://merchant.com/checkout/checkout_abc123" } } ``` ## Best practices * **Idempotency keys**: Provide a unique UUID in `meta["idempotency-key"]` for `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.