Coupons and Discounts

Features Overview

Single code coupons for mass distribution with the option to limit maximum redemptions and or set a specific redeem by date
Bulk unique codes for individual delivery and tracking
Discounts at the account level or tied to specific subscriptions
Coupons that discount one-time non-subscription charges
Item coupons specific to items from Item Catalog
Percentage discounts or fixed amount discounts in multiple currencies for one coupon
Free trial coupons to give new subscriptions special free trial lengths
Offer your discount for one purchase, a limited time, or forever
Set how many times a customer can redeem a specific coupon
Limit customers to one active coupon, or allow multiple coupons on their account and purchases
Ability to edit, expire, and restore coupon campaigns

Learn how to improve your renewal rates with customized lifecycle marketing promotions.

Coupon Accounting

Percentage or fixed amount off coupons 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.

Percentage and fixed amount off 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.

Free trial coupon redemptions create a custom trial period when the subscription is created, so they expire as soon as the subscription is created. Since they don't provide a monetary discount, they are excluded from the first invoice and any future invoices.

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:

Plan A - Setup fee of $50.00 will not be discounted
Plan A - Plan fee of $15.00 will be discounted 10% for a discount total of ($1.50)
Plan A - Add-on of $7.00 will be discounted 10% for a discount total of ($0.70)
The total discount on the invoice is ($2.20)
The customer pays $69.80

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.

If the fixed amount discount is larger than the eligible charges on the invoice, the remaining discount will not be returned to the coupon redemption and will not carry over to other invoices.
Fixed amount discounts will discount plan setup fees. If you want to create a coupon that only discounts a setup fee, create a Single Use coupon with a Fixed Amount that equals or is less than the setup fee amount. Since the setup fee is always the first subscription line item on the invoice, the fixed amount discount will start with that line item and will not be large enough to extend to other line items.
One-time charges are listed before subscription charges on the invoice, but are discounted after subscription charges. If you have a coupon that discounts both subscription and one-time charges, and a fixed amount discount that is less than the total subscription charges, it will not discount the one-time charges on the invoice.

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:

Plan A - Plan fee of $15.00 will get a full discount of ($15.00)
Plan A - Add-on of $7.00 will get a discount of ($5.00), since there was only $5.00 remaining on the coupon redemption
The total discount on the invoice is ($20.00)
The customer pays $2.00

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.

Item Coupons

📘
Item Coupons
Item Coupons give merchants the flexibility to create discounts that are only applicable to the purchase of specific items in their catalog.

Item coupons can only be applied to items, and will not apply to other line items that are not items in the catalog
Item coupons can be be a fixed amount or a percentage
Item coupons can be applied to the specific items it was associated with:
- Single specific item
- A group of specific items
- All items
Item Coupons can be set to be applied only to item specific charges when items are purchased as one time charges.
Item Coupons can be set to be applied only to item specific charges on all plans or limited to specific plans. The plan will not be discounted, only the item based add-ons for the selected plan(s).
Applied across to item specific charges with any one time charges and any plans
Item Coupons can be set to be applied to both one time and when included with subscription purchases.
Item Coupons are applied after other coupons (one time charge and plan coupons) are applied
Will be applied within the percentage or fixed price calculation as the last calculation based on the merchant configuration.
Managing item coupons are available via API V3, V2, and the Recurly App admin UI.

API V3 Sample Requests to Create an Item Coupon (see developer documentation for full request requirements, as these are examples only):

{
<other coupon fields>
applies_to_all_items: true, 
item_codes: [ ]
}

Or:

{
<other coupon fields>
applies_to_all_items: false, 
item_codes: [
    item_code: item_a,
    item_code: item_b,
    item_code: item_c,
]
}

Item Coupon Redemption Examples

Given the following coupons (applying fixed amount discounts first with compounding discounts enabled):

Coupon A is 10% off on one-time purchases
Coupon B is $20.00 off on one-time purchases of any item

For an invoice with:

One-time purchase of $50.00
One-time item purchase of $60.00
Total of $110.00 without discounts

Redemption of only Coupon B would result in:

One-time purchase of $50.00 with no discount for a total item cost of $50.00
One-time item purchase of $60.00 with a ($20.00) discount for a total item cost of $40.00
Total of $90.00 with discounts

Redemption of only Coupon A would result in:

One-time purchase of $50.00 with a ($5.00) discount for a total item cost of $45.00
One-time item purchase of $60.00 with a ($6.00) discount for a total item cost of $54.00
Total of $99.00 with discounts

Redemption of both Coupon A and Coupon B would result in:

One-time purchase of $50.00 with a ($5.00) discount for a total item cost of $45.00
One-time item purchase of $60.00 with a ($24.00) discount for a total item cost of $36.00
Total of $79.00 with discounts

Notes and limitations

Item coupons are not compatible with free trial coupons.
Current coupons will continue to apply to both item-backed and non-item-backed charges. Sending applies_to_all_items: false, item_codes: [ ] will result in a coupon that can still apply to both item-backed and non-item-backed charges.
There is no mechanism to say a coupon DOES NOT apply to item backed charges.
There is no mechanism to say that a coupon applies to all non-item charges and only specific items.

Free Trial Coupons

Free trial coupons can be used to give new subscriptions different free trial lengths. This is useful if you offer a plan that includes a 1-week free trial and want to test how conversion changes when new subscriptions come with a 1-month free trial instead. When the coupon is redeemed upon creating a new subscription to that plan, the new subscription will have a 1-month free trial instead of the normal 1-week free trial.

Free trial coupons can also be used to test shorter free trial periods (e.g. testing a 1 week free trial on a plan that normally comes with a 1-month free trial).

In addition, free trial coupons can be redeemed on new subscriptions to plans that don’t normally have a free trial, although merchants will not be able to use Recurly’s Trial Ending Reminder email to remind customers when their free trial is ending.

A few additional details about free trial coupons:

They must be redeemed when a customer is creating a new subscription
If you are explicitly setting a trial_ends_at date when also redeeming a free trial coupon in the subscription sign-up, the free trial will follow the trial_ends_at date, not the coupon rules
Redemptions expire immediately and therefore no Discounts Applied notes will appear on the free trial invoice, and the redemption will not appear in the invoice exports
The API does not return detail on free-trial coupon redemptions. This also applies to the redemptions by invoice API request. See documentation here.
The free trial invoice line items will correctly display the length of the free trial associated with the coupon
The coupon exports include information about the free trial length associated with the coupon and the redemptions
Merchants can create free trial coupons as either single use or bulk coupons

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.

958

Search

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:

Internal Name
Code
Plan Name
Plan Code
Fixed Amount (e.g. - $10.00 USD can be searched as "10")
Percentage (e.g. - 50% can be searched as "50")

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:

The Maximum Redemptions for the coupon has been reached.
The Redeem By Date for the coupon has been reached.
There are no remaining unique codes for a bulk coupon.

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.

984

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". Coupon codes are limited to a maximum of 50 characters.

Single Code
The coupon code you specify must be unique across your redeemable coupons. You can only reuse a coupon code if that code exists on a coupon that was either manually expired or reached its 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.

Type of discount

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

A fixed amount coupon redemption will apply the currency that matches the invoice.
See Coupon Accounting for information on how fixed amount and percentage discounts are applied to line items.
Free trial coupons require that you define how long the associated free trial should be. When doing so, be sure that the length specified is the full length of the free trial that you want customers to receive when they redeem the coupon. For example, if you have a plan with a 1-week free trial, and you want to offer a coupon that gives new subscribers a total of 1 month of free trial, then the length of the free trial coupon should be 1 month.

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. Free trial coupons can only be single use, so this section does not appear if the discount type is free trial.

There are three duration choices: Forever, Single Use and Limited Time:

Forever: A recurring discount that will be applied to each billing cycle until manually removed from the account.
Single Use - Percent and fixed amount coupons: A single invoice discount. Once redeemed, single-use percent and fixed amount coupons will be applied to the next invoice that includes eligible charges and will go inactive immediately afterward. Single-use coupons will not be applied to free trial invoices unless the plan has a setup fee and the coupon is a fixed amount.

Single Use - Free trial coupons: Free trial coupons can only be single-use because once they are redeemed, free trial coupons create a custom free trial on the new subscription and then the redemption expires.

