Cart API implementation

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 for the high-level concepts and prerequisites.

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.