Using rejectedPromotions to Debug

Every Verify response includes a rejectedPromotions object listing promotions that were considered but not applied, each with a rejectionReason. This is the most direct tool for diagnosing why a promotion isn't firing.

How to find it

In the Verify response body, look for the rejectedPromotions object. Each entry is keyed by promotion ID and includes at minimum:

• promotionId — the promotion that was rejected
• versionId — the version evaluated
• rejectionReason — why it was rejected

Some reasons include additional context fields (see below).

Rejection reasons and what they mean

PromotionUsageExceeded

The promotion's total usage limit (Max Use Count) has been reached across all customers. The response also includes usageCountLimit showing the configured limit. To continue offering the promotion, increase the limit in the Dashboard.

PromotionPerCustomerUsageExceeded

This specific customer (identified by email) has already used the promotion the maximum number of times. The response includes usageCountLimit. This customer cannot use this promotion again unless the limit is raised or the usage records are cleared via Unrecord.

Stopped

An earlier promotion in the evaluation order had an After Processing Action of STOP, which halted evaluation of subsequent Item Group and Whole Cart promotions. Identify which promotion triggered the stop and review whether that is intentional.

Exclusivity

An earlier promotion with an After Processing Action of EXCLUSIVE ran first, blocking this promotion. Exclusive promotions are also sorted to the front of the evaluation order. Review whether the exclusive promotion is intended to block this one.

AppliedPromotionsLimitReached

The project-level limit on the number of promotions that can apply to a single cart has been reached. The response includes appliedPromotionsLimit. This is a project configuration limit, not a promotion configuration limit.

NoApplicableCartItems

The promotion's action ran but found no eligible items in the cart. For Item Group promotions, this typically means the cart doesn't contain items matching the action group conditions. Check the item group configuration and compare it against the items in the cart.

What is NOT in rejectedPromotions

Promotions that fail the earliest evaluation checks are silently omitted from rejectedPromotions rather than listed. This includes:

• Currency mismatch — the cart currency doesn't match the promotion's configured currencies
• Trigger conditions not met — the cart didn't satisfy the configured trigger conditions
• Coupon not provided or invalid — a required coupon was missing, unrecognised, or exceeded its usage limit

If the promotion you're debugging does not appear in rejectedPromotions at all, it was almost certainly silently skipped for one of these reasons. Check the promotion's currency settings, trigger conditions, and coupon configuration directly in the Dashboard.

For coupon-specific debugging, also check the couponMatchResults object in the same Verify response — it shows per-code validation results including invalidReason.

Going deeper

For a full explanation of the evaluation steps and the order in which checks run, see the Promotion Evaluation Process. Understanding the evaluation order helps you predict which rejection reason to expect and where in the sequence the promotion is being blocked.