--- 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 on the merchant storefront following your agentic referral. **Coming soon:** Checkout MCP tools are coming soon. ## How it works With Checkout MCP, you create, get, and update checkout sessions that allows your agent to guide the checkout by its status along the following path: * Create checkout sessions with line items, buyer information, and fulfillment details. * Retrieve and update checkout state as buyers make selections. * Refer buyers to merchant storefronts to continue their journey. 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. Access tokens 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 (invited partners only; most partners use `continue_url` to direct buyers to the storefront). * [`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 a delivery option **Caution:** `update_checkout` uses PUT semantics. Each request replaces the full checkout state with the payload you send. Omit a field (for example `line_items` or `buyer`) and it is removed from the checkout. There is no server-side merge of partial updates. #### 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 ### General access For most partners referring checkout sessions from Catalog, each response from [`create_checkout`](#create_checkout), [`get_checkout`](#get_checkout), and [`update_checkout`](#update_checkout) includes: * `status`, `requires_escalation` * `messages`: an array of message objects, each with `type` and `severity`. The message in this array will contain the `severity` `requires_buyer_input` or `recoverable` depending on the error. * `continue_url` for handing off to the merchant storefront When the session is ready for the buyer to finish on the storefront, present the `continue_url`. For general access, directing buyers to that URL is how checkout completes; you do not call [`complete_checkout`](#complete_checkout). ## General access terminal state (example) ```json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "id": "gid://shopify/Checkout/...", "status": "requires_escalation", "messages": [ { "type": "error", "severity": "requires_buyer_input" } ], "continue_url": "https://merchant.com/checkout/..." } } } ``` ### Native checkout Some apps can respond to the full set of lifecycle events in checkout to act on behalf of the buyer in certain circumstances. Checkout sessions transition through the following states: Every tool response includes `status` and a `messages` array. Each message has a `severity` that reflects the resource state and recommended action. When `status` is `"incomplete"` or `"requires_escalation"`, use `severity` to decide the next step. You can't call `complete_checkout` until the status is `ready_for_complete`. Until then, use `update_checkout` to address `incomplete` or `requires_escalation` statuses, or direct the buyer to `continue_url` when `messages` include `severity: requires_buyer_input`. See the [Checkout Status Lifecycle](https://ucp.dev/latest/specification/checkout/#checkout-status-lifecycle) in the UCP spec for the full status lifecycle. | Status | Description | | - | - | | `incomplete` | Checkout is missing required information. Inspect `messages` (including each message's `severity`) and resolve via Update Checkout. | | `requires_escalation` | Checkout requires buyer input not available via API. Check `messages` for `severity: requires_buyer_input` and 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. | ## Error handling UCP distinguishes between protocol errors and business outcomes. * Business outcomes: application-level results from successful request processing, returned as JSON-RPC `result` with the UCP envelope and a `messages` array. * Protocol errors: transport-level failures (authentication, rate limiting, unavailability) that prevent request processing. Returned as JSON-RPC `error` with code `-32000`, or `-32001` for discovery errors. See the [Checkout MCP binding](https://ucp.dev/latest/specification/checkout-mcp/#error-handling) and [Core Specification error handling](https://ucp.dev/latest/specification/overview/#error-handling) for the complete error code registry and examples. ### Business outcomes Application-level results (including errors like expired checkout, invalid address, unavailable merchandise, or payment declined) are returned as a successful JSON-RPC `result` with `structuredContent` and a `messages` array (on the checkout object or at the top level). The request was processed; the outcome is in the payload. Inspect `result.structuredContent` for the checkout (or UCP envelope) and its `messages` array. Use message `type`, `code`, and optional `path` to adjust your flow (for example, prompt the buyer to choose alternatives or direct them to `continue_url`). ## 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" } } ``` ### Protocol errors Transport-level failures that prevent the request from being processed (for example authentication failure, rate limiting, or service unavailability) are returned as JSON-RPC `error` with code `-32000`, or `-32001` for discovery errors. These are not application outcomes: the server did not complete the operation. ## Protocol error (JSON-RPC error) ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Unauthorized" } } ```