Coupons & Promotions API

The Coupons and Promotions API handles discount logic including promotion rules, application methods, coupon codes, and campaign budget tracking.

Promotion Structure

{
  "id": "promo_abc123",
  "code": "SUMMER25",
  "type": "standard",
  "status": "active",
  "applicationMethod": {
    "type": "percentage",
    "value": 25,
    "allocation": "across",
    "maxQuantity": null,
    "buyRulesMinQuantity": null
  },
  "rules": [
    {
      "attribute": "subtotal",
      "operator": "gte",
      "values": ["5000"]
    }
  ],
  "campaign": {
    "id": "camp_summer",
    "name": "Summer Sale 2024",
    "budgetLimit": 100000,
    "budgetUsed": 34500
  },
  "startsAt": "2024-06-01T00:00:00Z",
  "endsAt": "2024-08-31T23:59:59Z",
  "usageLimit": 1000,
  "usageCount": 342,
  "createdAt": "2024-05-15T10:00:00Z"
}

Endpoints

List Promotions

GET /promotion

Query Parameters:

Parameter	Type	Description
`page`	number	Page number
`display`	number	Items per page
`sort`	string	Sort field
`status`	string	`active`, `draft`, `expired`, `disabled`
`type`	string	`standard`, `buyget`, `freeShipping`
`campaignId`	string	Filter by campaign

curl "https://api.hanzo.ai/promotion?status=active&display=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "count": 8,
  "models": [
    {
      "id": "promo_abc123",
      "code": "SUMMER25",
      "type": "standard",
      "status": "active",
      "usageCount": 342,
      "usageLimit": 1000
    }
  ]
}

Get Promotion

GET /promotion/:id

curl https://api.hanzo.ai/promotion/promo_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create Promotion

POST /promotion

curl -X POST https://api.hanzo.ai/promotion \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "type": "standard",
    "status": "active",
    "applicationMethod": {
      "type": "percentage",
      "value": 25,
      "allocation": "across"
    },
    "rules": [
      {
        "attribute": "subtotal",
        "operator": "gte",
        "values": ["5000"]
      }
    ],
    "startsAt": "2024-06-01T00:00:00Z",
    "endsAt": "2024-08-31T23:59:59Z",
    "usageLimit": 1000
  }'

Update Promotion

PUT /promotion/:id

curl -X PUT https://api.hanzo.ai/promotion/promo_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "disabled"
  }'

Delete Promotion

DELETE /promotion/:id

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

Application Methods

Application methods define how a discount is calculated.

Create Application Method

POST /applicationmethod

curl -X POST https://api.hanzo.ai/applicationmethod \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promotionId": "promo_abc123",
    "type": "fixed",
    "value": 1000,
    "allocation": "each",
    "maxQuantity": 3
  }'

Application Method Types:

Type	Description	Example
`percentage`	Percentage off	25% off
`fixed`	Fixed amount off	$10 off each item
`freeShipping`	Waives shipping cost	Free shipping

Allocation:

Value	Description
`across`	Spread across all eligible items
`each`	Apply to each eligible item individually

Promotion Rules

Rules determine when a promotion can be applied.

Create Promotion Rule

POST /promotionrule

curl -X POST https://api.hanzo.ai/promotionrule \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promotionId": "promo_abc123",
    "attribute": "product.collection",
    "operator": "in",
    "values": ["summer-collection", "clearance"]
  }'

Rule Attributes:

Attribute	Description
`subtotal`	Cart subtotal in cents
`itemCount`	Number of items in cart
`product.collection`	Product collection slug
`product.tag`	Product tags
`customer.tag`	Customer segment tags
`currency`	Cart currency code

Rule Operators:

Operator	Description
`eq`	Equals
`gte`	Greater than or equal
`lte`	Less than or equal
`in`	Value in list
`nin`	Value not in list

Evaluate Promotion

POST /promotion/evaluate

Test which promotions apply to a given cart without modifying it:

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

Response:

{
  "applicable": [
    {
      "id": "promo_abc123",
      "code": "SUMMER25",
      "discount": 1499,
      "description": "25% off orders over $50"
    }
  ],
  "automatic": [
    {
      "id": "promo_auto01",
      "discount": 500,
      "description": "Free shipping on orders over $75"
    }
  ]
}

Campaign Budgets

Campaigns group promotions and enforce a shared budget.

curl -X POST https://api.hanzo.ai/campaign \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale 2024",
    "budgetLimit": 100000,
    "startsAt": "2024-06-01T00:00:00Z",
    "endsAt": "2024-08-31T23:59:59Z"
  }'

When a campaign budget is exhausted, all promotions in that campaign are automatically paused.

SDK Examples

JavaScript

import { Commerce } from '@hanzo/commerce'

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

// Create promotion
const promo = await commerce.promotions.create({
  code: 'SUMMER25',
  type: 'standard',
  applicationMethod: { type: 'percentage', value: 25 },
  rules: [{ attribute: 'subtotal', operator: 'gte', values: ['5000'] }],
  startsAt: '2024-06-01T00:00:00Z',
  endsAt: '2024-08-31T23:59:59Z'
})

// Evaluate cart promotions
const result = await commerce.promotions.evaluate({ cartId: 'cart_abc123' })

Go

promo, err := client.Promotions.Create(ctx, &sdk.PromotionInput{
    Code:   "SUMMER25",
    Type:   "standard",
    Status: "active",
    ApplicationMethod: &sdk.ApplicationMethod{
        Type:  "percentage",
        Value: 25,
    },
    StartsAt: "2024-06-01T00:00:00Z",
    EndsAt:   "2024-08-31T23:59:59Z",
})

Coupons & Promotions API

On this page