Recurly supports the addition of coupon codes to customer accounts, enabling merchants to offer a variety of promotions, discounts, and special offers. Coupons are supported via the Hosted Payment Pages, Recurly.js, and API. They can also be added to an account via the Recurly admin console.

How Coupons Work

Coupons allow you to give your customers discounts on their subscriptions, whether through a flat-rate (dollars off) or a percentage. There are a few rules to keep in mind when working with coupons:

Coupons Dashboard

The Coupons dashboard can be found under the Configuration section of the navigation. Here, you can see a list of your redeemable and non-redeemable coupons, perform a coupons export, create a new coupon, or search for a coupon.

To disable or enable coupons on your hosted payments page, go to the Hosted Payment Page Settings.

Coupons Dashboard

Creating a Coupon

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

Coupon Name & Coupon Code

The coupon name is the name that will be displayed for the coupon. The coupon code is the code that you will give to your customers to redeem the coupon.


The discount can either be a flat dollar amount subtracted from the subscription total, or a percentage of the total.


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:


Coupons can be restrained in three ways.

Other Settings

A few other customization options are available for coupons:

Bulk Coupon Creation

Coupons can be created in bulk using the API. Set the coupon options for the base template, then change the coupon_code for each coupon to a unique and random string (should be at least 16 characters, non-consecutive).

Modifying and Expiring Coupons

Once a coupon has been created it cannot be modified or deleted. However, a coupon can be expired from the Coupon console by clicking Expire next to the coupon or on the coupon details page.

Once expired, the coupon code may be reused, but any existing customers with that 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.

A coupon will automatically be expired when it has reached its set number of redemptions or expire date. At that point the coupon code can be reused. This is a change from behavior prior to May 2014 wherein expired coupon codes could not be reused.

Coupon Examples

First Month Free

On a plan with a free trial period: You will need to give the coupon a duration of one month. If you make it single-use, then it will get applied to the initial, $0.00 invoice and then expired.

On a plan without a free trial period: You can give the coupon a duration of single use.

Multiple Months Discounted

To give your customers a discount over multiple months, you should give make the coupon a percentage-coupon and give it a duration of the amount of months you want discounted. We recommend that you use a percentage coupon for this because if the coupon is a flat-rate and over the subscription price, the extra money will not become a credit, or be recorded in any way.

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.

Redeeming Coupons

Coupons can be redeemed by the customer, in the admin panel or through the API. To allow a customer to redeem a coupon on a Hosted Payment Page, you must enable the coupon field in your Hosted Payment Page settings.

When a customer redeems a coupon on a Hosted Payment Page, the discount will be applied immediately and shown to them.

Redeeming Coupons

Only one coupon may be active on an account at a time. Coupons can be removed from a user’s account through the Recurly admin console by clicking Remove Active Coupon under the Coupon Redemptions section of their account. You can also remove coupons using the API.

Coupons Exports

There are two exports related to coupons.