Customer Module

The Customer module manages user accounts, authentication via Hanzo ID, saved addresses, and customer segmentation through groups.

Data Model

{
  "id": "cust_abc123",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+14155551234",
  "addresses": [
    {
      "id": "addr_001",
      "label": "Home",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "isDefault": true
    }
  ],
  "groups": ["vip", "wholesale"],
  "metadata": {},
  "orderCount": 12,
  "totalSpent": 45800,
  "currency": "USD",
  "createdAt": "2024-06-01T08:00:00Z"
}

Key Concepts

Customer -- an authenticated user who can place orders and manage their profile

Address -- a saved shipping or billing address associated with a customer

Group -- a tag used for segmentation (VIP, wholesale, B2B) that can trigger special pricing or promotions

Guest -- unauthenticated checkout creates a minimal customer record linked by email

API Examples

Register a Customer

curl -X POST https://api.hanzo.ai/customer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "password": "securePassword123"
  }'

const customer = await commerce.customers.create({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Doe',
  password: 'securePassword123',
})

customer, err := client.Customers.Create(ctx, &sdk.CustomerInput{
    Email:     "[email protected]",
    FirstName: "Jane",
    LastName:  "Doe",
    Password:  "securePassword123",
})

Add an Address

curl -X POST https://api.hanzo.ai/customer/cust_abc123/address \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Office",
    "line1": "456 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  }'

Assign to a Group

curl -X POST https://api.hanzo.ai/customer/cust_abc123/group \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group": "vip"}'

List Customers with Filters

curl "https://api.hanzo.ai/customer?group=vip&minOrders=5&sort=totalSpent:desc" \
  -H "Authorization: Bearer $TOKEN"

Authentication

Customer authentication is handled through Hanzo ID (OAuth2):

// Storefront login
const session = await commerce.auth.login({
  email: '[email protected]',
  password: 'securePassword123',
})

// Use the session token for subsequent requests
commerce.setToken(session.accessToken)

Configuration

customer:
  require_email_verification: true
  allow_guest_checkout: true
  password_min_length: 8
  max_addresses: 10
  auto_merge_guest: true  # merge guest orders when they register

Events

Event	Description
`customer.created`	New customer registered
`customer.updated`	Profile or address changed
`customer.group_added`	Customer added to a group
`customer.merged`	Guest account merged with registered account

On this page