Coupon Code Redemption Flow

1. User enters code

The checkout page exposes a single text input below the plan selector. On submit, the frontend POSTs /api/coupons/validate with the raw code and the selected plan SKU. No client-side validation beyond length > 0 — all logic lives server-side.

2. Server-side validation

• Lookup coupon in Upstash KV by key coupon:CODE.
• Reject if missing, expired, or usage count exhausted.
• Check plan_allowlist — if set, the selected SKU must match.
• Compute discount: percentage (e.g. 20% off) or fixed amount in USD cents.
• Return { valid, discount_amount, discount_type, final_total }.

3. Frontend updates pricing

On a valid response, the UI swaps the displayed total, shows a green “Coupon applied” badge, and stores the code in local component state. The original price is shown with a strikethrough. Invalid codes surface an inline error without clearing the input.

4. Checkout with SellAuth

When the user clicks purchase, the frontend calls /api/checkout with plan, coupon code, and any custom fields. The server creates a SellAuth invoice with the discounted total and attaches the coupon code as metadata. After payment, the webhook handler decrements the coupon usage counter in KV and provisions the license via KeyAuth.

5. Edge cases

• Race conditions: usage counter is decremented atomically via KV INCR; if max uses is reached mid-checkout, the webhook still honors the coupon (post-payment grace).
• Stacking: Meridian enforces one coupon per invoice. Attempting a second code returns HTTP 409.
• Zero-total: if a 100% coupon is issued, SellAuth creates a $0 invoice and the license is provisioned immediately without a payment confirmation delay.