Checkout Capability

Checkout Capability

• Capability Name: dev.ucp.shopping.checkout

Overview

Allows platforms to facilitate checkout sessions. The checkout has to be finalized manually by the user through a trusted UI unless the AP2 Mandates extension is supported.

The business remains the Merchant of Record (MoR), and they don’t need to become PCI DSS compliant to accept card payments through this Capability.

Payments

Payment handlers are discovered from the business’s UCP profile at /.well-known/ucp and checkout.ucp.payment_handlers. The handlers define the processing specifications for collecting payment instruments (e.g., Google Pay, Shop Pay). When the buyer submits payment, the platform populates the payment.instruments array with the collected instrument data.

The payment object is optional on checkout creation and may be omitted for use cases that don’t require payment processing (e.g., quote generation, cart management).

Fulfillment

Fulfillment is modelled as an extension in UCP to account for diverse use cases.

Fulfillment is optional in the checkout object. This is done to enable a platform to perform checkout for digital goods without needing to furnish fulfillment details more relevant for physical goods.

Checkout Status Lifecycle

The checkout status field indicates the current phase of the session and determines what action is required next. The business sets the status; the platform receives messages indicating what’s needed to progress.

       +------------+                         +---------------------+
       | incomplete |<----------------------->| requires_escalation |
       +-----+------+                         |   (buyer handoff    |
             |                                |  via continue_url)  |
             | all info collected             +----------+----------+
             v                                           |
    +------------------+                                 |
    |ready_for_complete|                                 |
    |                  |                                 |
    | (platform can    |                                 | continue_url
    | call Complete    |                                 |
    |   Checkout)      |                                 |
    +--------+---------+                                 |
             |                                           |
             | Complete Checkout                         |
             v                                           |
   +--------------------+                                |
   |complete_in_progress|                                |
   +---------+----------+                                |
             |                                           |
             +-----------------------+-------------------+
                                     v
                               +-------------+
                               |  completed  |
                               +-------------+

                               +-------------+
                               |  canceled   |
                               +-------------+
          (session invalid/expired - can occur from any state)

Status Values

• incomplete: Checkout session is missing required information or has issues that need resolution. Platform should inspect messages array for context and should attempt to resolve via Update Checkout.

• requires_escalation: Checkout session requires information that cannot be provided via API, or buyer input is required. Platform should inspect messages to understand what’s needed (see Error Handling below). If any recoverable errors exist, resolve those first. Then hand off to buyer via continue_url.

• ready_for_complete: Checkout session has all necessary information and platform can finalize programmatically. Platform can call Complete Checkout.

• complete_in_progress: Business is processing the Complete Checkout request.

• completed: Order placed successfully.

• canceled: Checkout session is invalid or expired. Platform should start a new checkout session if needed.

Error Handling

The messages array contains errors, warnings, and informational messages about the checkout state. Error messages include a severity field that reflects the resource state and recommended action. When ucp.status is "success", a resource is returned and severity indicates the recommended action. When ucp.status is "error", no valid resource exists — severity is unrecoverable:

Severity	Meaning	Platform Action
recoverable	Platform can resolve by modifying inputs via API	Update resource and retry
requires_buyer_input	Business requires input not available via API	Hand off via continue_url
requires_buyer_review	Buyer review and authorization is required	Hand off via continue_url
unrecoverable	No resource exists to act on	Retry with new resource or inputs, or hand off via continue_url

Errors with requires_* severity contribute to status: requires_escalation. Both result in buyer handoff, but represent different checkout states.

• requires_buyer_input means the checkout is incomplete — the business requires information their API doesn’t support collecting programmatically.
• requires_buyer_review means the checkout is complete — but policy, regulatory, or entitlement rules require buyer authorization before order placement (e.g., high-value order approval, first-purchase policy).

When the business cannot create a new resource or the requested resource no longer exists, the response contains ucp.status: "error" with messages describing the failure — no resource is included in the response body. Error responses MUST use severity: "unrecoverable". For example, a business may reject a create checkout request where all items are unavailable:

{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}

Standard Errors

Standard errors are standardized error codes that platforms are expected to handle with specific, appropriate UX rather than generic error treatment.

Code	Description
out_of_stock	Specific item or variant is unavailable
item_unavailable	Item cannot be purchased (e.g. delisted)
address_undeliverable	Cannot deliver to the provided address
payment_failed	Payment processing failed

Continue URL

The continue_url field enables checkout handoff from platform to business UI, allowing the buyer to continue and finalize the checkout session.

Availability

Businesses MUST provide continue_url when returning status = requires_escalation. For all other non-terminal statuses (incomplete, ready_for_complete, complete_in_progress), businesses SHOULD provide continue_url. For terminal states (completed, canceled), continue_url SHOULD be omitted.

Guidelines

Platform

• MAY engage an agent to facilitate the checkout session (e.g. add items to the checkout session, select fulfillment address). However, the agent must hand over the checkout session to a trusted and deterministic UI for the user to review the checkout details and place the order.
• MAY send the user from the trusted, deterministic UI back to the agent at any time. For example, when the user decides to exit the checkout screen to keep adding items to the cart.
• MAY provide agent context when the platform indicates that the request was done by an agent.
• MUST use continue_url when checkout status is requires_escalation.
• MAY use continue_url to hand off to business UI in other situations.
• When performing handoff, SHOULD prefer business-provided continue_url over platform-constructed checkout permalinks.

Business

• MUST send a confirmation email after the checkout has been completed.
• SHOULD provide accurate error messages.
• Logic handling the checkout sessions MUST be deterministic.
• MUST provide continue_url when returning status = requires_escalation.
• MUST include at least one message with severity of requires_buyer_input or requires_buyer_review when returning status = requires_escalation.
• SHOULD provide continue_url in all non-terminal checkout responses.
• After a checkout session reaches the state “completed”, it is considered immutable.

Operations

The Checkout capability defines the following logical operations.

Operation	Description
Create Checkout	Initiates a new checkout session. Called as soon as a user adds an item to a cart.
Get Checkout	Retrieves the current state of a checkout session.
Update Checkout	Updates a checkout session.
Complete Checkout	Finalizes the checkout and places the order.
Cancel Checkout	Cancels a checkout session.

Transport Bindings

The abstract operations above are bound to specific transport protocols as defined below:

• REST Binding: RESTful API mapping using standard HTTP verbs and JSON payloads.
• MCP Binding: Model Context Protocol mapping for agentic interaction.
• A2A Binding: Agent-to-Agent Protocol mapping for agentic interactions.
• Embedded Checkout Binding: JSON-RPC for powering embedded checkout.