Cart API

This guide describes how to integrate with the Universal Commerce Protocol (UCP) Cart API, allowing users to build and manage a shopping cart across Google surfaces, including AI Mode in Google Search and Gemini. This capability is designed for basket building before the user has expressed explicit intent to checkout.

Note: This Cart API is a new feature and is only available starting with UCP version 2026-04-08.

Overview

The UCP Cart API (Capability Name: dev.ucp.shopping.cart ) enables the transfer of a user's shopping cart from Google surfaces, such as AI Mode in Google Search and Gemini, directly to your website. This API supports Google's Universal Cart feature by allowing a one-way population of the cart on your system, primarily through the CreateCart endpoint. This API is distinct from the Checkout API, as it does not handle payments or the full purchase lifecycle.

Note: This initial release is limited to cart creation and transfer using the CreateCart method. Features like updating, deleting, or synchronizing cart contents between Google and your system are not supported.

Key Benefits of Implementing CreateCart:

• For Users: A seamless transition from product discovery on Google to a pre-populated cart on your website.
• For Merchants: Receive user carts directly from Google, simplifying the initial purchase steps for customers and providing opportunities for upselling and cross-selling on your website.

Prerequisites

• Ensure your system is set up to handle UCP version 2026-04-08.
• Publish your UCP profile at /.well-known/ucp and include the dev.ucp.shopping.cart capability, as described in the UCP Profile guide. The endpoint specified in your profile (for example, https://business.example.com/ucp/v1) will be used as the base URL for these API calls.

Cart REST API implementation

The following steps describe the API endpoints you will need to implement.

Create Cart

This endpoint allows the creation of a new cart session. To integrate, implement the CreateCart endpoint (POST /carts). When a user opts to transfer their cart, Google calls this endpoint with the line item details. Your system must respond with a continue_url directing the user to their pre-populated cart on your site.

• Endpoint: POST /carts
• Trigger: User clicks "Add to cart" on a product and adds the first item to the cart for the merchant.

Request: Google sends the array of line_items to be added to the cart.

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ],
}

Response: You return the initialized cart session including line item details, totals, and a continue_url. The continue_url field in the response must direct the user back to a page on your site where they can continue managing the cart. This typically links to your cart or checkout page with the session identified by id pre-loaded.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid
  "expires_at": "2026-01-16T12:00:00Z"
}

Error Handling

How to report errors depends on the error type:

1. Protocol/Server Errors:

   • Use standard HTTP status codes (e.g., 4xx for client errors, 5xx for server errors) for issues like malformed requests, authentication failures, or server unavailability.
   • Refer to the UCP Specification for details.

2. Business Logic Errors/Warnings:

   • Return an HTTP 200 OK status.
   • Describe the issue within the messages array in the JSON response body and refer to the standardized codes from the Error Codes guide for all business logic issues.