Coupons and discounts give you flexible tools to reduce prices for subscribers — automatically applied by you or redeemed via a code at checkout. Use them to run promotions, reward loyalty, and drive new signups across any plan or billing cycle.

Available on all Recurly plans

1Definition 2Key benefits 3Creating a coupon 4Types of discounts 5Discount duration 6Applying a coupon 7Editing and removing coupons 8Expiration and restoration 9Reporting and analysis 10FAQs

Definition

Discounts are price reductions you apply automatically to a product or service — no action required from the subscriber. Coupons are codes subscribers enter at checkout to receive a price reduction. Both tools use the same underlying configuration in Recurly, and throughout this page "apply the discount" refers to both scenarios.

Key benefits

Drive conversions and revenue Run targeted promotions that attract new subscribers and convert trial users into paying customers.

Reward loyal customers Offer exclusive discounts to your most valuable subscribers to build long-term loyalty and reduce churn.

Strategic flexibility and insights Tailor promotions to specific plans, items, or billing cycles — then analyze redemption data to refine your strategy.

Prerequisites You'll need at least one subscription plan configured in your Recurly site. To allow coupon redemption on hosted payment pages, enable coupons in your Checkout or Hosted Page Settings.

Limitations Once a coupon is created, the following attributes cannot be edited: coupon code, discount type, duration, eligible plans, eligible items, and discount level. Additionally: free trial coupons cannot be applied to an existing account (only at subscription creation); coupons cannot be applied alongside "On next renewal" subscription changes; a fixed amount discount that exceeds eligible charges does not carry over to future invoices; percentage discounts never apply to plan setup fees; and coupons cannot retroactively discount an existing invoice.

Creating a coupon

Coupon fields

Before building a coupon, here's what each field in the creation form does.

Field	Description
Internal name	Identifies the coupon campaign internally. Not shown to subscribers unless exposed via API or email. Use a descriptive name for easy reference.
Code type	Single code — one code reusable multiple times based on redemption settings. Bulk unique codes — a set of one-time-use codes generated in bulk, ideal for personalized offers. See bulk unique codes for details.
Coupon code	Supports alphanumeric characters, dashes (-), underscores (_), and plus signs (+). A code can be reused only after the previous coupon using it has expired or reached its redemption limit.
Type of discount	Fixed amount, percentage, or free trial. Fixed amount coupons support multi-currency — specify a different amount for each currency you accept.
Duration	How long the discount applies after redemption: forever, single use, or limited time (days, weeks, or months).
Maximum redemptions	Total number of times the coupon can be redeemed across all accounts. Leave unlimited or set a cap.
Redemptions per account	How many times a single account can redeem the coupon — once, unlimited, or a specific number.
Redeem by date	Optional expiration date. After this date the coupon can no longer be redeemed.
Eligible charges	Which charge types the coupon can discount: recurring charges (plan fees, add-ons, setup fees), one-time charges only, or both.
Eligible plans	Which subscription plans qualify for the discount. Defaults to all plans but can be restricted to specific ones.
Eligible items	Which catalog items qualify for the discount. Defaults to all items but can be restricted to specific ones.
Discount level	Account level — applies across all eligible subscriptions on the account. Subscription level — tied to a specific subscription only.
Payment page description	Shown to subscribers when they redeem the coupon on your checkout page, hosted payment page, or via API. Up to 255 characters.
Invoice description	Appears in the "Discounts applied" section on the invoice. Not applicable to free trial coupons, which don't provide a monetary discount.

Step-by-step: create a new coupon

Navigate to Coupons

Go to Configuration and click Coupons.

Click New Coupon

Enter an internal name

Select a code type

Choose Single code or Bulk unique codes.

Choose a discount type

Select Percentage, Fixed amount, or Free trial.

Set the coupon duration

Choose Single use, Forever, or Limited time (specify days, weeks, or months).

Configure redemption rules

Set maximum redemptions, redemptions per account, and an optional redeem-by date.

Define eligible charges, plans, and items

Add descriptions (optional)

Optionally enter a payment page description and/or invoice description.

Click Create coupon

The discount will automatically appear on the invoice when it's generated.

Types of discounts

Percentage discounts

A percentage discount applies the same rate to each eligible charge on the invoice. Percentage discounts never apply to plan setup fees.

Example: A 10% discount on a plan with a $50 setup fee, $15 plan fee, and $7 add-on:

Charge	Amount	Discounted?	Discount applied
Setup fee	$50.00	No	—
Plan fee	$15.00	Yes	($1.50)
Add-on	$7.00	Yes	($0.70)
Total discount			($2.20) — payable: $69.80

Fixed amount discounts

A fixed amount discount is distributed across eligible charges starting with the first subscription line item — typically the setup fee. If the discount exceeds total eligible charges, the remaining balance is not returned or carried to future invoices.

One-time charges appear on the invoice before subscription charges but are discounted after them. If the fixed amount discount is less than total subscription charges, one-time charges won't receive any discount.

To target only a setup fee: create a single-use coupon with a fixed amount equal to or less than the setup fee — it will apply there before reaching other charges.

Example: A $20 discount on a plan with a $15 plan fee and $7 add-on:

Charge	Amount	Discount applied
Plan fee	$15.00	($15.00) — fully discounted
Add-on	$7.00	($5.00) — remaining $5 of discount applied
Total discount		($20.00) — payable: $2.00

Free trial coupons

