How can a coupon be redeemed 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

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.

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.