This guide provides the technical API reference and payload schemas for
integrating the Universal Commerce Protocol (UCP) Cart API in version
`2026-04-08`.

Before building your endpoints, ensure you have reviewed the [Cart API
overview](https://developers.google.com/merchant/ucp/guides/overview/cart-overview) for the high-level
concepts and prerequisites.

> [!TIP]
> **Tip:** To ensure your API meets the recommended performance targets, review the [Service level objectives and capacity planning](https://developers.google.com/merchant/ucp/guides/overview/cart-overview#slo-capacity) guidelines.

## 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 all the line items details. Your system
must respond with a `continue_url` directing the user to their pre-populated
cart on your site.

- **Endpoint:** `POST /carts`
- **Trigger:** a single `CreateCart` (`POST /carts`) request is triggered only when the user clicks the transfer button (for example, **Checkout on merchant**) to transfer their cart to your store.

### Cart flow

The cart flow and state work as follows:

- **Accumulation on Google:** when a user adds items to their cart, Google accumulates those items locally. Google does not fire multiple API calls as items are added.
- **The payload:** the single `POST /carts` request will contain the complete array of all accumulated `line_items` at once.
- **Redirection and state:** the merchant's backend responds with a `continue_url` pointing to the pre-populated cart on their website.

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

Request example:

    {
      "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.

Response example:

    {
      "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

For complete guidelines on how to format error messages and the distinction between protocol and business logic errors, see the [Error codes](https://developers.google.com/merchant/ucp/guides/overview/error-codes).