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.

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

The response contains:

  • 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 to investigate more details related to how Shopify issues this token.

{} Response

{
"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:
https://{shop-domain}/api/ucp/mcp

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": {
// tool-specific arguments
}
}
}

Anchor to Available toolsAvailable tools

Checkout MCP provides tools for managing the checkout lifecycle:

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

Metadata object containing ucp.profile, the URI to your agent's UCP profile for version compatibility.

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": {
"profile": "https://agent.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": {
"content": [
{
"type": "text",
"text": {
"ucp": {
"version": "2026-01-11",
"capabilities": [
{ "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" },
{ "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11" }
],
"transports": {
"embedded": {
"schema": "https://ucp.dev/services/shopping/embedded.openrpc.json",
"delegations": ["payment.credential", "payment.instruments_change", "fulfillment.address_change"]
}
}
},
"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" }
],
"parent_id": null
}
],
"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", "title": "Privacy Policy", "url": "https://shop.example.com/policies/privacy" },
{ "type": "terms_of_service", "title": "Terms of Service", "url": "https://shop.example.com/policies/terms" }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"version": "2026-01-11",
"spec": "https://ucp.dev/handlers/google_pay",
"config_schema": "https://ucp.dev/handlers/google_pay/config.json",
"instrument_schemas": ["https://ucp.dev/handlers/google_pay/card_payment_instrument.json"],
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_name": "Example Store",
"merchant_id": "16708973830884969730"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD", "AMEX", "DISCOVER"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": [
{ "key": "gateway", "value": "shopify" },
{ "key": "gateway_merchant_id", "value": "12345678" }
]
}
}
]
}
}
],
"instruments": []
},
"messages": [],
"continue_url": "https://shop.example.com/cart/c/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

Metadata object containing ucp.profile, the URI to your agent's UCP profile for version compatibility.

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": {
"profile": "https://agent.example/profiles/shopping-agent.json"
}
},
"id": "gid://shopify/Checkout/abc123?key=xyz789"
}
}
}

{} Response

{
"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" },
{ "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11" }
]
},
"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" }
],
"parent_id": null
}
],
"totals": [
{ "type": "subtotal", "amount": 17800, "display_text": "Subtotal" }
],
"fulfillment": {},
"expires_at": "2026-02-20T15:17:07Z",
"links": [
{ "type": "privacy_policy", "title": "Privacy Policy", "url": "https://shop.example.com/policies/privacy" },
{ "type": "terms_of_service", "title": "Terms of Service", "url": "https://shop.example.com/policies/terms" }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"version": "2026-01-11",
"spec": "https://ucp.dev/handlers/google_pay"
}
],
"instruments": []
},
"messages": [
{
"type": "error",
"code": "missing_shipping_address",
"severity": "recoverable",
"content": "Shipping address is required"
}
],
"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

Metadata object containing ucp.profile, the URI to your agent's UCP profile for version compatibility.

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": {
"profile": "https://agent.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": {
"content": [
{
"type": "text",
"text": {
"ucp": {
"version": "2026-01-11",
"capabilities": [
{ "name": "dev.ucp.shopping.checkout", "version": "2026-01-11" },
{ "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11" }
]
},
"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" }
],
"parent_id": null
}
],
"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", "title": "Privacy Policy", "url": "https://shop.example.com/policies/privacy" },
{ "type": "terms_of_service", "title": "Terms of Service", "url": "https://shop.example.com/policies/terms" }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"version": "2026-01-11",
"spec": "https://ucp.dev/handlers/google_pay",
"config": {
"api_version": 2,
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD", "AMEX", "DISCOVER"]
}
}
]
}
}
],
"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.

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

Metadata object containing ucp.profile, the URI to your agent's UCP profile for version compatibility.

id•stringRequired

The ID of the checkout session to complete.

idempotency_key•stringRequired

A unique UUID for retry safety. Prevents duplicate order placement.

payment•objectRequired

Payment instrument instance with credential data submitted by the buyer through 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": {
"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

{
"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" },
{ "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11" }
]
},
"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,
"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" }
],
"parent_id": null
}
],
"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": {},
"links": [],
"payment": {
"handlers": [],
"instruments": [
{
"id": "pm_1234567890abc",
"handler_id": "gpay",
"type": "card"
}
],
"selected_instrument_id": "pm_1234567890abc"
},
"messages": [],
"order_id": "gid://shopify/Order/9876543210",
"order_permalink_url": "https://shop.example.com/orders/9876543210"
}
}
]
}
}

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

Anchor to ParametersParameters

_meta•objectRequired

Metadata object containing ucp.profile, the URI to your agent's UCP profile for version compatibility.

id•stringRequired

The ID of the checkout session to cancel.

idempotency_key•stringRequired

A unique UUID for retry safety.

POST

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

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

{
"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" },
{ "name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11" }
]
},
"id": "gid://shopify/Checkout/abc123?key=xyz789",
"status": "canceled",
"currency": "USD",
"line_items": [],
"totals": [],
"fulfillment": {},
"links": [],
"payment": {
"handlers": [],
"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 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.

Anchor to Error handlingError handling

Errors follow JSON-RPC 2.0 format with UCP-specific error codes in the data field:

Common error codes:

  • 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.

{} Error Response

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

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