--- updatedAt: 2026-09-21T15:26:49.000Z agentTools: siteIndex: https://docs.recurly.com/llms.txt projectIndex: https://docs.recurly.com/recurly-subscriptions/llms.txt --- # Coupons & discounts Create and manage coupons and discounts in Recurly — configure discount types, duration, redemption rules, and eligible plans or items to run targeted promotions for your subscribers.
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 6Coupon redemption 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 Keep these constraints in mind when configuring coupons:
# 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, limited time (days, weeks, or months), or a defined number of billing periods.
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 When a coupon can be redeemed: anytime, a specific date, or within a set period of time (days, weeks, months, years). After this date or period, the coupon can no longer be redeemed. Defaults to anytime. A set period of time is only available with bulk coupons.
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.
# 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.
Billing periods The discount applies for an exact number of billing cycles, regardless of cycle length. This eliminates the need to approximate billing periods using days, weeks, or months. Compatible with fixed amount, percentage, and free trial discount types. Subscription level only. Available in the UI and API.
## Billing period coupons Billing period coupons let you define duration in terms of exact billing cycles rather than fixed time intervals. Previously, time-based durations (days, weeks, months) served only as an approximation of billing periods — requiring overhead to align them correctly and introducing inconsistencies across billing cycle lengths. With billing period coupons, the discount applies for precisely the number of cycles you specify, across any billing period type. **How billing period coupons work:**
API support Billing period coupons are available in the UI and API. Understanding a coupon's current state, when it will expire, and the total discounted amount has never been easier with the new coupon_redemptions object returned in several endpoints, including the renewal preview API.
# Coupon redemption Setting a redeem-by date can help you forecast when a coupon could be used and can tie redemptions to specific promotional periods or marketing pushes. When creating a single coupon, you have two redeem-by options — **anytime** and **a specific date**. A coupon set to **anytime** never expires automatically; a coupon with a specific date expires once that date passes. A third option, **within a set time period**, is available for bulk coupons. It lets you set a relative expiration period (for example, 7 days, 2 weeks, or 1 month) that starts individually for each unique code when it's generated, rather than when the coupon is created. Each time you generate a new batch of unique codes, you can set a new redeem-by window in the UI or by updating the bulk coupon via the [API.](https://recurly.com/developers/api/v2021-02-25/index.html#tag/coupon) This gives you more flexibility and reduces the number of unused or duplicate coupons. The redeem-by window is converted to a date and displayed on the bulk coupon's page. ```text redeem_by fields { "name": "string", "code": "string", // ... "redeem_by_date": "string", "redeem_by_interval_unit": "day", //"day", "week", "month", "year". Bulk coupons only "redeem_by_interval_amount": 1, //Must be paired with redeem_by_interval_unit // ... "discount_type": "fixed" } ``` ## 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.
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 or email support@recurly.com.
## 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:
## 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:
Note Changes only affect coupons redeemed after the update is saved. Existing redemptions are not impacted.
## Removing a coupon from an account
1

Go to Coupon Redemptions

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

2

Locate the coupon

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

3

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 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. 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. 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. Use the Billing periods duration type and set the number of cycles to match your needs. Unlike the Limited time option, billing period coupons align precisely to your plan's billing cycle regardless of cycle length — no manual time conversion needed. 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. 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. # Sub pages * [Bulk unique coupons](https://docs.recurly.com/recurly-subscriptions/docs/bulk-unique-coupons.md) * [Multiple coupons per account](https://docs.recurly.com/recurly-subscriptions/docs/multiple-coupons-per-account.md) # Sibling pages * [Free trial management](https://docs.recurly.com/recurly-subscriptions/docs/free-trial-management.md) * [Gift subscriptions](https://docs.recurly.com/recurly-subscriptions/docs/gift-subscriptions.md) * [Gift cards](https://docs.recurly.com/recurly-subscriptions/docs/gift-cards.md) * [Gift cards dashboard](https://docs.recurly.com/recurly-subscriptions/docs/gift-cards-dashboard.md)