Collections API

The Collections API lets you group products into curated or rule-based collections for storefront navigation, promotions, and merchandising.

Collection Structure

{
  "id": "col_summer",
  "name": "Summer Collection",
  "slug": "summer-collection",
  "description": "Light and breathable styles for the warm season.",
  "type": "manual",
  "status": "published",
  "image": {
    "url": "https://cdn.hanzo.ai/collections/summer.jpg",
    "alt": "Summer Collection"
  },
  "conditions": [],
  "sortOrder": "manual",
  "productCount": 24,
  "metadata": {
    "season": "summer",
    "year": "2024"
  },
  "createdAt": "2024-03-01T08:00:00Z",
  "updatedAt": "2024-06-10T12:00:00Z"
}

Collection Types

Type	Description
`manual`	Products are added and ordered manually
`automated`	Products are included based on condition rules

Endpoints

List Collections

GET /collection

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`display`	number	Items per page (default: 20, max: 100)
`sort`	string	Sort field (e.g. `name:asc`, `createdAt:desc`)
`status`	string	`published`, `draft`
`type`	string	`manual`, `automated`
`q`	string	Search by name

curl "https://api.hanzo.ai/collection?status=published&sort=name:asc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 8,
  "models": [
    {
      "id": "col_summer",
      "name": "Summer Collection",
      "slug": "summer-collection",
      "status": "published",
      "type": "manual",
      "productCount": 24
    }
  ]
}

Get Collection

GET /collection/:id

Retrieve a collection with optional product expansion.

curl "https://api.hanzo.ai/collection/col_summer?expand=products" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Collection

POST /collection

curl -X POST https://api.hanzo.ai/collection \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Collection",
    "slug": "summer-collection",
    "description": "Light and breathable styles for the warm season.",
    "type": "manual",
    "status": "published",
    "sortOrder": "manual",
    "metadata": {
      "season": "summer",
      "year": "2024"
    }
  }'

Response: 201 Created

{
  "id": "col_summer",
  "name": "Summer Collection",
  "slug": "summer-collection",
  "status": "published",
  "type": "manual",
  "productCount": 0,
  "createdAt": "2024-03-01T08:00:00Z"
}

Update Collection

PUT /collection/:id

curl -X PUT https://api.hanzo.ai/collection/col_summer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated summer styles for 2024.",
    "status": "published"
  }'

Delete Collection

DELETE /collection/:id

curl -X DELETE https://api.hanzo.ai/collection/col_summer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response: 204 No Content

Deleting a collection does not delete the products within it. Products remain in the catalog and in any other collections they belong to.

Product Associations

Add Products to Collection

POST /collection/:id/products

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

Remove Products from Collection

DELETE /collection/:id/products

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

Reorder Products

PUT /collection/:id/products/reorder

curl -X PUT https://api.hanzo.ai/collection/col_summer/products/reorder \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_def456", "prod_abc123", "prod_ghi789"]
  }'

Automated Conditions

For automated collections, define conditions that determine which products are included.

curl -X POST https://api.hanzo.ai/collection \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On Sale",
    "slug": "on-sale",
    "type": "automated",
    "status": "published",
    "conditions": [
      { "field": "compareAtPrice", "operator": "gt", "value": "0" },
      { "field": "status", "operator": "eq", "value": "published" }
    ],
    "conditionMatch": "all"
  }'

Condition Fields:

Field	Description
`tag`	Product tags
`price`	Product price in cents
`compareAtPrice`	Compare-at price
`status`	Product status
`vendor`	Product vendor
`inventoryQuantity`	Total inventory count

Condition Operators:

Operator	Description
`eq`	Equals
`neq`	Not equals
`gt`	Greater than
`lt`	Less than
`contains`	Contains string
`startsWith`	Starts with string

Condition Match:

Value	Description
`all`	Product must match all conditions
`any`	Product must match at least one condition

Sort Orders

Value	Description
`manual`	Custom order (manual collections only)
`bestSelling`	Highest order count first
`price:asc`	Lowest price first
`price:desc`	Highest price first
`name:asc`	Alphabetical A-Z
`name:desc`	Alphabetical Z-A
`createdAt:desc`	Newest first

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// List collections
const collections = await commerce.collections.list({
  status: 'published',
  sort: 'name:asc'
})

// Create manual collection
const collection = await commerce.collections.create({
  name: 'Summer Collection',
  slug: 'summer-collection',
  type: 'manual',
  status: 'published'
})

// Add products
await commerce.collections.addProducts(collection.id, [
  'prod_abc123', 'prod_def456'
])

// Create automated collection
await commerce.collections.create({
  name: 'On Sale',
  slug: 'on-sale',
  type: 'automated',
  conditions: [
    { field: 'compareAtPrice', operator: 'gt', value: '0' }
  ],
  conditionMatch: 'all'
})

Go

collections, err := client.Collections.List(ctx, &sdk.CollectionListParams{
    Status: "published",
    Sort:   "name:asc",
})

collection, err := client.Collections.Create(ctx, &sdk.CollectionInput{
    Name:   "Summer Collection",
    Slug:   "summer-collection",
    Type:   "manual",
    Status: "published",
})

err = client.Collections.AddProducts(ctx, collection.ID, []string{
    "prod_abc123", "prod_def456",
})

On this page