Shopping Cart

The Cart API provides persistent shopping carts with support for coupons, discounts, tax calculation, and shipping estimates.

Cart Structure

{
  "id": "cart_abc123",
  "userId": "user_xyz789",
  "items": [
    {
      "id": "item_001",
      "productId": "prod_abc123",
      "variantId": "var_xyz789",
      "quantity": 2,
      "price": 2999,
      "subtotal": 5998
    }
  ],
  "subtotal": 5998,
  "discount": 500,
  "tax": 540,
  "shipping": 599,
  "total": 6637,
  "couponCode": "SAVE10",
  "currency": "USD"
}

Creating a Cart

Anonymous Cart

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

User Cart

curl -X POST https://api.hanzo.ai/cart \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_xyz789"
  }'

Managing Cart Items

Add Item

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

Update Quantity

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

Remove Item

curl -X DELETE https://api.hanzo.ai/cart/cart_abc123/item/item_001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Clear Cart

curl -X DELETE https://api.hanzo.ai/cart/cart_abc123/items \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Coupons and Discounts

Apply Coupon

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

Response includes recalculated totals:

{
  "id": "cart_abc123",
  "couponCode": "SAVE10",
  "subtotal": 5998,
  "discount": 600,
  "total": 5938,
  "coupon": {
    "code": "SAVE10",
    "type": "percentage",
    "value": 10,
    "description": "10% off your order"
  }
}

Remove Coupon

curl -X DELETE https://api.hanzo.ai/cart/cart_abc123/coupon \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Coupon Types

Type	Description	Example
`percentage`	Percentage off subtotal	10% off
`fixed`	Fixed amount off	$5 off
`free_shipping`	Waives shipping cost	Free shipping
`buy_x_get_y`	Buy X get Y free	Buy 2 get 1 free

Automatic Discounts

Discounts can be applied automatically based on rules:

{
  "discount": {
    "type": "automatic",
    "rule": "spend_100_get_10_off",
    "amount": 1000,
    "description": "Spend $100, get $10 off"
  }
}

Shipping Estimates

Get Shipping Options

curl -X POST https://api.hanzo.ai/cart/cart_abc123/shipping \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "postalCode": "94102",
      "country": "US"
    }
  }'

Response:

{
  "options": [
    {
      "id": "standard",
      "name": "Standard Shipping",
      "price": 599,
      "estimatedDays": "5-7"
    },
    {
      "id": "express",
      "name": "Express Shipping",
      "price": 1499,
      "estimatedDays": "2-3"
    }
  ]
}

Select Shipping

curl -X PATCH https://api.hanzo.ai/cart/cart_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shippingMethod": "express"
  }'

Tax Calculation

Taxes are calculated automatically based on shipping address:

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

Response:

{
  "taxRate": 0.0875,
  "taxAmount": 524,
  "taxBreakdown": [
    {"name": "State Tax", "rate": 0.06, "amount": 360},
    {"name": "County Tax", "rate": 0.0025, "amount": 15},
    {"name": "City Tax", "rate": 0.0125, "amount": 75},
    {"name": "District Tax", "rate": 0.0125, "amount": 74}
  ]
}

Cart Merging

When a user logs in, merge their anonymous cart with their account cart:

curl -X POST https://api.hanzo.ai/cart/merge \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceCartId": "cart_anonymous",
    "targetUserId": "user_xyz789"
  }'

Abandoned Cart Recovery

Track and recover abandoned carts:

# List abandoned carts (admin only)
curl "https://api.hanzo.ai/cart?abandoned=true&since=2024-01-01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

const commerce = new Commerce({ apiKey: 'your_key' })

// Create cart and add items
const cart = await commerce.carts.create()

await commerce.carts.addItem(cart.id, {
  productId: 'prod_abc123',
  variantId: 'var_xyz789',
  quantity: 2
})

// Apply coupon
await commerce.carts.applyCoupon(cart.id, 'SAVE10')

// Get shipping options
const shipping = await commerce.carts.getShippingOptions(cart.id, {
  postalCode: '94102',
  country: 'US'
})

// Calculate tax
await commerce.carts.calculateTax(cart.id, {
  line1: '123 Main St',
  city: 'San Francisco',
  state: 'CA',
  postalCode: '94102',
  country: 'US'
})

Go

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

err = client.Carts.AddItem(ctx, cart.ID, &sdk.CartItemInput{
    ProductID: "prod_abc123",
    VariantID: "var_xyz789",
    Quantity:  2,
})

err = client.Carts.ApplyCoupon(ctx, cart.ID, "SAVE10")

On this page