From a33188a79ef07acea0eb59d64495d1f30d33b9dc Mon Sep 17 00:00:00 2001 From: Prateek Srivastava Date: Fri, 10 Jul 2026 14:55:37 +0200 Subject: [PATCH 1/2] docs(discount): document usage-limit and stacking-conflict rejection codes The documented discount_code_* rejection codes have no entry for two common real-world cases: a code whose overall usage allowance has been exhausted, and a code that matched and was valid but lost to stacking or best-deal resolution against an already-active discount. Both currently have to be forced into discount_code_already_applied or discount_code_combination_disallowed, which mean something narrower and would mislead a buyer. Adds discount_code_usage_limit_reached and discount_code_stacking_conflict to the error-code table, with a short note distinguishing each from its nearest existing neighbor. --- docs/specification/discount.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/specification/discount.md b/docs/specification/discount.md index 4f6ffe27c..2f6c56114 100644 --- a/docs/specification/discount.md +++ b/docs/specification/discount.md @@ -178,9 +178,22 @@ via the `messages[]` array: | `discount_code_invalid` | Code not found or malformed | | `discount_code_already_applied` | Code is already applied | | `discount_code_combination_disallowed` | Cannot combine with another active discount | +| `discount_code_usage_limit_reached` | Code has reached its maximum number of allowed uses | +| `discount_code_stacking_conflict` | Code is valid, but a higher-priority discount already applied takes precedence | | `discount_code_user_not_logged_in` | Code requires authenticated user | | `discount_code_user_ineligible` | User does not meet eligibility criteria | +`discount_code_usage_limit_reached` differs from `discount_code_already_applied`: +the latter means the buyer is trying to apply a code that is already active on +*this* cart or checkout; the former means the code's overall usage allowance +(global or per-customer) has been exhausted by other carts/customers. + +`discount_code_stacking_conflict` differs from `discount_code_combination_disallowed`: +the latter means the business has an explicit rule that these specific +discounts cannot combine; the former means the code matched and was valid, +but discount-stacking or best-deal resolution rules resulted in a different, +already-active discount taking precedence instead. + ## Automatic Discounts Businesses may apply discounts automatically based on cart contents, customer From 5cc3bb1f5a287f5f4d97924e1433af6c840dac86 Mon Sep 17 00:00:00 2001 From: Prateek Srivastava Date: Tue, 14 Jul 2026 10:31:57 +0200 Subject: [PATCH 2/2] docs(discount): fix table column alignment markdownlint (MD060/table-column-style) flagged the two new rows added in the previous commit for not aligning with the rest of the table. Re-padded every row to a consistent column width. No content change. --- docs/specification/discount.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/specification/discount.md b/docs/specification/discount.md index 2f6c56114..4c1d6886b 100644 --- a/docs/specification/discount.md +++ b/docs/specification/discount.md @@ -172,16 +172,16 @@ via the `messages[]` array: **Error codes for rejected discounts:** -| Code | Description | -| -------------------------------------- | ------------------------------------------- | -| `discount_code_expired` | Code has expired | -| `discount_code_invalid` | Code not found or malformed | -| `discount_code_already_applied` | Code is already applied | -| `discount_code_combination_disallowed` | Cannot combine with another active discount | -| `discount_code_usage_limit_reached` | Code has reached its maximum number of allowed uses | +| Code | Description | +| -------------------------------------- | ------------------------------------------------------------------------------ | +| `discount_code_expired` | Code has expired | +| `discount_code_invalid` | Code not found or malformed | +| `discount_code_already_applied` | Code is already applied | +| `discount_code_combination_disallowed` | Cannot combine with another active discount | +| `discount_code_usage_limit_reached` | Code has reached its maximum number of allowed uses | | `discount_code_stacking_conflict` | Code is valid, but a higher-priority discount already applied takes precedence | -| `discount_code_user_not_logged_in` | Code requires authenticated user | -| `discount_code_user_ineligible` | User does not meet eligibility criteria | +| `discount_code_user_not_logged_in` | Code requires authenticated user | +| `discount_code_user_ineligible` | User does not meet eligibility criteria | `discount_code_usage_limit_reached` differs from `discount_code_already_applied`: the latter means the buyer is trying to apply a code that is already active on