Promotions

The promotions engine lets you create targeted offers with conditions, discounts, and coupon codes.

Promotion Types

Type	Description
Discount	Percentage or fixed amount off
Points Multiplier	Earn extra points on qualifying actions
Free Item	Award a free product from the catalog
Coupon	Redeemable codes with usage limits

Conditions

Promotions support rich condition logic:

Customer segments — Target by metadata, tier, or history
Time-based — Start/end dates, day-of-week, time ranges
Purchase-based — Minimum spend, specific products, categories
Usage limits — Per-customer limits, global redemption caps

Creating a Promotion

curl -X POST https://api.storelayer.io/v1/promotions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale 2x Points",
    "type": "points_multiplier",
    "multiplier": 2,
    "conditions": {
      "startDate": "2025-06-01",
      "endDate": "2025-08-31",
      "minSpend": 2000
    },
    "maxRedemptions": 1000
  }'

Coupon Codes

Generate and manage coupon codes attached to promotions:

curl -X POST https://api.storelayer.io/v1/promotions/{promotionId}/coupons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER2025",
    "maxUses": 500,
    "maxUsesPerCustomer": 1
  }'