Key concepts
Promotions
A promotion defines the discount rules and constraints:- Type: The kind of discount (percentage, fixed amount, BOGO, bundle, tiered, free shipping, gift with purchase)
- Scope: What the promotion applies to (all products, specific products, categories, collections, or departures)
- Value: The discount amount or percentage
- Validity period: When the promotion is active
- Usage limits: Maximum total uses or per-customer limits
Promotion codes
Codes are the actual strings customers enter to redeem a promotion:- Each promotion can have multiple codes
- Codes can have their own validity periods and usage limits
- Codes are automatically uppercased for case-insensitive matching
Scopes required
| Endpoint | Scope |
|---|---|
| List, get, validate | marketing:read |
| Create, update, delete, redeem | marketing:write |
Promotion types
| Type | Description |
|---|---|
percentage | Percentage discount off the order |
fixed_amount | Fixed monetary discount |
bogo | Buy one get one free |
bundle | Bundle discount |
tiered | Tiered pricing based on quantity |
free_shipping | Free shipping discount |
gift_with_purchase | Free gift with purchase |
Promotion scopes
| Scope | Description |
|---|---|
all_products | Applies to all products |
specific_products | Only applies to listed product IDs |
specific_categories | Only applies to listed category IDs |
specific_collections | Only applies to listed collection IDs |
specific_departures | Only applies to listed departure IDs |
Validation flow
When validating a promotion code:- Code lookup: Find the code and check it’s active
- Code validity: Check date range and usage limits
- Promotion status: Verify parent promotion is active
- Promotion validity: Check promotion date range and total usage
- Order constraints: Verify minimum order value, currency, product eligibility
- Customer limits: Check per-customer usage if customer ID provided
- Calculate discount: Return the applicable discount amount