Coupon and Promotion Codes

Apply discounts predictably instead of turning checkout into a loophole.

involved Monetization

What it adds

Redeemable codes with eligibility rules, redemption limits, expiry, defined stacking behaviour, and an accurate discounted total before purchase.

What your agent is told to do

1
Validate every code on the server at redemption time against plan, customer, region, currency and remaining redemptions. A code checked only when it was typed can be redeemed after it expires.
2
Decide and enforce one stacking policy: codes combine, or the best one wins, or only one applies. Ambiguity here is how a plan ends up free.
3
Normalise codes on entry — trim and case-fold — so that a code copied out of an email works.
4
Show the actual discounted amount, the discount duration, and what the price becomes afterwards, before the user confirms. A percentage with no end date is not a price.
5
Do NOT enumerate valid codes through the validation endpoint. Rate-limit redemption attempts and keep the failure message the same shape for invalid and ineligible codes.

Edge cases it handles

A first-time-customer code applied by a returning customer must be refused, including when they return under a second account with the same payment method.
Two concurrent redemptions of a single-use code must not both succeed. Claim the redemption atomically.
A percentage discount on one currency's plan is not the same as a fixed-amount discount converted between currencies. Refuse currency mismatches rather than converting.
A code applied to a subscription that later changes plan may no longer be eligible. Define whether it survives the change and apply that consistently.
Expiry means expiry of eligibility to redeem, not of the discount already granted. Keep those two clocks separate.
Discounts interact with tax and proration. The displayed total must come from the same source that produces the invoice, not a local subtraction.

Definition of done

Every code is validated server-side at the moment of redemption.
The stacking policy is defined in one place and cannot be bypassed by applying codes in a different order.
Codes are matched case-insensitively with surrounding whitespace ignored.
Single-use and limited-redemption codes cannot be over-redeemed under concurrent requests.
The discounted total, discount duration, and post-discount price are shown before purchase.
Invalid and ineligible codes produce indistinguishable responses and are rate-limited.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Usage Limits

Upgrade Modal

Billing Portal

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.