Promotions & Discounts

This guide covers setting up promotions in Hanzo Commerce, including percentage and fixed discounts, conditional rules, campaign budgets, and checkout integration.

Overview

The promotions system has three components:

Promotion: The discount definition with a code or automatic trigger

Application Method: How the discount is calculated (percentage, fixed, free shipping)

Rules: Conditions that must be met for the promotion to apply

Creating a Basic Promotion

Create a 20% off coupon code:

curl -X POST https://api.hanzo.ai/promotion \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME20",
    "type": "standard",
    "status": "active",
    "applicationMethod": {
      "type": "percentage",
      "value": 20,
      "allocation": "across"
    },
    "usageLimit": 500,
    "startsAt": "2024-01-01T00:00:00Z",
    "endsAt": "2024-12-31T23:59:59Z"
  }'

const promo = await commerce.promotions.create({
  code: 'WELCOME20',
  type: 'standard',
  status: 'active',
  applicationMethod: {
    type: 'percentage',
    value: 20,
    allocation: 'across'
  },
  usageLimit: 500,
  startsAt: '2024-01-01T00:00:00Z',
  endsAt: '2024-12-31T23:59:59Z'
})

Discount Types

Percentage Off

{
  "applicationMethod": {
    "type": "percentage",
    "value": 25,
    "allocation": "across"
  }
}

Fixed Amount Off

{
  "applicationMethod": {
    "type": "fixed",
    "value": 1000,
    "allocation": "across"
  }
}

value is in cents. 1000 = $10.00 off.

Free Shipping

{
  "applicationMethod": {
    "type": "freeShipping"
  }
}

Buy X Get Y

{
  "type": "buyget",
  "applicationMethod": {
    "type": "percentage",
    "value": 100,
    "allocation": "each",
    "buyRulesMinQuantity": 2,
    "maxQuantity": 1
  }
}

This creates a "Buy 2 Get 1 Free" promotion.

Configuring Rules

Rules control when a promotion applies. Add rules to restrict by cart value, product, or customer segment.

Minimum Order Value

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

Specific Collections

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-sale", "clearance"]
  }'

VIP Customers Only

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

Campaign Management

Group promotions under a campaign with 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": 500000,
    "startsAt": "2024-06-01T00:00:00Z",
    "endsAt": "2024-08-31T23:59:59Z"
  }'

const campaign = await commerce.promotions.createCampaign({
  name: 'Summer Sale 2024',
  budgetLimit: 500000,
  startsAt: '2024-06-01T00:00:00Z',
  endsAt: '2024-08-31T23:59:59Z'
})

Then assign promotions to the campaign:

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

When a campaign's budget is exhausted, all promotions in that campaign are automatically paused. Monitor budget usage via the campaign's budgetUsed field.

Integration with Checkout

Apply a Coupon to Cart

curl -X POST https://api.hanzo.ai/cart/cart_abc123/coupon \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME20"
  }'

await commerce.carts.applyCoupon('cart_abc123', 'WELCOME20')

Evaluate Promotions

Check which promotions apply to a 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": "WELCOME20",
      "discount": 1200,
      "description": "20% off your order"
    }
  ],
  "automatic": [
    {
      "id": "promo_freeship",
      "discount": 599,
      "description": "Free shipping on orders over $50"
    }
  ]
}

Remove a Coupon

curl -X DELETE https://api.hanzo.ai/cart/cart_abc123/coupon \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Automatic Promotions

Promotions without a code field are applied automatically when conditions are met:

curl -X POST https://api.hanzo.ai/promotion \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "status": "active",
    "applicationMethod": {
      "type": "freeShipping"
    },
    "rules": [
      {
        "attribute": "subtotal",
        "operator": "gte",
        "values": ["7500"]
      }
    ]
  }'

This gives free shipping on all orders over $75 with no coupon code needed.

Promotions & Discounts

On this page