Skip to content

Promotions and coupons

Install campaigns, eligibility rules, coupon codes, usage limits, and deterministic cart discounts.

@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:run

The configurator registers @adocommercekit/promotions/promotions_provider and publishes:

  • config/commerce_promotions.ts and app/validators/commerce_promotions.ts;
  • timestamped promotions and promotion-kinds migrations using core’s table prefix;
  • app/controllers/commerce/promotions_controller.ts and start/routes/commerce_promotions.ts;
  • admin management controllers and routes when app/services/commerce_admin.ts exists;
  • 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close