Recurly

Coupons and Discounts

Whether you are implementing a promotion, discount, special offer, or sale strategy, use Recurly's Coupons to create codes your customers can redeem in order to get a discount on their purchases. Track campaign success through the Coupons Dashboard and Exports.

What’s New!

We recently released a ton of new coupon options. Select a feature below to learn more:

Table of Contents

Features Overview

Coupon Accounting

Coupons can be either a percentage or fixed amount off and are applied to charge line items before tax is calculated. Credits are their own line items on an invoice and are applied after coupons have discounted the charge line items.

Coupons are always applied to the next invoice after a coupon is redeemed. A coupon cannot retroactively discount an invoice. If you need to correct an existing invoice, you can issue a partial refund on the invoice equal to the discount amount, or you can do a full refund of the invoice, redeem the coupon and issue the invoice again with the correct discount.

Percentage Discounts

Percentage discounts will apply the same percentage to each eligible charge on the invoice. Percentage discounts will never discount a plan setup fee. This difference allows merchants to create coupons that only discount plan fees and add-ons, by using a percentage discount. The reverse is true as well. Merchants can create a fixed amount discount that will only discount a setup fee. See below for more details.

Percentage Discount Example

Coupon is for 10% off Plan A. Plan A has a setup fee of $50.00, a plan fee of $15.00 and an add-on of $7.00. The resulting invoice would have these discounts:

Fixed Amount Discounts

Fixed amount discounts will apply the specified amount across all eligible charges on the invoice, starting with the first subscription line item.

Fixed Amount Discount Example

Coupon is for $20.00 off Plan A. Plan A has a plan fee of $15.00 and an add-on of $7.00. The resulting invoice would have these discounts:

Multiple Discounts on an Invoice

Merchants can allow customers to have more than one active coupon redemption on their account. This may result in multiple discounts on the same invoice or even a specific line item. To learn how multiple discounts are applied to line items, read about our Multiple Coupons Per Account feature.

Coupons Dashboard

The Coupons dashboard will show you all coupon campaigns that have been created on your Recurly site. Here you can find an existing coupon, create a new coupon, or configure your site’s Coupons Settings. Visit the Coupons dashboard in your Recurly site.

Coupons Dashboard

Use the search bar to quickly find a specific coupon in either the Redeemable or Expired Coupons table. Here are the fields you can search:

Redeemable Coupons

This table on the Coupons dashboard lists all coupons that can currently be redeemed by customers. Redeemable coupons can be edited or expired early.

Expired Coupons

This table on the Coupons dashboard lists all coupons that cannot be redeemed by customers. Any active coupon redemptions on a customer’s account are not affected by the coupon expiring. Coupon expiration only blocks new redemptions of the coupon. Expired coupons cannot be edited, but can be restored and have fields edited within the restore action.

Coupons will expire if:

Coupon Settings

On the Coupons dashboard you will see a button at the top right called Settings. On the Settings page we offer some site level coupon options:

Multiple Coupons Per Account

By default, Recurly only allows one active coupon redemption on an account at a time. Here you can enable the ability for multiple coupon redemptions to be active on an account at one time. To learn more about multiple coupons on accounts and how that affects discounts on invoices, read our Multiple Coupons Per Account feature documentation.

One-Time Charges

By default, Recurly’s coupons only discount plan charges: setup, plan, and add-on fees. In Coupon Settings you have the option to allow coupons to be created with a discount that applies to one-time charges. Once enabled, the New Coupon form will show a section called Eligible Charges. There you can select any configuration of one-time charges and/or plans.

One-time charges is a setting because most Recurly merchants do not create one-time charges. To avoid confusion on the New Coupon form, we have elected to have merchants decide if one-time charges are a part of their business and a type of charge they would want to discount.

Hosted Payment Pages

If you would like to allow coupons to be redeemed on your hosted payment pages, enable Coupons on the Hosted Page Settings page under Configuration in your Recurly account. Visit the Hosted Page Settings in your Recurly site.

Coupon Overview

Each coupon has it’s own page where you can find details about the coupon’s rules, redemptions, and take an action on the coupon. This page is called the Coupon Overview. Actions on the page will vary depending on the coupon’s status of redeemable or expired, or whether it is a single code or bulk coupon.

Coupon Summary

The right sidebar of the Coupon Overview page has the Coupon Summary. All fields that are set for the coupon will be displayed here. If you need to edit details about the coupon, click the Edit button at the top right of the page.

Redemptions

All coupons have a Redemptions table that lists accounts that have redeemed the coupon. If an account has redeemed the coupon more than once, you will see a Redemptions count greater than 1 for the row and multiple Redeemed dates. The Total Discounted column reflects the total discount amount from the coupon on that customer’s account across all redemptions of that coupon.

