Carts and checkout for agents
Carts and checkout in Universal Commerce Protocol (UCP) let your agent move buyers from product selection to purchase. Build a cart to iterate on line items and totals while the buyer is still shopping. When they're ready to buy, follow the cart's continue_url to hand off to the merchant's checkout, or create a checkout session when finalized values are critical to the buyer's experience.
The merchant always remains the merchant of record. When eligible, your agent can complete the checkout directly. When a purchase requires escalation or review, redirect the buyer to the merchant's prefilled checkout for completion.
Tool use is subject to access and rate limiting that scale with how your agent identifies itself. See Auth and rate limiting for traffic tiers and what each can do.
Tool use is subject to access and rate limiting that scale with how your agent identifies itself. See Auth and rate limiting for traffic tiers and what each can do.
Anchor to How it worksHow it works
After product discovery, your agent can move buyers toward purchase using one of the following approaches:
- Cart MCP: Build and iterate on a cart before the buyer commits to purchase. Cart tools accept unauthenticated requests, which lets your agent estimate totals and share a cart with the buyer before collecting credentials.
- Checkout MCP: Create and manage a checkout session, optionally converting a cart into a checkout. Checkout tools require authentication or a signed request.
- Cart permalinks: URLs that take buyers directly to a merchant's checkout with pre-selected items. The Catalog returns a
checkout_urlfor each variant that you can use directly in your agent for simpler flows.
Anchor to End-to-end flowEnd-to-end flow
A typical purchase flow combines Cart MCP and Checkout MCP:
- Your agent authenticates itself and gets an access token.
- A buyer discovers products using the Catalog MCP, with results optionally scoped to a custom catalog.
- (Optional) Build a cart with
create_cart, iterating on line items and context until the buyer is ready to purchase. - Call
create_checkoutwith the selected line items, or passcart_idto convert an existing cart into a checkout. - Call
update_checkoutas needed to resolve missing data or add more line items. - Direct the buyer to the
continue_urlin the response to finish checkout on the merchant's storefront.
Anchor to Cart MCPCart MCP
Cart MCP implements UCP's cart capability. A cart holds line items, localization context, and buyer information. Use carts to iterate on line items across multiple conversations, show estimated totals before the buyer commits, or hand off a cart to the buyer via continue_url without starting a checkout session. Carts are designed for long-running, exploratory sessions.
Cart tools accept unauthenticated requests, so your agent can call them while the buyer is still browsing:
| Tool | Description |
|---|---|
create_cart | Start a new cart with line items and optional context. |
get_cart | Fetch the current cart state and totals. |
update_cart | Replace the cart's contents. |
cancel_cart | Delete the cart. No further action can be taken. |
update_cart uses PUT semantics. This differs from Storefront API and AJAX cart mutations, which patch individual fields. Each update_cart request replaces the cart's full state with the payload you send. Omit a field and it's removed from the cart.
update_cart uses PUT semantics. This differs from Storefront API and AJAX cart mutations, which patch individual fields. Each update_cart request replaces the cart's full state with the payload you send. Omit a field and it's removed from the cart.
Anchor to Checkout MCPCheckout MCP
Checkout MCP implements UCP's checkout capability. A checkout session represents an active purchase. Use checkout tools once the buyer is ready to buy to resolve fulfillment or buyer details and then refer them to the merchant's storefront.
Checkout tools require authentication or a signed request:
| Tool | Description |
|---|---|
create_checkout | Start a new checkout session, optionally from an existing cart. |
get_checkout | Fetch the current checkout state. |
update_checkout | Update items, fulfillment options, or buyer information. |
complete_checkout | Finalize the checkout after the buyer completes payment on the storefront. |
cancel_checkout | Cancel an in-progress checkout session. |
Every checkout response includes a status and a messages array. Non-terminal states (incomplete, requires_escalation, ready_for_complete) also include a continue_url that hands the buyer off to the merchant's storefront. See Checkout status for the full lifecycle and response shape.
Anchor to Convert a cart into a checkoutConvert a cart into a checkout
When the buyer is ready to purchase, convert a cart from Cart MCP into a checkout by passing the cart's id as cart_id on create_checkout. The merchant uses the cart's line items, context, and buyer when creating the checkout, and ignores any overlapping fields in the checkout payload. Conversion is idempotent: calling create_checkout with the same cart_id twice returns the same incomplete checkout.
See Convert a cart into a checkout for the full rules.
Anchor to Cart permalinksCart permalinks
Cart permalinks are URLs that take buyers directly to a merchant's checkout with pre-selected items. Use permalinks for simpler flows where you redirect buyers without managing a cart or checkout session programmatically.
Anchor to Get a permalink from the Global CatalogGet a permalink from the Global Catalog
The Global Catalog returns a checkout_url for each variant when you call get_product:
Anchor to Customize the permalinkCustomize the permalink
You can append query parameters to prefill buyer information, apply discounts, add custom tracking data, or attribute marketing campaigns. See supported checkout parameters for the full list:
Anchor to Handle multiple merchantsHandle multiple merchants
The Global Catalog can return products from multiple merchants in a single search. Cart permalinks are scoped to a single merchant, so when buyers select variants from different merchants, group them by shop domain and create a separate checkout URL for each:
