Products

The Product Catalog API provides complete product management including variants, collections, inventory tracking, and search.

Product Structure

A product in Hanzo Commerce has the following structure:

{
  "id": "prod_abc123",
  "name": "Premium T-Shirt",
  "slug": "premium-t-shirt",
  "description": "High-quality cotton t-shirt",
  "price": 2999,
  "currency": "USD",
  "images": [
    {
      "url": "https://cdn.hanzo.ai/images/shirt.jpg",
      "alt": "Premium T-Shirt"
    }
  ],
  "variants": [...],
  "collections": ["apparel", "featured"],
  "inventory": {
    "quantity": 100,
    "trackInventory": true
  },
  "metadata": {
    "brand": "Hanzo",
    "material": "100% Cotton"
  }
}

Creating Products

Basic Product

curl -X POST https://api.hanzo.ai/product \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium T-Shirt",
    "slug": "premium-t-shirt",
    "price": 2999,
    "currency": "USD",
    "description": "High-quality cotton t-shirt"
  }'

Product with Variants

curl -X POST https://api.hanzo.ai/product \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium T-Shirt",
    "slug": "premium-t-shirt",
    "price": 2999,
    "currency": "USD",
    "options": [
      {"name": "Size", "values": ["S", "M", "L", "XL"]},
      {"name": "Color", "values": ["Black", "White", "Navy"]}
    ]
  }'

This automatically creates variants for each option combination.

Managing Variants

List Variants

curl https://api.hanzo.ai/product/prod_abc123/variant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Variant

curl -X PATCH https://api.hanzo.ai/variant/var_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 3499,
    "sku": "SHIRT-BLK-M",
    "inventory": {
      "quantity": 50
    }
  }'

Variant Structure

{
  "id": "var_xyz789",
  "productId": "prod_abc123",
  "sku": "SHIRT-BLK-M",
  "price": 2999,
  "options": {
    "Size": "M",
    "Color": "Black"
  },
  "inventory": {
    "quantity": 50,
    "reserved": 5
  }
}

Collections

Collections group related products for merchandising.

Create a Collection

curl -X POST https://api.hanzo.ai/collection \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale",
    "slug": "summer-sale",
    "description": "Hot deals for summer",
    "products": ["prod_abc123", "prod_def456"]
  }'

Add Products to Collection

curl -X POST https://api.hanzo.ai/collection/coll_123/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["prod_ghi789"]
  }'

Inventory Management

Update Inventory

curl -X PATCH https://api.hanzo.ai/variant/var_xyz789/inventory \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 100,
    "trackInventory": true,
    "allowBackorder": false
  }'

Reserve Inventory

When an order is placed, inventory is automatically reserved:

{
  "quantity": 100,
  "reserved": 5,
  "available": 95
}

Product Search

Basic Search

curl "https://api.hanzo.ai/product?q=shirt" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filtered Search

curl "https://api.hanzo.ai/product?collection=apparel&minPrice=1000&maxPrice=5000&sort=price:asc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search Parameters

Parameter	Description
`q`	Full-text search query
`collection`	Filter by collection slug
`minPrice`	Minimum price in cents
`maxPrice`	Maximum price in cents
`sort`	Sort field and direction
`limit`	Results per page (default: 20)
`offset`	Pagination offset

Pricing

Price Tiers

Support volume-based pricing:

curl -X PATCH https://api.hanzo.ai/product/prod_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "priceTiers": [
      {"minQuantity": 1, "price": 2999},
      {"minQuantity": 10, "price": 2499},
      {"minQuantity": 50, "price": 1999}
    ]
  }'

Sale Pricing

curl -X PATCH https://api.hanzo.ai/product/prod_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "compareAtPrice": 3999,
    "price": 2999,
    "saleEndsAt": "2024-12-31T23:59:59Z"
  }'

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// Create product with variants
const product = await commerce.products.create({
  name: 'Premium T-Shirt',
  price: 2999,
  options: [
    { name: 'Size', values: ['S', 'M', 'L'] },
    { name: 'Color', values: ['Black', 'White'] }
  ]
})

// Search products
const results = await commerce.products.search({
  query: 'shirt',
  collection: 'apparel',
  limit: 20
})

Go

product, err := client.Products.Create(ctx, &sdk.ProductInput{
    Name:  "Premium T-Shirt",
    Price: 2999,
    Options: []sdk.ProductOption{
        {Name: "Size", Values: []string{"S", "M", "L"}},
        {Name: "Color", Values: []string{"Black", "White"}},
    },
})

On this page