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

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.