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

While no authentication is required, Google supports the following options for use when calling the business's checkout API endpoint.

API keys

HTTP Header: X-API-Key

A shared secret value which will be used in Google's UCP API client request HTTP header to authenticate with the checkout endpoint.

HTTP Header: Authorization: Bearer <Access Token>

Following RFC 6749, Google's UCP Platform agent uses the following properties to request the access tokens needed for checkout endpoint interaction.

Property Description
Client ID A unique string representing the client (for example, Google's UCP API client)
Client Secret A password type string used to authenticate with the authorization server
Authorization endpoint URL The URL to the OAuth2 API endpoint
Format Basic authentication HTTP header or HTTP body
Encoding Form data or JSON

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:

  • 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.

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.

Next steps

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

Previous
Prepare your UCP profile
Next
Order lifecycle (post-purchase)