Overview
The Promotion Service is the platform’s pricing-and-offers brain. It lets merchandising teams author promotions (percent-off, amount-off, BOGO, free shipping, bundles, gift-with-purchase, trade-in, and more), organise them into stacking/exclusivity groups, target them with promo codes, wallets and condition-based lists, then evaluate them against a shopping cart to compute the final discounted total. Rule eligibility is expressed as decision-graph rules and executed in-memory by an orchestrator that also enforces priority, stacking, group caps and tenant-level discount caps.
The service is multi-tenant: nearly every request is scoped by an instanceId query parameter, and each tenant (instance) carries its own configuration properties (locale, currency, workflow enablement, discount caps, plugin config).
Business Value
| Capability | Business outcome |
|---|---|
| Author 14 promotion action types (percent/amount off, BOGO, bundles, free shipping, gift, trade-in, personalization, summed-up/tiered) | Marketing can model virtually any offer without code changes |
Cart-time evaluation (/preview, /evaluate) |
Storefront and checkout show accurate, consistent discounts |
| Groups with priority / stacking / exclusivity strategies | Controlled stacking prevents over-discounting and margin leakage |
| Promo codes (generation, validation, redemption, block/reserve, assign, reverse) | Coupon campaigns, single-use codes, per-customer caps |
| Promo wallet | Targeted, customer-specific offers (“in your wallet”) |
| Promotion lists (SKU/customer/category value sets) | Reusable condition sets shared across many promotions |
| Config-driven approval workflow + versioning + rollback | Governance, audit trail, safe rollout of live offers |
Tenant-level discount caps (maxDiscountPerCart, maxStackingPerCart) |
System-wide guardrails on total discount exposure |
Live/cached storefront feeds (/promotions/live, /promotion-groups/live) |
Fast, read-optimised merchandising surfaces |
Who Uses It
| Persona | Interaction |
|---|---|
| Merchandiser / Promotions admin | Creates/updates promotions, groups, lists, displays, promocode lists via admin APIs (require isAdmin) |
| Storefront / cart service | Calls /promotions/preview (display) and /promotions/live for cart-page rendering |
| Checkout / OMS service | Calls /promotions/evaluate (commit mode) and promocode block/redeem/reverse |
| Approver | Drives the workflow (/v1/workflows) approve/deny transitions |
| Platform / DevOps | Configures instances, env vars, EventBridge bus, MongoDB, Redis |
| Marketplace apps | Receive projections and lifecycle events via the marketplace integration plugin |
Core Features
| # | Feature | Notes |
|---|---|---|
| 1 | Promotion CRUD + lifecycle | Create (single/bulk up to 100), get, patch, delete (draft hard-delete vs archive), duplicate |
| 2 | Cart evaluation | /preview (display, non-mutating) and /evaluate (apply, commits promo codes) |
| 3 | Promotion groups | Priority / first_match / best_discount strategies; mutually_exclusive / stackable / organizational types; caps |
| 4 | Promo codes | 7 canonical code types, generation, validate, redeem (atomic), block/unblock (reserve), assign/unassign, reverse, CSV export, bulk-assign, usage count |
| 5 | Promo wallet | Grant / revoke / view / visible entries per customer |
| 6 | Promotion lists | Condition-based value sets (SKUs, customers, categories); items add/remove; resolved into eval lists context |
| 7 | Promotion displays | Curated storefront display surfaces with items |
| 8 | Rule engine | Decision-graph eligibility + per-action conditions; in-memory orchestrator |
| 9 | Stacking / caps | Cross-promo conflict resolution, group caps, tenant maxDiscountPerCart/maxStackingPerCart |
| 10 | Multi-tenant instances | Per-tenant properties (locale, currency, workflow entities, caps, plugin config) |
| 11 | Events | Publishes domain events to EventBridge; consumes marketplace app.* events |
| 12 | Change stream | Optional MongoDB change stream keeps the in-memory orchestrator in sync |
| 13 | Marketplace integration | App projections/selections + EventBridge lifecycle handling (gated) |
| 14 | In-memory mode | PROMO_USE_INMEMORY=true replaces Mongo/Redis/EventBridge/JWT with local stubs |
Related Resources
- Batch jobs — promo-code generate/upload/download, promotion-list upload/download/delete.
- EventBridge rule templates for event routing.
- Sibling services: OMS Service, Cart Service, User Service (instance lookup), Marketplace Service.
Revision History
2026-08-04 | JP – Created the page and added the content.