Open API coupon validation

🔍 Problem Statement

As a Crain integration engineer, I receive generic, inconsistently-placed coupon validation errors, which results in unreliable checkout error handling and support triage.

💡 User Story

1. As a Crain integration engineer, I want a stable, enumerated failure_reason_code on every coupon validation failure, so that I can map errors to subscriber-facing messaging and support tooling.

2. As a Crain integration engineer, I want a published reason-code dictionary with sample error payloads for each code, so that I can implement checkout error handling confidently.

🎯 Definition of Done (DoD)

✔ Given a coupon validation failure on subscription creation or a campaign-attached coupon or on order preview, when the API returns coupon.valid: false, then the response includes a failure_reason_code and failure_reason_detail at a fixed location.

✔ Given a coupon validation failure, when the API responds, then it returns one documented HTTP status for that failure type.

✔ Given a subscriber's plan changes via the Open API Change Subscription endpoint, when sticky coupon re-validation runs, then plan-eligibility failures return a distinct code from expired or unknown-coupon failures.

✔ Given the feature ships, when Crain references the documentation, then a published failure_reason_code dictionary with sample error payloads per code is available.

✔ This change will impact the Open API, specifically the Create Subscription, Change Subscription, and Get Campaign endpoints.

✔ This solution will include the following limitations: subscriber-facing copy mapping and abuse/enumeration messaging remain Crain's responsibility; existing failure reason codes must not be collapsed or removed.

✔ This change will impact API, specifically POST /api/v1/sdk/order, POST /api/v1/sdk/subscription, and GET /api/v1/sdk/campaign (coupon.valid: false).

Feedback:

Pelcro today returns a generic invalid result for coupon validation across many distinct business rules (expired, wrong plan, segment, redemption limits, etc.), with inconsistent HTTP statuses and free-text messages whose location varies by case. To support our checkout flow, we need a stable, enumerated failure_reason_code on every coupon validation failure — order preview, subscription commit, and campaign-attached coupons (coupon.valid: false) — returned with one documented HTTP status at a fixed body location, identifying the coupon as the failing input, plus structured failure_reason_detail for support and ops. We will map codes to subscriber-facing copy and will manage any abuse/enumeration messaging on its side — please do not collapse distinct failure reasons in the API. Please provide a published reason-code dictionary, sample error payloads for each code, and confirmation that sticky re-validation on plan change returns plan-eligibility failures distinctly from expired/unknown codes.

Attached is a more complete requirements document. Please review.