Not Redeemed

If the coupon is a bulk coupon, you will see a Not Redeemed table. This table includes all unique codes that have not yet been redeemed. You can hover over the right dots in any row to Expire Early the unique code. Any expired unique codes will be at the end of the table list.

Coupon Overview

Create a Coupon

To create a new coupon, click the New Coupon button at the top right on in the Coupons dashboard. You will see a form with the following fields:

Internal Name

The Internal Name is an identifier you can use within your company to remember which coupon campaign is which. This name will never be shown to customers, unless you choose to include the field through the API or email parameters. We recommend setting up a naming convention within your company to help differentiate similar campaigns. Internal Name is not a unique field and can share the same name across coupon campaigns, but we suggest you use a unique name to make referencing the campaign easier.

Code

The coupon code is the code that your customers will enter to redeem the coupon. You will need to distribute the code to your customers. You can create one code that all customers redeem by selecting “Single Code”, or you can create many unique codes by selecting “Bulk unique codes”.

Single Code

The coupon code you specify must be unique across your redeemable coupons. You can only reuse a coupon code if that coupon code exists on a coupon that was either manually expired or it reached it’s maximum redemptions. If the coupon expired by reaching it’s redeem by date, it cannot be reused.

Coupon codes can be alphanumeric and may include a dash (-), underscore (_), or a plus sign (+).

Bulk Unique Codes

To learn about creating unique codes for your coupon campaign, read our Bulk Unique Coupons documentation.

Discount

The discount can be either a fixed amount or percentage. If you are collecting payments in multiple currencies, you will see the option to specify a different fixed amount for each currency.

Duration

The duration is the period of time the coupon will discount any eligible purchases by the customer. Duration starts when the customer redeems the coupon. Once the duration has ended, the coupon is inactive on the customer’s account and will no longer discount an invoice.

There are three duration choices:

Maximum Redemptions

Maximum redemptions is the number of times the coupon code can be redeemed across all customers. By default this field is set to “Unlimited”.

Redemptions Per Account

Redemptions per account is the number of times a specific account can redeem the coupon. By default, this field is set to “1” in the UI and unlimited in the API. * Set redemptions per account to “1” if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign.

Redeem By Date

Redeem by date is the date the coupon will expire and customers can no longer redeem the coupon. By default, this field is set to “Anytime”. If you specify a date, the time will be 11:59pm in the timezone of your user profile. In the API this will be UTC. * Customers who redeemed the coupon before it expired will still have active redemptions and will continue to receive the discount until the redemption’s duration runs out.

Eligible Charges

If you have enabled one-time charges in Coupon Settings, you will see the Eligible Charges section. By default, only Plans is enabled. Here you can create coupons that only discount plans, only one-time charges, or both plans and one-time charges.

Eligible Plans

Eligible plans is the list of all plans or specific plans that the coupon can discount on an account. All plans is selected by default. If you select Specific plans, you will see a table appear where you can select the plans you want to include. * If you specified a limited time duration, make sure the plans you select have a billing cycle that matches your duration period. If the duration has a different period than your plans, you may end up discounting more invoices than you planned.

Discount Level

By default, coupons redeemed on an account will discount any subscription on the account that is for a plan the coupon discounts. We call this “Account-level”. You can now select “Subscription-level” and require the coupon to be tied to one specific subscription on the account, making sure the discount is only applied to that subscription.

Account-level

Subscription-level

Using Subscription-level for Gift Subscriptions

Gift subscriptions often create multiple subscriptions on an account. Subscription-level coupons allow the merchant to restrict the discount to only the Gifter’s subscription, or only the Giftee’s subscription. For example, you may give a customer a discount for subscribing for the first time, but you want to make sure they don’t get the same discount automatically on the next subscription they purchase.

Subscription-level Redemptions in an Upgrade or Downgrade

If you want to tie a Subscription-level coupon to an upgrade or downgrade only, you can redeem the coupon on the Edit Subscription page for the customer. This is necessary if the coupon is only eligible for the new plan the customer is moving to because you will not be able to redeem the coupon on the current version of the subscription.

We only allow coupon redemptions on the Edit Subscription page if the subscription change is effective “Immediately” and if you change something about the subscription that will result in an invoice. We will not allow you to only redeem the coupon. We don’t allow coupon redemptions with “On next renewal” changes because it could cause a conflict with any Maximum Redemption rules for the campaign or the account.

Removing subscription-level Redemptions

To remove a Subscription-level coupon from a subscription, you must remove the coupon from the account altogether. We do not allow you to associate the coupon redemption with a different subscription once the coupon has been redeemed and tied to a subscription.

