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 aren't 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.
Anchor to How it worksHow 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: 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.
- Cart permalinks: URLs that take buyers directly to a merchant's checkout with pre-selected items. The Catalog returns a
checkoutUrlfor each product that you can open directly or embed in your application for simpler flows.
Anchor to Checkout sessions with MCPCheckout sessions with MCP
The Checkout MCP server implements UCP's checkout capability through these tools:
create_checkout: Initiates a new checkout session with line items and buyer information.update_checkout: Modifies items, fulfillment options, or buyer information to resolve missing data.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:
- Create a checkout session with line items and buyer information
- Update the checkout to resolve any missing information, or escalate to a trusted UI for buyer input
- Complete the checkout when status reaches
ready_for_complete
Anchor to Status-driven workflowStatus-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. |
Anchor to Resolving incomplete statusResolving 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. After you've addressed the issues, the next response returns an updated status.
Anchor to Resolving escalationsResolving 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 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_urldirectly in a browser or web view. This is the simplest approach. - Embedded Checkout Protocol 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 and the ECP specification 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.
Anchor to Completing the checkoutCompleting the checkout
When status reaches ready_for_complete, call complete_checkout to finalize the order. The response includes status completed when the order is placed successfully.
Anchor to Payment handlersPayment 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.
Anchor to Shop PayShop 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.
Anchor to Embed with Checkout KitEmbed 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.
Anchor to Cart permalinksCart 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 returns a checkoutUrl for each product that you can open directly or embed in your application when calling the get_global_product_details tool.
Anchor to Get the checkout URLGet 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 that takes buyers to the merchant's checkout with the product variant they selected.
The URL includes tracking parameters for conversion attribution. You can append additional parameters to prefill buyer information, apply discounts, or add custom tracking data.
Anchor to Redirect to checkoutRedirect 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:
Anchor to Handle multiple merchantsHandle 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:
