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:
- Percentage-off coupons are only applied to recurring charges, not one-time charges or set up fees.
- Flat-rate coupons are applied to recurring charges and set up fees, but not one-time charges.
- If a coupon is applied to an account with an existing credit, the coupon will be used first.
- Coupons are applied to the next invoice after a coupon is redeemed.
- An account can only have one active coupon at a time.
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.
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 lifespan determines how long a coupon will remain active on an account, and how many invoices the coupon will be applied to. There are three lifespan choices:
Forever - A recurring discount that will be applied to each billing cycle.
Single Use - A one-time flat discount. Once redeemed, single use coupons will be applied to the first recurring invoice, and will go inactive immediately afterward.
Note: Plans with a free trial still have an initial invoice. If you wish to use a coupon on a plan with a free trial, you must use one with a Forever or Limited Time lifespan.
These coupons will also not apply if the customer upgrades or downgrades.
Limited Time - A recurring discount that is only valid for a specified number of months. The coupon will discount any invoices generated between redemption date and the limited time date.
Coupons can be restrained in three ways.
- Limit Plans - Allows a coupon code to be applied to select subscription plans or all plans (including those subscription plans created in the future).
- Max Redemptions - The maximum amount of times a coupon can be used before it expires. Note: Once a coupon has been used for the maximum number of times, it will disappear from your Coupons Console.
- Redeem-by Date - The date/time through which a coupon offer is valid for redemption. After this date, a coupon cannot be applied to a users account. But if applied, it may still discount invoices according to the coupon lifespan.
A few other customization options are available for coupons:
- Hosted Payments Page Description - A short description that will display on the Hosted Payments Page.
- Invoice Description - A more detailed description of the coupon offer that appears on the customer invoice. Not available yet.
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.
First Month Free
On a plan with a free trial period: You will need to give the coupon a lifespan 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 lifespan 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 lifespan 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.
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.
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.
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.
There are two exports related to coupons.
- The Coupons export will show you a list of coupons you have created, including information such as coupon code, discount, and redeem-by date. See this page for more information about this export.
- The Coupon Redemptions export will show you a list of accounts that have redeemed coupons, as well as what coupons they have redeemed. See this page for more information about this export.