How Discount Level Affects Redemption Duration

Say you give a customer a 3 month duration coupon to Plan A as a thank you for signing up. The customer gets the first month’s discount on their Subscription A and then terminates their subscription. The customer then comes back a few days later and subscribes to Subscription A again on the same account.

Payment Page Description

The payment page description will show when a customer redeems a coupon on your hosted payment pages, or if you choose to show the description on your own checkout page. The description can be up to 255 characters. * If you would like to allow coupons to be redeemed on your hosted payment pages, enable Coupons on the Hosted Page Settings page on your Recurly site.

Invoice Description

The invoice description will show in the Discounts Applied notes section that shows on the invoice when there are coupons applied to the invoice. The description can be up to 255 characters.

Redeem a Coupon

When a coupon is redeemed on an account, it creates a redemption, which is the account’s instance of the coupon. Coupons are redeemed on customer accounts and those redemptions apply discounts to future invoices. There are two methods of redemption, through a purchase or directly on an account.

Redeem at Purchase

In most cases, you will want to allow your customers to enter a coupon code on your checkout page and have that redemption applied to their purchase. You can do this using the hosted payment pages or your own checkout page with Recurly.js and the API. Here are some general rules to consider:

Hosted Payment Pages

To allow coupons to be redeemed on the hosted payment pages, select the Coupons option on the Hosted Pages Settings page under Configuration on your Recurly site.

Hosted Payment Pages Coupon Redemption Field

Redeeming Coupons

API and Recurly.js

You can have customers redeem coupons in your own checkout page using Recurly.js and or the API. Makes sure the coupon is being redeemed within the subscription creation action in order to avoid redemptions on accounts where the subscription failed due to a declined transaction. If you redeem the coupon directly on the account, separate from the subscription creation action, you will see redemptions for failed signups.

Recurly UI

When adding a subscription to a customer’s account in the Recurly UI, you can enter in a coupon code and redeem the coupon at the same time.

Redeem on Account

If you would like to discount the next invoice of an existing subscription or a one-time charge invoice, you can redeem the coupon directly on the account, outside of a purchase action.

Recurly UI

Each account page has it’s own Coupon Redemptions page that you can access by clicking on Manage Coupons in the Account Information module or above the Coupon Redemptions table lower on the account page. On the Coupon Redemptions page you can find coupons in the Redeemable Coupons table and click “Redeem” in the hover actions to the right.

API and Recurly.js

You can redeem a coupon on an existing account, outside of a purchase, through our API Coupon Redemption resource. We do not support this functionality through Recurly.js. If the coupon is subscription-level, you will need to specify the uuid of the existing subscription you want to tie the redemption too in the redemption request.

Hosted Account Management

We do not currently allow coupons to be redeemed on existing accounts through the hosted account management pages. If you would like to include this option on your hosted account management pages, please submit a feature request through a support ticket.

Remove a Redemption

If you need to remove a redemption from a customer’s account, you can do so through the Recurly UI or the API. Visit the account and click on Manage Coupons in the Account Information module or above the Coupon Redemptions table lower on the account page. Manage Coupons will take you to the Coupons Redemptions page for the account where you can select the redemption you want to remove from the Redeemed on Account table. You will find the Remove action in the right hover actions for the table row.

If you only allow one active coupon on an account, you can also remove an existing coupon redemption by redeeming a new coupon. When accounts are limited to one active redemption at a time, redeeming a new coupon will automatically remove the existing coupon and then redeem the new one.

Edit a Coupon

Redeemable coupons can be edited to change display text or redemption rules. We do not allow you to edit any coupon attributes that would affect active redemptions currently on a customer’s account. These are the coupon fields that can be edited after the coupon is created:

To edit a coupon, visit the coupons dashboard and find the coupon you want to edit in the Redeemable Coupons table. Click on the coupon’s internal name. This will take you to the coupon’s overview page where you will see an Edit button in the top right corner. Click Edit and you will be taken to the edit page for the coupon. Edit the fields you want to change and click Save Changes.

Note: We do not store a history of changes, so you will not see what the coupon fields were before you changed them. Invoice Description will not update on already created invoices, but will be updated on new invoices created after the change.

Expire a Coupon

Coupons can expire automatically based on the rules you set for the coupon campaign, or you can choose to manually expire the coupon. Expiring a coupon blocks customers from redeeming the coupon. Customers who have already redeemed the coupon are not affected. Their active redemptions will continue to discount their accounts.

Expire Early

Coupons can be manually expired in an action we call Expire Early. To expire a coupon, visit the coupon’s overview page and select Expire Early in the top right corner. This will ask you if you are sure you want to expire the coupon. Once you confirm, the coupon will expire immediately and will now live in the Expired Coupons table on the coupons dashboard.

