Coupons and discounts
DEFINITION
A coupon is a code that applies a discount to a customer's charges, either a fixed amount off, a percentage off, or a free trial period. Recurly models each coupon with an explicit discount type, redemption scope, and duration, so a merchant can see exactly what a discount does and how long it lasts.
RELATED TERMS
A coupon is a code that applies a discount to a customer's charges, either as a fixed amount off, a percentage off, or a free trial period. Discounts are the mechanism a subscription business uses to reduce what a customer pays, whether for acquisition, retention, or account-specific arrangements.
A coupon's discount has one of three types. A fixed discount subtracts a set amount, defined per currency, so the amount applied to a transaction is whichever value was configured for that transaction's currency. A percent discount subtracts a set percentage of the charge. A free trial discount waives charges for a defined length of time, measured in days, weeks, months, or billing periods.
Coupons also differ in scope and distribution. The redemption_resource setting controls whether a discount applies to all eligible charges on an account or only to a specific subscription. The coupon_type setting controls distribution: a single code coupon is one shared code, while a bulk coupon generates a batch of unique codes from a template, useful for one-per-customer promotions.
A coupon's redemption window and duration are tracked separately. The redeem_by setting fixes the date a coupon stops being redeemable at all. Once redeemed, remaining_duration describes how long the discount itself lasts on that account or subscription: forever, a single use, for a defined time period such as days, weeks, or months, or for a set number of billing periods.
Why it matters
Coupons and discounts directly affect recognized revenue, so how they are typed, scoped, and time-boxed has to be precise, not just for the customer experience but for accurate invoicing and reporting. A discount meant for one subscription but scoped to the whole account, or a free trial measured in the wrong unit, changes what a customer is actually charged. Because Recurly models coupons with explicit discount types (fixed, percent, free_trial), explicit redemption scope (account or subscription), and explicit duration types (forever, single_use, temporal, billing_periods), a merchant can see exactly what a discount does and how long it lasts without inferring it from raw invoice math.
Coupon state also matters operationally. A coupon can be redeemable, expired, or maxed_out, and knowing which state it is in explains why a customer's code did or did not apply, a common source of support inquiries. Recurly exposes that state directly, so support and billing teams have a clear answer when a code does not work.
How to use
Choose the discount type for the coupon: fixed, percent, or free_trial, based on the offer being made.
Set redemption_resource to account or subscription, depending on whether the discount should apply broadly or to one specific subscription.
Choose coupon_type: single_code for one shared promotional code, or bulk with a unique_code_template when each customer needs a distinct code.
Set redeem_by, or for bulk coupons a relative redemption window using redeem_by_interval_unit and redeem_by_interval_amount, to control how long the coupon can be redeemed.
Set the customer-facing hosted_page_description and the invoice_description so the discount is clearly labeled wherever the customer sees it.
After redemption, check remaining_duration and coupon.state to see how long the discount will continue to apply and whether the coupon is still active.
Benefits and examples
A 20% percent-type coupon applied at redemption reduces every eligible charge by that percentage until its remaining_duration runs out.
A fixed $10 discount coupon, scoped with redemption_resource set to subscription, reduces only that one subscription's charges rather than everything on the account.
A free_trial coupon with unit set to month and length set to 1 waives the first month of charges for a new subscriber.
A bulk coupon with a unique code template distributes a one-per-customer welcome offer at scale, with each code independently trackable through the /generate endpoint, rather than relying on a single shared code for a mass promotion.
Frequently asked questions
What is the difference between a coupon and a discount? A coupon is the code or mechanism a customer redeems. A discount is what that coupon actually applies, such as a fixed amount off, a percentage off, or a free trial period.
Can a coupon apply to only one subscription instead of an entire account? Yes. The redemption_resource setting on a coupon determines whether it applies to all eligible charges on the account or is scoped to a specific subscription.
What happens when a coupon reaches its redemption limit? The coupon's state changes to maxed_out, and it can no longer be redeemed. That is distinct from a coupon that is expired because its redemption window has passed.
Can multiple coupons be applied to the same subscription? Yes, if Multiple Coupons Per Account is enabled on the site. When enabled, Recurly applies every eligible coupon redemption to each qualifying invoice, following the discount-order and stacking rules configured for the site. Without it enabled, only one coupon redemption is allowed per account at a time.