Note: If you wish to use a fixed amount coupon on a non-trial invoice for a plan with a free trial and a setup fee, you must use one with a Forever or Limited Time duration. In addition, single-use coupons will not apply to new charges if the customer upgrades or downgrades mid-billing cycle.
Limited Time: A recurring discount that is only valid for a specified number of days, weeks, months, or years. The coupon will discount any invoices generated during the lifespan of the coupon. We recommend you select a period that matches the length of the subscription for the eligible plans included in the coupon. Limited lifespan coupons will automatically expire one hour prior to the anniversary of their redemption.

Note on applying a coupon to a subscription with a free trial: You will need to include the free trial duration in the coupon duration. For example, if you offer a plan with a 1-month free trial and wish for customers to receive 4 months discounted after the trial expires, we recommend setting the Coupon Duration to 5 months:

1 free trial month + 4 months discounted after the trial expires = 5-month coupon duration

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".

Set a maximum number of redemptions if you want to create a coupon where the first "500" customers to redeem the coupon get the discount.
A coupon will expire when it hits its maximum redemptions.

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

The 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 define which charges are discounted by the coupon. You can create coupons that only discount plans, only one-time charges (if you have enabled one-time charges in Coupon Settings), or both plans and one-time charges.

Plan charges include: setup, plan, and add-on fees
One-time charges are created through the "Add Charge" option on account pages, or as adjustments in the API
If "Plans" is selected, the Eligible Plans section will show
Item discounts are able to be set that will not apply to other charges.

Eligible Plans

Eligible plans is the list of 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 subscription term 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.
Item discounts are able to be set that will not apply to other charges, and will only be applicable on specified plans.

Discount Level

Discount level specifies whether the coupon can discount any eligible subscription on an account or only a specific subscription. "Account-level" is selected by default. Free trial coupons can only be subscription-level, so this section does not appear if the coupon type is free trial.

Account-level

Coupon redemptions will discount all subscriptions for eligible plans on an account.
If a subscription is terminated, active coupon redemptions on the account will remain active on the account.

Subscription-level

Coupon redemptions will only discount one specific subscription on an account. Even if the coupon is configured to have unlimited redemptions, you can only redeem a unique subscription-level coupon once on a given subscription.
Coupons must be redeemed on existing subscriptions or redeemed within the creation of a new subscription on the account. Free trial coupons can only be redeemed within the creation of a new subscription on the account.
If a subscription is terminated or changed to an ineligible plan, associated subscription-level coupon redemptions that are still active on the account will be removed from the account.
A subscription can have more than one subscription-level coupon redemption tied to it.
Coupon redemptions tied to a subscription will have the grey italicized words "Subscription-level" under the internal name of the coupon in the Coupon Redemptions table on the Account
Subscriptions on the account will show a list of coupon redemptions that are tied to the subscription. Active redemptions are shown on the main account page in the subscription module. The specific subscription page will include a Coupon Redemptions table that is filtered to only show coupon redemptions associated with the subscription.

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.

Account-level coupons would have kept the coupon redemption active on the account for the full 3 months duration. This means that the customer would have received the discount again when they subscribed a second time.
Subscription-level coupons would have expired the coupon redemption on the account at the time the subscription terminated. This means that the customer would not receive a discount when they sign up a second time. They would pay full price.

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. Free trial coupons do not provide a monetary discount on a subscription, and therefore they do not appear on any invoices. Consequently, you cannot enter an invoice description for free trial coupons.

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:

The purchase must include eligible charges for the coupon in order for the redemption to be successful. For example, a coupon only for Plan B cannot be redeemed on a subscription sign-up for Plan A.
If the subscription sign-up fails due to a transaction decline, the coupon will not be redeemed on the account.
If you only allow one active coupon on an account at a time and the purchase includes a new coupon, the new coupon will replace the existing coupon on the account.
If you allow more than one active coupon on an account at a time and the purchase includes a new coupon, the new coupon will be added to the active redemptions on the account and we be considered after the existing redemptions when discounts are applied to the invoice.
If the coupon is subscription-level, redeeming it in a subscription creation action will automatically tie the redemption to that subscription.
Account-level coupons can be redeemed in a subscription creation action and can discount the new subscription, but are not technically tied to the subscription and could discount additional subscriptions added to the account later on.

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

