Skip to main content

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.

Anchor to How it worksHow 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. For the full UCP specification, see Checkout capability and MCP binding.

Anchor to AuthenticateAuthenticate

Obtain your client credentials (client ID and secret) from the Catalog section of 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 to view more details related to how Shopify issues this token.

POST

https://api.shopify.com/auth/access_token

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

{
"access_token": "f8563253df0bf277ec9ac6f649fc3f17",
"scope": "read_global_api_catalog_search",
"expires_in": 86399
}

Anchor to Make requestsMake 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) for capability negotiation. 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 (for example, RFC 9421) for agent authentication in addition to or instead of Bearer tokens.

Learn more about building agentic commerce experiences.

POST

https://{shop-domain}/api/ucp/mcp

{
"jsonrpc": "2.0",
"method": "tools/call",
"id": 1,
"params": {
"name": "tool_name",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://example.com/.well-known/ucp"
}
}
}
}
}

{} Response

{
"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\",...}" }
]
}
}

Anchor to Available toolsAvailable 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.

Anchor to [object Object]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

Anchor to ParametersParameters

meta•objectRequired

Request metadata. You're required to include ucp-agent.profile, the URI to your agent's UCP profile for capability negotiation.

checkout•objectRequired

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

{
"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

{
"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\",...}" }
]
}
}

Anchor to [object Object]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

Anchor to ParametersParameters

meta•objectRequired

Request metadata. You're required to include ucp-agent.profile, the URI to your agent's UCP profile for capability negotiation.

id•stringRequired

The ID of the checkout session to retrieve.

POST

https://{shop-domain}/api/ucp/mcp

{
"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

{
"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"
}
}
}

Anchor to [object Object]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.

Anchor to ParametersParameters

meta•objectRequired

Request metadata. You're required to include ucp-agent.profile, the URI to your agent's UCP profile for capability negotiation.

id•stringRequired

The ID of the checkout session to update.

checkout•objectRequired

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

{
"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

{
"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"
}
}
}

Anchor to [object Object]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

Anchor to ParametersParameters

meta•objectRequired

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

The ID of the checkout session to complete.

checkout•objectRequired

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

{
"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

{
"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": []
}
}
}

Anchor to [object Object]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

Anchor to ParametersParameters

meta•objectRequired

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

The ID of the checkout session to cancel.

POST

https://{shop-domain}/api/ucp/mcp

{
"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

{
"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": []
}
}
}

Anchor to Checkout statusCheckout status

Checkout sessions transition through the following statuses:

StatusDescription
incompleteCheckout is missing required information. Agent should inspect messages and resolve via Update Checkout.
requires_escalationCheckout requires buyer input not available via API. Hand off to buyer via continue_url.
ready_for_completeAll information collected. Agent can call Complete Checkout.
complete_in_progressMerchant is processing the Complete Checkout request.
completedOrder placed successfully.
canceledCheckout 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.

Anchor to Error handlingError handling

UCP distinguishes between protocol errors (transport-level) and business outcomes (application-level). Your agent should handle both.

Anchor to Protocol errorsProtocol 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)

{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32000,
"message": "Unauthorized"
}
}

Anchor to Business outcomesBusiness 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)

{
"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"
}
}

Anchor to Best practicesBest 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.