Cart Module

The Cart module manages shopping carts with automatic price calculation, promotion application, and tax computation.

Data Model

{
  "id": "cart_abc123",
  "regionId": "reg_us",
  "customerId": "cust_xyz",
  "items": [
    {
      "id": "item_001",
      "variantId": "var_abc",
      "productName": "Premium T-Shirt",
      "quantity": 2,
      "unitPrice": 2999,
      "total": 5998
    }
  ],
  "subtotal": 5998,
  "discount": 500,
  "tax": 494,
  "shipping": 799,
  "total": 6791,
  "currency": "USD",
  "promotions": ["SAVE10"],
  "shippingAddress": null,
  "paymentMethod": null,
  "completedAt": null,
  "expiresAt": "2025-01-22T10:00:00Z"
}

Key Concepts

Cart -- a temporary container of line items that becomes an order at checkout

Line Item -- a variant + quantity entry in the cart

Promotion -- a coupon code or automatic discount applied to the cart

Cart Expiry -- carts expire after a configurable period (default 7 days)

API Examples

Create a Cart

curl -X POST https://api.hanzo.ai/cart \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"regionId": "reg_us"}'

const cart = await commerce.carts.create({ regionId: 'reg_us' })

cart, err := client.Carts.Create(ctx, &sdk.CartInput{RegionID: "reg_us"})

Add Items

curl -X POST https://api.hanzo.ai/cart/cart_abc123/item \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variantId": "var_abc", "quantity": 2}'

Update Item Quantity

curl -X PATCH https://api.hanzo.ai/cart/cart_abc123/item/item_001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'

Apply a Promotion Code

curl -X POST https://api.hanzo.ai/cart/cart_abc123/promotion \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "SAVE10"}'

Set Shipping Address

curl -X PATCH https://api.hanzo.ai/cart/cart_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingAddress": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }
  }'

Complete Cart (Convert to Order)

curl -X POST https://api.hanzo.ai/cart/cart_abc123/complete \
  -H "Authorization: Bearer $TOKEN"

Calculation Pipeline

When a cart is modified, totals are recalculated automatically:

Line Items ──► Pricing Module (unit prices)
           ──► Promotion Module (discounts)
           ──► Tax Module (tax amounts)
           ──► Fulfillment Module (shipping cost)
           ──► Final totals

Configuration

cart:
  expiry_days: 7                # cart TTL
  max_items: 50                 # max line items per cart
  allow_empty_checkout: false   # require at least one item
  auto_remove_unavailable: true # remove out-of-stock items

Events

Event	Description
`cart.created`	New cart initialized
`cart.updated`	Items or address changed
`cart.completed`	Cart converted to order
`cart.abandoned`	Cart expired without completion

Abandoned cart events fire after the expiry window. Use these to trigger recovery email campaigns via the Analytics module.

On this page