FAQs

Q1. What’s the difference between /preview and /evaluate?

/preview (PROCESS_MODE_DISPLAY) runs identical discount math but never commits a promo-code redemption — used for cart-page rendering. /evaluate (PROCESS_MODE_APPLY) also commits every participating promo code; partial failures surface in failedCommits[].

Q2. How is a promotion’s eligibility rule expressed?

As a decision graph stored in the promotion’s conditions, compiled by the rule engine. Per-action condition graphs are also supported. Invalid rules raise EQ-PROMO-4220003.

Q3. How does the service control over-discounting / stacking?

Through group strategies (priority/first_match/best_discount), group caps (maxAppliedPerCart, maxDiscountPerCart), promotion stackingMode/combinesWith, stop conditions, and tenant-level maxDiscountPerCart/maxStackingPerCart caps applied last.

Q4. What are the promo-code types?

Seven canonical types: DEFAULT_TYPE, SINGLE_USER_SINGLE_USE, SINGLE_USER_NTIME_USE, MULTI_USER_MULTI_USE, MULTI_USER_MULTI_USE_MTIME_OFFER, MULTI_USER_NTIME_USE_PER_USER, SINGLE_USER_NTIME_USE_PER_XDAYS (some read typeConfig.N/M/X).

Q5. How do I run locally without AWS/Mongo?

Set PROMO_USE_INMEMORY=true — Mongo, Redis, EventBridge and JWT are replaced with in-memory stubs and all routes become unauthenticated.

Q6. Where does the tenant context come from?

Every request should carry ?instanceId=.... The service attaches an instance context; with INSTANCE_SERVICE_URL set it enriches from the User Service (cached).

Q7. Are events guaranteed to be delivered?

No. Event publishing is fire-and-forget; if the EventBridge integration fails to register it becomes a no-op and events are dropped (logged as a warning). In-memory mode captures them locally only.

Q8. What happens when I delete a promotion?

Draft promotions never activated are hard-deleted; others are archived. Active promotions cannot be deleted (EQ-PROMO-4090010) — pause or archive first.

Q9. How does versioning/rollback work?

Write operations snapshot entities into *_versions collections. GET /v1/versions/:id lists snapshots and POST /v1/versions/:id/rollback restores a chosen version.

Q10. Which entities support the approval workflow?

Only entity types listed in the instance’s enabledWorkflowEntities property (e.g. PROMOTION,PROMOTION_GROUP). Others raise WORKFLOW_ENTITY_NOT_ENABLED.

Revision History
2026-08-05 | JP – Created the page and added the content.