---
title: Checkout for agents
description: >-
  Complete purchases in agentic commerce applications using checkout sessions or
  cart permalinks.
source_url:
  html: 'https://shopify.dev/docs/agents/checkout'
  md: 'https://shopify.dev/docs/agents/checkout.md'
---

ExpandOn this page

* [How it works](https://shopify.dev/docs/agents/checkout.md#how-it-works)
* [Checkout sessions with MCP](https://shopify.dev/docs/agents/checkout.md#checkout-sessions-with-mcp)
* [Embed with Checkout Kit](https://shopify.dev/docs/agents/checkout.md#embed-with-checkout-kit)
* [Cart permalinks](https://shopify.dev/docs/agents/checkout.md#cart-permalinks)
* [Next steps](https://shopify.dev/docs/agents/checkout.md#next-steps)

# Checkout for agents

Checkout in the Universal Commerce Protocol (UCP) enables buyers to complete purchases after product discovery. Agents can facilitate the checkout process, and even carry out the complete transaction on behalf of the buyer.

If the checkout requires buyer actions that are not supported over MCP the agent can open web checkout in any browser, or present it using Checkout Kit or Embedded Checkout Protocol for a native, embedded checkout experience.

***

## How it works

After product discovery, your AI agent needs to transition buyers through the checkout flow. How you handle checkout depends on how much control your agent needs over the process:

* **[Checkout MCP](https://shopify.dev/docs/agents/checkout/mcp)**: Provides tools for creating and managing checkout sessions programmatically. Use this when your agent needs to track status, handle errors, update checkout details, or support complex multi-step flows. Checkout MCP requires [authentication via JWT tokens](https://shopify.dev/docs/agents/get-started/authentication).
* **[Cart permalinks](#cart-permalinks)**: URLs that take buyers directly to a merchant's checkout with pre-selected items. The Catalog returns a `checkoutUrl` for each product that you can open directly or embed in your application for simpler flows.

***

## Checkout sessions with MCP

The [Checkout MCP server](https://shopify.dev/docs/agents/checkout/mcp) implements UCP's [checkout capability](https://ucp.dev/specification/checkout/) through these tools:

* [`create_checkout`](https://shopify.dev/docs/agents/checkout/mcp#create_checkout): Initiates a new checkout session with line items and buyer information.
* [`update_checkout`](https://shopify.dev/docs/agents/checkout/mcp#update_checkout): Modifies items, fulfillment options, or buyer information to resolve missing data.
* [`complete_checkout`](https://shopify.dev/docs/agents/checkout/mcp#complete_checkout): Finalizes the checkout and places the order.

Together, these tools enable a status-driven workflow where your agent iteratively builds the checkout until it's ready for completion.

The pattern works like this:

1. **Create** a checkout session with line items and buyer information
2. **Update** the checkout to resolve any missing information, or **escalate** to a trusted UI for buyer input
3. **Complete** the checkout when status reaches `ready_for_complete`

### Status-driven workflow

After each tool call, check the `status` field to determine what action is required next:

| Status | Action |
| - | - |
| `incomplete` | Read `messages` array and call `update_checkout` to provide missing data. |
| `requires_escalation` | Redirect buyer to `continue_url` for trusted UI input. |
| `ready_for_complete` | Call `complete_checkout` to finalize the order. |
| `complete_in_progress` | Wait; merchant is processing the request. |
| `completed` | Order placed successfully. |
| `canceled` | Session expired. Start a new checkout. |

### Resolving incomplete status

When status is `incomplete`, the `messages` array tells you what's missing (shipping address, contact information, or other required fields). Each message includes a `severity` field that indicates whether your agent can resolve it:

| Severity | Meaning | Agent action |
| - | - | - |
| `recoverable` | Agent can fix via API. | Call `update_checkout` with the missing data. |
| `requires_buyer_input` | Merchant requires input not available via API. | Messages include actions for buyer to take, such as `MERCHANDISE_NOT_AVAILABLE`. Agent should surface error to direct buyer to choose another item. |

Resolve all `recoverable` errors before initiating buyer handoff. Once you've addressed the issues, the next response will return an updated status.

### Resolving escalations

When status reaches `requires_escalation`, the checkout requires buyer input that can't be collected via API (for example, a business critical [Checkout UI extension](https://shopify.dev/docs/api/checkout-ui-extensions/latest) implemented by the merchant for age verification).

The response includes a `continue_url` that points to where buyers can complete these steps securely. You have two options for rendering this interaction:

* **In-app browser**: Open the `continue_url` directly in a browser or web view. This is the simplest approach.
* **[Embedded Checkout Protocol](https://shopify.dev/docs/agents/checkout/ecp)** and **Checkout Kit**: Embed the checkout UI in your application and handle events like address changes and payment credential requests programmatically. This provides more control over the checkout experience. See the [Checkout Kit reference](https://shopify.dev/docs/storefronts/mobile/checkout-kit) and the [ECP specification](https://ucp.dev/specification/embedded-checkout/) for protocol details.

Either approach ensures:

* **Security**: Payment credentials are never exposed to agents.
* **Determinism**: Given the same inputs, the merchant returns the same outputs.
* **Buyer control**: The buyer always reviews and authorizes the final transaction.

### Completing the checkout

When status reaches `ready_for_complete`, call [`complete_checkout`](https://shopify.dev/docs/agents/checkout/mcp#complete_checkout) to finalize the order. The response will include status `completed` when the order is placed successfully.

### Payment handlers

Payment handlers enable "N-to-N" interoperability between platforms, businesses, and payment providers. Rather than building custom integrations for each payment method, agents and merchants can work with standardized handler specifications that define how payments are configured, discovered, and processed.

When a checkout reaches `ready_for_complete`, the `payment.handlers` array in the response tells your agent which payment methods the merchant accepts. Agents can use this information to present appropriate payment options or delegate credential collection to a handler-specific flow.

For a complete framework on building and integrating payment handlers, see the [UCP Payment Handler Guide](https://ucp.dev/specification/payment-handler-guide/).

#### Shop Pay

Shop Pay (`dev.shopify.shop_pay`) is Shopify's native payment handler that provides accelerated checkout by securely storing buyer payment and shipping information. Agents can orchestrate Shop Pay payments through a delegated flow that collects payment authorization from buyers and returns a token for processing.

[Integrate Shop Pay as a UCP payment handler - Shop Pay handler specification](https://shopify.dev/docs/agents/checkout/shop-pay-handler)

***

## Embed with Checkout Kit

Checkout Kit embeds the purchase flow directly in your application. Buyers stay within your application from product discovery through payment completion. The kit provides native SDKs and a web component for handling presentation, lifecycle events, and authentication.

[Embed checkout using the web component. - Web](https://shopify.dev/docs/storefronts/mobile/checkout-kit/web)

[Embed checkout in iOS apps using the Swift SDK. - Swift](https://shopify.dev/docs/storefronts/mobile/checkout-kit/swift)

[Embed checkout in Android using the Kotlin SDK. - Android](https://shopify.dev/docs/storefronts/mobile/checkout-kit/android)

[Embed checkout in React Native apps. - React Native](https://shopify.dev/docs/storefronts/mobile/checkout-kit/react-native)

***

## Cart permalinks

Cart permalinks are URLs that take buyers directly to a merchant's checkout with pre-selected items. Use this for simpler flows where you just need to redirect buyers to complete their purchase, rather than managing checkout sessions programmatically with Checkout MCP.

The [Catalog](https://shopify.dev/docs/agents/catalog) returns a `checkoutUrl` for each product that you can open directly or embed in your application when calling the [`get_global_product_details` tool](https://shopify.dev/docs/agents/catalog/catalog-mcp#get_global_product_details).

### Get the checkout URL

When you call `get_global_product_details`, the Catalog MCP server returns a `checkoutUrl` in the response. This is a [cart permalink](https://shopify.dev/docs/apps/build/checkout/create-cart-permalinks) that takes buyers to the merchant's checkout with the product variant they selected.

```json
{
  "product": {
    "products": [{
      "checkoutUrl": "https://example.myshopify.com/cart/70881412:1?_gsid=abc123&payment=shop_pay",
      "selectedProductVariant": {
        "id": "gid://shopify/ProductVariant/70881412"
      }
    }]
  }
}
```

The URL includes tracking parameters for conversion attribution. You can append [additional parameters](https://shopify.dev/docs/apps/build/checkout/create-cart-permalinks#step-3-optional-modify-the-checkout) to prefill buyer information, apply discounts, or add custom tracking data.

### Redirect to checkout

Open the `checkoutUrl` to redirect buyers to the merchant's checkout. You can open the URL in a new tab to keep your agent interface available:

```javascript
const checkoutUrl = productResponse.product.products[0].checkoutUrl;
window.open(checkoutUrl, "_blank");
```

### Handle multiple merchants

The Catalog can return products from multiple merchants in a single search. Cart permalinks work for products from a single merchant only. When your agent returns products from different merchants, create separate checkout URLs for each:

```javascript
const productsByShop = {};
selectedProducts.forEach(product => {
  const shopDomain = new URL(product.shop.onlineStoreUrl).hostname;
  if (!productsByShop[shopDomain]) {
    productsByShop[shopDomain] = [];
  }
  productsByShop[shopDomain].push(product);
});


Object.entries(productsByShop).forEach(([shopDomain, products]) => {
  const variantIds = products.map(p => {
    const id = p.selectedProductVariant.id.split('/').pop();
    return `${id}:1`;
  }).join(',');
  
  const checkoutUrl = `https://${shopDomain}/cart/${variantIds}`;
  console.log(`Checkout for ${shopDomain}: ${checkoutUrl}`);
});
```

***

## Next steps

[Complete checkout\
\
](https://shopify.dev/docs/agents/get-started/complete-checkout)

[Walk through the full checkout flow end-to-end.](https://shopify.dev/docs/agents/get-started/complete-checkout)

[Checkout MCP reference\
\
](https://shopify.dev/docs/agents/checkout/mcp)

[Reference for UCP-compliant checkout on Shopify.](https://shopify.dev/docs/agents/checkout/mcp)

[Embedded Checkout Protocol\
\
](https://shopify.dev/docs/agents/checkout/ecp)

[Handle escalations by embedding checkout in your application.](https://shopify.dev/docs/agents/checkout/ecp)

***

* [How it works](https://shopify.dev/docs/agents/checkout.md#how-it-works)
* [Checkout sessions with MCP](https://shopify.dev/docs/agents/checkout.md#checkout-sessions-with-mcp)
* [Embed with Checkout Kit](https://shopify.dev/docs/agents/checkout.md#embed-with-checkout-kit)
* [Cart permalinks](https://shopify.dev/docs/agents/checkout.md#cart-permalinks)
* [Next steps](https://shopify.dev/docs/agents/checkout.md#next-steps)