@adocommercekit/promotions is an optional package for promotion campaigns, eligibility rules,
coupon codes, transactional usage claims, per-campaign and per-customer limits, deterministic
stacking, and line-level cart discount adjustments.
Install and configure
Configure core first, using the same exact lockstep version for every commerce package:
pnpm add @adocommercekit/promotions
node ace configure @adocommercekit/promotions
node ace migration:runThe configurator registers @adocommercekit/promotions/promotions_provider and publishes:
config/commerce_promotions.tsandapp/validators/commerce_promotions.ts;- timestamped promotions and promotion-kinds migrations using core’s table prefix;
app/controllers/commerce/promotions_controller.tsandstart/routes/commerce_promotions.ts;- admin management controllers and routes when
app/services/commerce_admin.tsexists; - panel pages, navigation, translations, controllers, validators, and routes when the admin panel is configured;
- publication baselines under
.commercekit/publications.
Configure @adocommercekit/storefront-api before using the published coupon HTTP surface.
Configure the optional admin API or panel first, then reconfigure promotions to add those
surfaces. Host-modified panel files are left untouched and reported.
The provider registers the cart and shipping promotion processors, releases order redemptions on
OrderCanceled, and registers commerce:promotions:expire-pending with core’s job dispatcher on
a */5 * * * * schedule.
Campaigns, rules, and coupon feedback
Campaigns support percentage, fixed, free_shipping, and cheapest_free. All values are
positive: percentage uses integer basis points up to 10000 (100%); fixed values are minor-unit amounts and require currency;
free_shipping still requires a positive value (use 1); cheapest_free uses its value as
the qualifying group quantity (2 means buy one, get one cheapest unit free).
Rules support:
| Rule | Configuration |
|---|---|
minimum_subtotal |
Integer-string amount and currency |
minimum_quantity |
Positive integer quantity across cart lines |
product |
Nonempty productIds |
category |
Nonempty categorySlugs |
customer_group |
Nonempty groupIds |
matchType: 'all' intersects qualifying lines; 'any' unions them. Priority and stacking
control deterministic application. UpdateCampaignInput permits null to clear startsAt,
endsAt, usageLimit, and perCustomerLimit; omission preserves their values.
PromotionService and PromotionCartProcessor accept an injected clock for deterministic windows.
applyCoupon() throws PromotionNotApplicableException for inactive, expired, exhausted,
or ineligible codes, with details.code and details.reason. Guests cannot use campaigns
or codes with a per-customer limit. Cart recalculation exposes processor feedback through
cart.$extras.promotions; transformers can fall back to metadata.promotionFeedback.
Each feedback entry contains code, status (applied, ineligible, exhausted, or
expired), and optional reason (inactive, expired, exhausted, or ineligible).
Redemption lifecycle
listCodes(campaignId) lists codes; revocation releases pending claims.
releaseOrder(orderId, options?) releases pending or redeemed order claims, including cancellation.
expirePendingRedemptions(options?) releases expired pending claims; the scheduled
commerce:promotions:expire-pending job calls it every five minutes.
Storefront routes
The published coupon routes mount under /api/commerce:
| Method | Path | Purpose |
|---|---|---|
POST |
/cart/coupons |
Apply a coupon code to the current cart |
DELETE |
/cart/coupons/:code |
Remove a coupon code and recalculate the cart |
See the storefront REST reference for route names and rate limits.
Admin routes and abilities
Under /api/commerce/admin, management provides GET/POST /promotions,
GET/PATCH /promotions/:id, POST /promotions/:id/end,
GET/POST /promotions/:id/rules, DELETE /promotions/:id/rules/:ruleId,
GET/POST /promotions/:id/codes, and POST /promotion-codes/:codeId/revoke.
Reads require commerce.promotions.view; mutations require commerce.promotions.manage.
The optional panel lives at /admin/commerce/promotions. Map these host abilities before access;
see admin abilities.
Public entrypoints
| Import | Contents |
|---|---|
@adocommercekit/promotions |
Config helper, models, service/processors, promotion policy, and types |
@adocommercekit/promotions/models |
Campaign, rule, code, and redemption models |
@adocommercekit/promotions/services |
PromotionService, cart/shipping processors, and service types |
@adocommercekit/promotions/configure |
Adonis configure hook |
@adocommercekit/promotions/promotions_provider |
Adonis service provider |
@adocommercekit/promotions/upgrade |
Manifest and publication artifact loader for upgrades |
Upgrade published files
Existing hosts must publish and run the additive promotion_kinds migration before using the
newer kinds. Run node ace commerce:upgrade, review the plan, then node ace migration:run;
see operations.