ResourcesPromotions
Overview
Create and manage scheduled, multi-phase storefront promotions through the API.
Promotions apply automatic checkout discounts without requiring a coupon code. Each promotion has an ordered set of phases. The first eligible phase in position order controls the active discount.
Endpoints
- List promotions
- Search promotions
- Create a promotion
- Retrieve a promotion
- Update a promotion
- Replace promotion phases
- Delete a promotion
- Restore a promotion
Promotion model
- Name
idinteger- Description
- The promotion ID.
- Name
namestring- Description
- The seller-facing promotion name.
- Name
statusactive | disabled- Description
- Whether the promotion can be selected.
- Name
starts_attimestamp | null- Description
- The optional promotion start time.
- Name
ends_attimestamp | null- Description
- The optional promotion end time.
- Name
priorityinteger- Description
- Lower values are evaluated first.
- Name
is_stackableboolean- Description
- Whether the promotion can be combined with a coupon.
- Name
max_redemptionsinteger | null- Description
- The optional completed-order cap across all phases.
- Name
phasesPromotionPhase[]- Description
- The active phases in evaluation order.
Promotion phase model
- Name
sort_orderinteger- Description
- The one-based evaluation position.
- Name
discount_typepercentage | fixed- Description
- How the discount value is interpreted.
- Name
discount_valuestring- Description
- A decimal percentage or fixed amount. Percentage values cannot exceed
100. - Name
ends_attimestamp | null- Description
- The optional time at which this phase stops applying.
- Name
max_redemptionsinteger | null- Description
- The optional completed-order cap for this phase.
- Name
minimum_amountstring | null- Description
- The optional minimum checkout subtotal.
Phase replacement preserves order history: referenced old phases remain soft-deleted, while unreferenced old phases are permanently purged.