Native checkout overview

To enable users to check out, you must implement the Native checkout integration. This involves creating a standard REST API that allows Google to programmatically manage the checkout flow with your servers. This method provides the most seamless experience for users. Initially, Google will render the user interface for the buyer, with future plans to support more agentic experiences.

Checkout flow

The Native integration requires you to build a RESTful API that Google can call to create and manage checkout sessions.

The overall flow is as follows:

1. Build checkout session: the user and optionally an Agent are in a loop adding items to the session.
2. Handoff to a Google UI: once the user decides to check out the Agent (if engaged) passes the control to a Google UI (passing the checkout session data)
3. Manual checkout: the user now interacts only with the Google UI to fill in sensitive fulfillment and payment details and submit the order. The Agent is not involved in this part, ensuring determinism.
4. Completion & return: the Google UI shows a "Thank You" page to confirm the order. Optionally, the user can be redirected back to the Agent, who may have already been notified of the completed purchase.

Checkout session status lifecycle

As the user progresses through the checkout flow, you must update the checkout session status to reflect its current state. The session moves through the following lifecycle:

• incomplete: the initial status when a session is created. This indicates that mandatory information (such as shipping methods, taxes, or user details) is missing or uncalculated.
• ready_for_payment: the status to use after the user updates their shipping address and you compute shipping options and totals, but before the payment instrument is finalized.
• ready_for_complete: the status to use during full checkout object hydration, once the payment instrument is selected and all order details are validated.
• completed: the final status returned after you successfully process the payment and place the order.
• canceled: the status returned if the checkout session is aborted.
• error: the status returned if an unrecoverable business logic error prevents checkout. This status is available in UCP version 2026-04-08 and later.

Multi-Item Checkout Flow:

Google now supports multiple distinct line items in a single checkout session. The general flow is as follows:

1. The user initiates checkout from a UCP-enabled interface (e.g., by clicking "Buy now" on a product).
2. The POST /checkout-sessions call is made, including all distinct items in the line_items array. The line_items array will contain a separate object for each unique item being checked out.
3. The user can update their payment instrument, fulfillment details, or apply discounts using PUT /checkout-sessions/{id} calls.
4. When the user clicks the "Pay with GPay" button, the POST /checkout-sessions/{id}/complete call is made.

Authentication

For details on securing your Native Checkout API endpoints, including supported authentication methods like API keys, OAuth 2.0, and Mutual TLS (mTLS), see the Authentication guide.

Developer tools

To assist with your Native Checkout API implementation, you can find the following resources in the Universal Commerce Protocol GitHub repository:

• UCP GitHub repository: explore the main repository for comprehensive documentation, specifications, and community resources.
• SDKs: use the Software Development Kits to accelerate your integration. Language-specific SDKs are available, including:
  • Python SDK
  • JavaScript SDK

• Conformance tests: validate your API endpoints against the UCP specification using the conformance test suite

  This helps ensure your implementation meets the required standards and behaviors.

We strongly recommend using these tools to streamline your development and testing process.

Service level objectives

The following service level objectives (SLOs) apply to the Native Checkout REST API endpoints. Businesses integrating with Google are expected to meet these targets for API performance and availability. All latency percentiles are measured over a rolling 24-hour interval.

Endpoint	Availability	Latency (50th Percentile)	Latency (95th Percentile)
POST /checkout-sessions (Create)	>= 95%	<= 1 second	<= 4 seconds
PUT /checkout-sessions/{id} (Update)	>= 95%	<= 1 second	<= 5 seconds
POST /checkout-sessions/{id}/complete (Complete)	>= 95%	<= 6 seconds	<= 10 seconds

The 50th percentile latency indicates that at least 50% of requests are expected to be completed within this time. The 95th percentile latency indicates that at least 95% of requests are expected to be completed within this time.

Latency optimization

To meet the latency targets defined in the Service level objectives, follow these best practices.

General optimizations

• Maintain connection state: enable HTTP/2 connection reuse and Transport Layer Security (TLS) session resumption on your gateway to minimize handshake overhead.

Create checkout

• Parallelize operations: execute inventory checks, tax calculations, and shipping computations concurrently.
• Implement soft reservations: apply in-memory reservations or soft locks instead of blocking database inventory locks.
• Process partial addresses: compute shipping costs and tax using zip codes instead of complete shipping addresses.
• Process partial addresses: compute or use zip code-based cached values for shipping costs and tax estimates instead of requiring complete shipping addresses.
• Defer fraud screening: bypass risk and fraud analysis during session creation, as payment signals are not yet available.

Update checkout

• Isolate recalculations: compute updates only for modified parameters (such as shipping addresses) rather than recalculating the entire checkout object.
• Provide granular breakdowns: return itemized price breakdowns (subtotals, tax, shipping) to enable Google to process minor state changes without redundant calls to your servers.

Complete checkout

• Decouple settlement phases: restrict synchronous execution to payment authorization, final tax or stock checks, and order generation.
• Offload downstream tasks: delegate secondary processing, such as confirmation emails and fulfillment queuing, to asynchronous background processes or webhooks to manage the order lifecycle efficiently.
• Handle errors gracefully: return 200 OK with structured UCP error payloads for payment declines instead of 4xx error codes. This allows the user interface to display a clear message so the user can quickly select another card. For more information, see Error codes.

Next steps

View the checkout API payloads and technical implementation details for your UCP version:

• Version 2026-04-08 Native checkout REST API
• Version 2026-01-23 Native checkout REST API

If you are integrating as a third-party service provider, proceed to UCP Checkout service setup to host merchant profiles and configure account relationship handshakes.