Promotions

The Promotions API discounts an amount or percentage off a cart's items, its shipping, or the entire order — governed by rules that decide when the discount applies and grouped into campaigns that cap spend and set a schedule.

Base URL: https://api.hanzo.ai/v1/commerce/promotions

Promotion types

Application method

Every promotion has an application method describing the discount:

import { HanzoCommerce } from '@hanzo/commerce'

const commerce = new HanzoCommerce({ apiKey: process.env.HANZO_API_KEY })

const promo = await commerce.promotions.create({
  code: 'WELCOME10',
  type: 'standard',
  application_method: {
    type: 'percentage',
    target_type: 'items',
    value: 10,
    allocation: 'each'
  }
})

Flexible rules

Rules restrict when a promotion is applied by matching attributes of the cart, its items, or the customer. Combine multiple rules — all must pass.

{
  "rules": [
    { "attribute": "customer.groups.id", "operator": "in", "values": ["cusgroup_vip"] },
    { "attribute": "items.product.collection", "operator": "eq", "values": ["col_outerwear"] },
    { "attribute": "currency_code", "operator": "eq", "values": ["usd"] }
  ]
}

Supported operators: eq, ne, in, not_in, gt, gte, lt, lte.

Target a promotion at a customer group with a customer.groups.id rule to run tiered or member-only pricing without touching individual customers.

Promotion codes

A promotion can be automatic (applies with no code) or gated behind a code the shopper enters. Generate many unique codes for a single promotion when you need per-recipient tracking.

# Apply a code to a cart
curl -X POST https://api.hanzo.ai/v1/commerce/carts/cart_1/promotions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "WELCOME10" }'

Campaigns

A campaign groups promotions under a shared schedule and budget. When the budget is spent or the window closes, its promotions stop applying automatically.

const campaign = await commerce.promotions.createCampaign({
  name: 'Spring Sale',
  starts_at: '2026-03-01T00:00:00Z',
  ends_at: '2026-03-31T23:59:59Z',
  budget: { type: 'spend', limit: 100000, currency: 'USD' },
  promotion_ids: [promo.id]
})

Budget types: spend (cap total discount value) or usage (cap number of redemptions).

Endpoints

Next steps

Scope promotions to customer groups

Promotion adjustments are recorded on order line items

Match promotions against product attributes and collections