Free trial coupons let you offer a custom trial length that differs from your plan's standard trial period. The trial starts on the day the subscription is created. Because free trial coupons don't provide a monetary discount, they don't appear on any invoices.

Discount duration

Duration	Behavior
Forever	The discount applies indefinitely for as long as the subscription is active.
Single use	The discount applies to one invoice only.
Limited time	The discount applies for a defined period — a specified number of days, weeks, months, or years. All invoices generated within that period receive the discount. Recurly recommends matching the period to the billing cycle of the eligible plans. Note: limited-time coupons expire automatically one hour before the anniversary of their redemption date.

Applying a coupon

During a purchase

Subscribers can enter a coupon code at checkout via your hosted payment page, your own checkout page using Recurly.js or the API, or the Recurly UI when adding a subscription to an existing account.

The purchase must include charges eligible for the discount — a coupon for Plan B won't apply during signup for Plan A.
If the subscription creation fails due to a declined transaction, the coupon won't be applied.
If only one active coupon is allowed per account, a new coupon replaces any existing one.
If multiple active coupons are allowed, the new code is added and applied after existing discounts.
Subscription-level coupons redeemed at subscription creation are automatically tied to that subscription.
Account-level coupons apply to the new subscription and any future subscriptions on the account.

To pre-populate a coupon code on your hosted payment page, append this URL parameter: ?subscription[coupon_code]=10off

Note Coupons cannot currently be applied to existing accounts through hosted account management pages. To request this capability, submit a support ticket.

During an upgrade or downgrade

You can apply a coupon when upgrading or downgrading a subscription so the discount applies to the updated invoice. Keep in mind:

The eligible charges must include the new plan.
Coupons cannot be applied with "On next renewal" changes.
A plan, quantity, or price change must be part of the update — the coupon cannot be the only change.

Directly on an account

To discount the next invoice for an existing subscription or a one-time charge, apply the coupon directly to the account via Manage Coupons on the account page in the Recurly UI, or via the API.

Editing and removing coupons

Editing an existing coupon

Go to Configuration > Coupons, select the coupon, and click Edit. The following fields can be modified after a coupon is created:

Internal name
Maximum redemptions
Redeem by date
Redemptions per account
Payment page description
Invoice description (not applicable to free trial coupons)

Note Changes only affect coupons redeemed after the update is saved. Existing redemptions are not impacted.

Removing a coupon from an account

Go to Coupon Redemptions

Navigate to the Coupon Redemptions page for the subscriber's account.

Locate the coupon

In the "Redeemed on account" table, find the coupon you want to remove.

Remove and confirm

Select the coupon and follow the prompts. Removing a coupon stops the discount from applying to future invoices — already-issued invoices are unaffected and the subscriber will be charged the regular price on their next billing cycle.

Expiration and restoration

Expiring a coupon early

Go to the coupon's overview page and select Expire early. The coupon expires immediately. Subscribers who have already redeemed it are not affected.

Automatic expiration

Coupons expire automatically when they reach their redeem-by date or maximum redemptions limit.

Reusing a coupon code

Once a coupon expires or reaches its redemption limit, the code becomes available to reuse when creating a new coupon.

Restoring an expired coupon

You can restore an expired coupon to make it redeemable again. If it expired due to reaching its redemption limit or redeem-by date, update those fields before restoring.

Reporting and analysis

Track and analyze coupon performance from the Exports page under Reports.

Export	What it shows
Coupons	All coupons on your site, their rules, and creation or expiration dates.
Coupon Redemptions	Who redeemed coupons, when, and how much discount was applied.
Invoices – Summary	Which coupons were applied to each invoice (see the `coupon_code` column).
Invoices – Line Items	Which coupons were applied to each line item and the total discount.
Invoices – Line Items – Coupons	Specific discounts per coupon per line item. Only visible when Multiple Coupons Per Account is enabled.

FAQs

What happens with discounts when a plan includes a free trial and a setup fee?

Discounts are not applied to a free trial invoice unless there's a setup fee and the coupon is a fixed amount. In that case, Recurly recommends setting the coupon duration to "Limited time" for one month rather than "Single use." This ensures both the setup fee and the first paid month receive the discount.

How does coupon accounting work in Recurly?

Both percentage and fixed amount coupons are applied to charge line items before tax is calculated. Credits are applied after coupons have already discounted the charges. Coupons apply to the next invoice created after redemption — they can't retroactively adjust an existing invoice. To correct an already-issued invoice, you can issue a partial refund equal to the discount amount, or do a full refund, redeem the coupon, and reissue the invoice. Free trial coupons don't offer a monetary discount and don't appear on any invoices.

Can subscribers have multiple active coupon redemptions on their account?

Yes — you can allow multiple active coupon redemptions per account, which can result in multiple discounts on a single invoice or line item. Settings for this feature are adjusted on the coupon configuration page. See the Multiple Coupons Per Account documentation for details on how stacked discounts are applied.

How do I create a coupon that discounts across several billing cycles?

Set the duration to "Limited time" and configure the period to match your plan's billing cycle. Keep in mind that if the discount is a fixed amount and eligible charges are less than the discount on any given invoice, the remaining balance won't carry forward.

Where can I find coupon redemption data?

Every coupon has a Redemptions table showing all accounts that have redeemed it and the total discount applied. For bulk coupons, a "Not redeemed" table shows all unused unique codes. You can expire unredeemed codes early — expired codes appear at the end of the table.