345

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 at Upgrade or Downgrade

You can redeem a coupon in a subscription upgrade or downgrade to apply the discount to the change invoice. This option is useful for Subscription-level coupons that apply only to the new version of the subscription.

The coupon's eligible charges must include the new plan of the subscription.
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.
You must make a subscription change that would generate an invoice (e.g. - change the plan, quantity or price). You cannot only redeem the coupon in the subscription change. Instead, you should redeem the coupon directly on the account.
The discount value of a fixed amount coupon applied in an immediate subscription change will be prorated at the same rate of the subscription being changed.

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 a percentage or fixed amount off coupon directly on the account, outside of a purchase action. Free trial coupons cannot be redeemed on an account; they must be redeemed when creating a subscription.

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.

If the coupon is subscription-level, the redeem action will ask you to select the subscription on the account you want to tie the redemption to.
If the coupon is a bulk coupon, the redeem action will ask you to type the unique code you would like to redeem. You will need to visit the Coupon Overview page to find a unique code that has not been redeemed and then pass that code in the redeem form. Note that unique codes are often emailed to individual customers, make sure the unique code you select has not been shared with a different customer. Recurly users with access to only the Customer's section will not be able to visit the Coupon Overview page and will need to ask an administrator for a redeemable unique code.

🚧
Duplicate Coupon Codes
We strongly advise against using the same coupon code more than once. This is not best practice within Recurly and can lead to complications querying data and redeeming coupons.

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:

Internal Name
Maximum Redemptions
Redeem By date
Redemptions Per Account
Payment Page Description
Invoice Description (not applicable to free trial coupons)

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 keep 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.

Internal Name
Maximum Redemptions
Redeem By date
Redemptions Per Account
Payment Page Description
Invoice Description (not applicable to free trial coupons)

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.

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.

Bulk coupons are treated as expired in the UI when all unique codes are redeemed because they technically cannot be redeemed and we would like to reflect them as such in your Coupon tables.
Bulk coupons require two separate API calls to be created. One to create the bulk coupon and one to generate the unique codes. We need to keep the status of the bulk coupon active when there are no redeemable unique codes so you can hit the generate unique codes endpoint without having to restore the bulk coupon each time. This is important for merchants who only want to create unique codes on the fly when a customer initiates a redemption request.
If there are expired unique codes within the bulk coupon campaign, the bulk coupon will never expire if the remaining codes are all redeemed. The coupon will only expire if you manually expire the campaign or if the max redemptions or redeem by date are reached.

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.

The coupon_code column will show a comma separated list of coupon codes if the invoice had more than one coupon code applied.
The coupon codes are a unique list of coupons applied to the invoice. If the coupon had multiple redemptions applied to the invoice, you will see the coupon mentioned only once in this list.
Coupons used to calculate returned credits will show in this list.

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.

The adjustment_discount column will show the total discount for the line item.
The adjustment_coupon_code column will show the coupons that created the discount on the line item. Free trial coupon redemptions expire immediately and therefore the adjustment_coupon_code will not be populated for free trial coupons.
You will see a comma separated list of coupon codes if the line item had more than one coupon code applied.
The coupon codes are a unique list of coupons applied to the line item. If the coupon had multiple redemptions applied to the line item, you will see the coupon mentioned only once in this list.
Coupons used to calculate returned credits will show in this list.

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.

This export creates a row for each line item discount. A line item with multiple discounts applied will have multiple rows in the export.
The adjustment_discount column will show the portion of the line item discount created by the specific coupon in the adjustment_coupon_code column for that row.
The adjustment_coupon_code will only show one coupon code. If you see two rows for the same line item with the same coupon code, it means the coupon was redeemed more than once and more than one redemption discounted the line item. Free trial coupon redemptions expire immediately and therefore the adjustment_coupon_code will not be populated for free trial coupons.
Line items for credits will also show any coupons and discounts applied to calculate the correct credits to return.
Note that the “adjustment_origin” field is populated with “plan” (not “plan_trial”) if the subscription is discounted with a free trial coupon but the plan doesn’t have a free trial by default.

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.

Discount: 100%
Duration: Single Use

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 term 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.