Automatically Expire

Coupons will automatically expire if you set a redeem by date or maximum redemptions and either of those limitations are reached. The redeem by date will expire at 11:59 PDT on the day you select. The maximum redemptions will expire the coupon as soon as the last redemption in the limit is successful.

Bulk coupons with all unique codes redeemed will be considered Expired in the UI, even though their true status is active in the API.

Reuse a Coupon Code

If a coupon is expired early or reaches it’s maximum redemptions, the coupon code may be reused when creating a new coupon. Any existing customers with active redemptions from the original coupon on their account will be grandfathered into the terms of the old coupon. For instance, you can create a coupon for $12 off and then expire it and create a new one with the same coupon code with a price of $15 off. Any customers that redeemed the original coupon will remain at the $12 discount unless you remove the coupon from their account and re-add it.

If a coupon expired by reaching it’s redeem by date, you will not be able to reuse the coupon code.

Restore a Coupon

If a coupon has expired, you can restore the coupon in order to make it redeemable again. If the coupon has reached it’s maximum redemptions or the redeem by date, you must edit those fields before the coupon can be restored. You can edit all other editable fields in the restore action.

To restore a coupon, visit the coupons dashboard and find the coupon you want to restore in the Expired Coupons table. Click on the coupon’s internal name. This will take you to the coupon’s overview page where you will see a Restore button in the top right corner. Click Restore and you will be taken to the restore page for the coupon. Edit the fields you want to change and click Restore Coupon.

Note: We do not store a history of changes, so you will not see what the coupon fields were before you changed them. Invoice Description will not update on already created invoices, but will be updated on new invoices created after the change.

Bulk Coupons

Bulk coupons with all unique codes redeemed will be considered Expired in the UI, even though their true status is active in the API. In this case, you will be asked to add additional unique codes to the bulk coupon in order to restore the coupon through the UI.

To restore a unique code within a bulk coupon campaign, find the bulk coupon’s overview page and select “Restore Code” in the right hover actions in the row of the unique code.

Coupon and Discount Exports

There are many different exports you can use to understand the status or success of your coupon campaigns. All exports can be found on the Exports page under Reports.

Coupons

This export is essentially an inventory of your coupon campaigns. The export will show you all coupons that exist on your site, the rules for those coupons, and when they were created or expired.

See the details of this export in our Coupons export documentation.

Coupon Redemptions

This export will show you the success of your coupon campaign. The export will show you who has redeemed your coupons, when they redeemed it, and how much the redemption has discounted their account. Filter this report by your coupon and you can total the discount amount and build a chart that shows redemptions over time.

See the details of this export in our Coupon Redemptions export documentation.

Coupons - Bulk Unique Codes

This export will list a specific bulk coupon’s unique codes, which you can import into your email system or other tools to distribute the codes to customers. This export can also be used to track the success of your bulk coupon campaign because it includes the same redemption information found in the Coupon Redemptions export.

See the details of this export in our Coupons - Bulk Unique Codes documentation.

Invoices - Summary

This export answers which coupons were applied to the invoice, noted in the coupon_code column.

See the details of this export in our Invoices - Summary export documentation.

Invoices - Line Items

This export answers which coupons were applied to the line item and the total discount they created on the line item.

See the details of this export in our Invoices - Line Items export documentation.

Invoices - Line Items - Coupons

This export answers what the individual discounts were for each coupon applied to the line item. This export will only show if you have the Multiple Coupons Per Account feature enabled in your coupon Settings.

See the details of this export in our Invoices - Line Items Coupons export documentation.

Coupon Examples

First Month Free

Create a coupon that fully discounts the first month.

Does your plan have a free trial and a setup fee?

Coupon redemptions will not discount a free trial invoice unless there is a setup fee and the coupon is a fixed amount discount. If you are using a fixed amount discount on a plan that has a trial and a setup fee, you will want to use a limited time duration of 1 Month, instead of Single Use. A 1 Month duration will discount both the setup fee and the first month.

Multiple Billing Cycles Discounted

Create a coupon that discounts multiple billing cycles. * Duration: Limited time (match period to your plan’s billing cycle length)

Note: If the discount is Fixed Amount and the eligible charges on the invoice are less than the discount amount, the remainder of the discount will not be carried over to future invoices.

Special Occasion

If you want to put out a coupon that can only be redeemed on a particular day, such as a holiday, you need to set the redeem-by date of the coupon to that particular date (such as February 14th for a Valentine’s Day special). Please note that this limits the time a customer can redeem a coupon, but the coupon will still be applied to the next invoice generated after redemption, whether or not it occurs on that day.