The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Gift Cards

Increase customer acquisitions with a gift card program. Add gift card purchases to your checkout and allow gift card recipients to redeem the gift card for credit towards any of your products.

Feature Overview

  • Available with Recurly's Professional and Enterprise plans
  • Full functionality testable in sandbox mode
  • Create one gift card product with multiple amount options
  • Support gift card purchases with a unique redemption code generated by Recurly
  • Allow gift card recipients to redeem the gift card credit for payment on any subscription or product
  • Flexibility to not require a credit card from gift card recipients
  • Gift subscription and conversion tracking

Before You Get Started

Before starting any gift card program, it is important that you talk with a legal and financial advisor. There are many laws around gift cards, both at the federal and state level. For example, rules around expiration dates, dormant account fees, cash payouts, and escheatment. Recurly Gift Cards is a tool to create a gift card program, but does not manage your compliance with gift card regulation. You will be responsible for understanding your compliance requirements and maintaining that compliance. Additionally, consider how you will account for unspent card balances within a gift card program, in relation to revenue recognition.

Finally, gift card sales may increase your fraud risk. Gift cards are often bought with stolen credit cards and resold on secondary sites to unsuspecting victims. You may find that a chargeback is for a gift card redeemed by someone who thought they purchased a good gift card. To decrease loss due to fraudulent gift card purchases, we recommend that you evaluate your fraud management tools and processes. Ask us about how we can help you decrease your fraud.

Create Your Gift Card Product

Recurly currently supports one gift card product that can have multiple preset amounts for customers to choose from.

To create your gift card product:

  1. Go to Configuration > Gift Cards
  1. Click "Get Started"

  2. Enter an Amount and click "Add". We recommend aligning your gift card amounts with your subscription plans/tiers. Consider customers who may have to pay tax. Using a higher amount will help cover possible taxes and may incline customers to buy more of your services or products.

  1. Enter additional amounts if you like. Delete an amount by hovering over the dots at the right of the row and click "Remove". Merchants with multiple currency support will see a dropdown to select the Currency of the Amount.
  1. Enter a Display Name for the gift card, which will appear on the purchase charge and redemption credit line items

  2. Enter a Product Code. This is the product sku.

  3. Enter an Accounting Code. This is the general ledger for your gift card purchase charge and redemption credit accounting.

  4. Upload one design image by clicking "Choose File" and selecting the image from your computer. This image will be displayed in the Gift Card Delivery email template.

  5. Click "Create Gift Card"

  6. Once created, you can view your gift card product details at anytime from the Gift Cards page

Edit Your Gift Card Product

To edit your gift card, go to Configuration > Gift Cards and click "Edit Gift Card" in the top right corner.

Edits to a gift card will update the gift card immediately. New gift card purchases will use the updated version of the gift card. Existing purchases of old gift card amounts will respect the original purchase amount.

Purchase a Gift Card

Once the gift card product is created, you can allow customers, gifters, to purchase gift cards for their friends and family, recipients. When a gift card is purchased, a gift card is created in Recurly with a unique redemption code. At the time of purchase the gift card is associated with the gifter's account. The gift card does not yet have an association with the recipient's account. The recipient association will come at the time of redemption.

Gifter Account

A gift card can be purchased by a new or existing customer. If the gifter is a new customer, you will create a new account for them in the purchase action. This gifter account is where the purchase invoice, billing information, and transaction live.

Amount

Recurly supports multiple preset gift card amounts. The gifter must choose from one of the amounts configured for the gift card product. We do not yet support custom gift card amounts specified by the gifter. Custom amounts will not be a part of the initial Gift Cards launch.

Delivery Method

Recurly supports two delivery methods, email and post.

Email

When a gift card is purchased with email delivery, Recurly will automatically send the recipient the Gift Card Delivery email with the redemption code and other gift card details. If you would like to send your own email to the recipient, disable the Gift Card Delivery email template. The purchase event will trigger a purchased_gift_card_notification webhook that you can use to know when to send your gift card email and the recipient's email address to send it to.

If you would like to allow gifters to schedule a future send date, see the Future Send Date section below.

When email delivery is selected, Recurly will require the gifter to provide a recipient email address.

Post

Post is available for businesses that want to offer the option to have a physical version of the gift card mailed to the recipient. Recurly will collect the shipping details and generate the gift card redemption code. The business is responsible for printing the redemption code on a physical gift card and delivering it to the recipient.

When post delivery is selected, Recurly will require the gifter to provide a full shipping address for the recipient. The address fields are:

  • Address 1 (required)
  • Address 2
  • City (required)
  • State (required if country is US, CA, IT, or NL)
  • Zip (required)
  • Country (required)
  • Phone

Future Send Date

Gifters who are early shoppers can select a future date for the Gift Card Delivery email to be sent to the gift recipient. This future date must be at least an hour in the future and less than a year from the purchase date.

Our API supports both day and time for the future send date (deliver_at is the API parameter name). The common practice is to only allow the gifter to select a day, but establish that the email will go out beginning of day in your business's timezone. By sending in time in UTC, you can tell Recurly what time beginning of day is in your timezone.

When the future send date comes, if the gift card's delivery method is "email", Recurly will send the Gift Card Delivery email to the recipient in the hourly window of the time provided. For example, at 6:00am, Recurly will kick off a batch of Gift Card Delivery emails to all gift cards scheduled for that day with a send time of 6:00:00am to 6:59:59am.

When editing a gift card that has a future delivery date, and when the future delivery date includes a time with minutes other than '00', the minutes are edited to '00' any time the edit form is saved even if that field wasn't touched.

Note that the gifter will get the Gift Card Purchase Confirmation at the time of the purchase event, but will not get another email when the Gift Card Delivery email goes out to the gift recipient.

Personal Message

Recurly supports two message fields with the gift card delivery information, personal message and gifter name. Personal message is a 255 character field where the gifter can write a personalized message for the recipient. This message will be used in the Gift Card Delivery email to the recipient. Gifter name is an optional field where you can collect a signature name for the gifter. For example, your gifter might want to be referenced as "Mom" with the gift, but her real name on her account is Sally Wilson. Gifter name will not be used in the Gift Card Delivery email unless you edit the email template to use the parameter.

Taxes

Gift card purchases are not taxed because they are essentially payment for future recipient purchases.

Discounts

We do not currently support discounts on gift card purchases. We are tracking customer interest for the ability to create a coupon that discounts a gift card purchase. Let us know if you would like this feature.

Fight Fraudulent Purchases

In order to block fraudulent purchases, Recurly does not allow a gift card to be purchased with another gift card credit. We recommend incorporating other fraud fighting tactics, like using our Kount integration and requiring more address information for the billing verification.

Purchase Confirmation

Upon a successful gift card purchase, the gifter will immediately receive the Gift Card Purchase Confirmation email, which will include details about the gift purchase, like the amount, personal message, and purchase invoice.

Find a Gift Card

In your Admin Console, you can find a gift card by knowing the redemption code, the account, or the purchase invoice number.

By Redemption Code

If you have a gift card's redemption code, you can search for it on the Gift Cards page under the Customers section. The Gift Cards table shows all purchased gift cards with the most recent at the top.

The left sidebar includes status filters to drill down to:

  • Not Yet Redeemed - The gift card has not been redeemed by the recipient and has not been canceled.
  • Redeemed - The gift card has been redeemed on a recipient account.
  • Has Balance Remaining - The gift card has been redeemed and still has a balance remaining.
  • No Balance Remaining - The gift card has been redeemed and the balance has been completely used up.
  • Canceled - The gift card has been canceled before it could be redeemed.

The Gift Cards page supports search by:

  • Redemption code
  • Gifter name, username, or account code
  • Recipient name, username, or account code
  • Delivery name, email, or address

The columns include:

  • Redemption Code - The current redemption code of the gift card, which links to the Gift Card Details page.
  • Gifter - The name, username, or account code of the gifter, which links to the gifter's account.
  • Recipient - The delivery name, account name, username, or account code of the recipient, which links to the recipient account if the gift card has been redeemed.
  • Purchase Date - The date the gift card was purchased by the gifter.
  • Amount - The value of the gift card.
  • Balance - The current balance of the gift card. Blank means the gift card has not been redeemed. A zero value means the gift card has been redeemed and the credit completely used up.

By Account

If you know the gift card's gifter or recipient, you can go directly to the customer's account and see a table for Gift Cards Purchased and Gift Cards Redeemed below the Coupon Redemptions table.

By Purchase Invoice

If you know the invoice number of the gift card purchase, you can search for the invoice on the Invoices page under Customers. On the Invoice Details page in the left sidebar called "Customer Info", you will see the gift card's redemption code, which links to the Gift Card Details page. This link does not exist on invoices where the gift card credit was applied as payment.

Refund a Gift Card Purchase

If you need to refund a gift card purchase, we recommend that you first block the associated credit from being used and then do a full refund to the gifter. Recurly will not automatically do this for you, so you will need to follow the steps below depending on the state of the gift card. We do not recommend refunding a gift card purchase if the gift card has been redeemed or issuing a partial refund, as your gift card balance and charges and credits will no longer be accurate for accounting purposes.

Gift Card Has Not Been Redeemed

  • Cancel the gift card in order to block the redemption.
  • Issue a full refund on the purchase invoice, which can be found on the Gift Card Details page.

Gift Card Has Been Redeemed

  • Find the remaining gift card credit on the recipient's account and delete it.
  • Issue a refund on the purchase invoice in the amount of the credit you deleted, which will either be the full amount or a remaining amount.
  • Note that deleting the credit will not decrease the gift card balance, so you will need to manually track that the gift card has been refunded.

Cancel a Gift Card

Canceling a gift card will make the associated redemption code inactive, blocking any redemption attempts. Once a gift card is canceled, it cannot be reactivated.

Canceling a gift card should be used if there is a fraudulent gift card purchase or if you are refunding a gift card purchase. A gift card can only be canceled if it has not yet been redeemed.

If you are refunding a gift card purchase, refund the invoice directly and Recurly will automatically cancel the gift card for you (not yet supported). If you are dealing with a fraudulent purchase or received a chargeback, you can cancel the gift card directly. In the case of the chargeback, you will not want to issue a refund in Recurly because the funds will have already been refunded outside of Recurly.

Canceling a gift card is offered via the Admin Console for your customer service reps. To cancel a gift card:

  1. Go to the account of the gifter and find the Gift Card Purchases table where you can find a link to the specific gift card.
  2. On the Gift Card Details page you will see a red button at the top right corner that says "Cancel Gift Card".
  1. Click "Cancel Gift Card" and confirm the action in the modal.

When a gift card is canceled, Recurly will show an activity for the cancelation on the gifter's account and will issue a canceled_gift_card_notification webhook.

Resolve Delivery Issues

With an online gift card program, there will always be recipients who experience delivery issues. To be able to manage these delivery issues, Recurly provide your customer service reps with Admin Console tools like editing delivery information, regenerating the redemption code, and resending the Gift Card Delivery email. All three options are available if the gift card has not yet been redeemed.

To find a gift card, you can:

  • Visit the Gift Cards index page under the Customers section of the Admin Console and search for the redemption code, gifter or recipient
  • Visit the gifter's account and find the Gift Card Purchases table listing the gift cards that account has purchased

Each gift card has it's own Gift Card Details page that links to both the gifter and recipient account, once the recipient has redeemed the gift card. On this page you can find the redemption status of the gift card, the delivery information, and the links to the below actions.

Edit Delivery Information

If the email address or physical address the gifter provided for the recipient was incorrect, you can log into the Recurly Admin Console and edit the gift card's delivery information before you resend the gift card to the recipient.

The following gift card delivery information fields are editable before the gift card is redeemed:

  • First Name
  • Last Name
  • Send Date
  • Email Address
  • Street Address
  • Address 2
  • City
  • State
  • Zip
  • Country
  • Phone Number
  • Gifter Name
  • Personal Message

Address Changes

If you are editing the email address, the new email address will be used if you resend the Gift Card Delivery email. If you edit the physical address, you are responsible for physically sending a new gift card to the recipient, or alerting your fulfillment team of the address change if the gift card has not yet gone out. To help with this, or if you are sending your own emails, Recurly will issue an updated_gift_card_notification webhook to alert you that the gift card delivery information has been changed. The webhook will include the updated delivery information, but will not specify which fields specifically have changed.

Send Date Changes

The future send date can only be edited if the send day is in the future. When edited, you will be able to select a day in the future up to a year out from the purchase date. You will also see a dropdown of hour send windows. Both the date and time will be in the timezone of your user profile.

Regenerate Redemption Code

If you believe the gift card redemption code may have been delivered to the wrong person, you can regenerate the redemption code before you resend the gift card details to the recipient. Regenerating the redemption code will make the previous code invalid if someone tries to redeem it. Regenerating the code will save you the hassle of having to refund and cancel the gift card and make the gifter purchase a new one.

To regenerate a gift card's redemption code, go to the Gift Card Details page in your Admin Console under Customers > Gift Cards > search for the gift card. There will be a "Regenerate Code" in the top right corner if the gift card has not yet been redeemed or canceled.

When a gift card's redemption code is regenerated, you will see an activity event on the account that records the previous redemption code and the new redemption code for future reference. Additionally, Recurly will send a regenerated_gift_card_notification webhook in case you need the new redemption code in another system in order to resend it to the recipient.

Resend Gift Card Delivery Email

After you have evaluated if you need to edit the delivery information or regenerate the redemption code, you can resend the Gift Card Delivery email to the recipient. The resend email option is available on the Gift Card Details page at the top right of the Delivery Information section if:

  • The gift card has not yet been redeemed
  • The gift card has not been canceled
  • The gift card delivery method was "email"
  • The gift card does not have a send date in the future
  • The Gift Card Delivery email template is currently enabled for your site

We do not allow you to resend the Gift Card Delivery email if the gift card has a send date in the future. If you would like to have the email go out sooner, edit the gift card to have the closest send date.

Redeem a Gift Card

Redeeming a gift card associates the recipient's account with the gift card in Recurly and creates a gift card credit on the recipient's account for the full purchased amount. A redemption code is no longer redeemable after the first redemption.

A gift card can be redeemed within a subscription sign-up or directly on an account. Redeem within a subscription sign-up for new customers or to push recipients into using their gift card credit right away. Redeem directly on an account for existing subscribers who want the gift card credit to apply to their next renewal.

Redemption Code

The gift card's redemption code is alphanumeric and is not case sensitive. While Recurly will display the code with capital letters, the customer can enter the code with capital or lowercase letters. It is important to note that Recurly's gift card redemption codes may include both "1" and "I", as well as "0" and "O". If your customer is struggling to redeem the code, you can always regenerate the code in your Admin Console and give them a new redemption code with different letters and numbers. Due to the possible confusion, we recommend displaying the redemption code in capital letters, which provides the most differentiation between letters like "i" and "l", which would be "I" and "L".

Taxes

Redeemed gift card credits will not calculate tax and will be applied to purchases after tax. If you are collecting taxes and not requiring a payment method from your redeemers; therefore, not requiring billing information, you will need to store the customer's taxable address in the account information address. Make sure your Tax Settings are set to "Use Account Information Address on all Invoices". That will make sure that your gift recipients are taxed using the account information address while those without an account information address are taxed base on their billing information address.

Discounts

Gift card credits can be applied to invoices that also have coupon discounts. Discounts are applied before credits. If the invoice total is zero after discounts, the gift card credit will not be applied to the invoice and will remain on the account for a future invoice.

Credit Balance

Once a gift card is redeemed, Recurly will start tracking the credit balance. Gift card balances can be viewed in the API, Gift Cards export or on the customer's account page in the Admin Console.

Billing Information

Some businesses feel that not requiring a credit card or other payment method at sign-up will increase the conversion of the gift recipient redeeming the gift card and using the service or product. In contrast, some businesses feel that requiring a credit card up front, while it may deter some gift card redemptions, will ultimately increase the chance of the gift recipient converting to a paying customer when the credit card is processed at their first renewal requiring payment. Whichever experience is best for your business, you have the option to require or not require billing information from gift card redeemers when their gift card credit covers the full amount of the subscription sign-up.

By default, Recurly requires a payment method for all subscription sign-ups that are not using manual invoicing. For Recurly, this means requiring "billing information" on the customer's account. To change this to not require a payment method from your gift card redeemers, go to the Gift Cards page under Configuration and change the right sidebar setting, "Require Billing Information?", to "Not Required".

If you are using the Hosted Pages

If you are using the Hosted Pages and collecting taxes, you will need to require billing information in order collect billing address.

When Billing Information Is Not Required

If your Gift Card "Require Billing Information?" setting is set to "Not Required", a gift recipient redeeming a gift card will not be required to provide billing information if the subscription started as a gift and the invoice cost after credits is $0.00.

How a Subscription Starts with a Gift

To provide businesses with better metrics around gift subscriptions, as well as a way to determine when billing information should not be required, Recurly tracks when a subscription is started with a gift card. This data point will soon be available to merchants in the Subscriptions export.

A subscription is determined to have started with a gift if:

  • The first subscription invoice was paid with at least one gift card credit
  • Or a gift card redemption code was redeemed in the subscription sign-up

If the first subscription invoice was a $0.00 trial invoice, then the first renewal invoice would be where we look for at least one gift card credit to determine if the subscription qualifies as starting with a gift.

Free Trials

Recurly requires billing information for free trial sign-ups, unless the subscription falls into the gift card scenario above. In order to not require billing information at a free trial sign-up, we must be able to determine that the subscription started with a gift. Since most free trial invoices are $0.00 before credits, except when a set-up fee is included, the trial invoice will, in most cases, not attempt to use any gift card credits on the account. This means the only way to identify the subscription as started with a gift and not require billing information at the trial sign-up is to have the customer redeem a gift card redemption code in the sign-up.

If you collect billing information from the customer at a trial sign-up and the first payment invoice is paid with a gift card credit, Recurly will record that the subscription started with a gift, so you can track the subscription as a gift subscription.

Converting Gift Subscriptions to Paying Subscriptions

Whether you are requiring billing information or not, Recurly will record when a subscription that started with a gift has converted to a normal paying subscription. A subscription that started with a gift converts when the subscription has it's first successful payment transaction. This "converted at" time will soon be available in your Subscriptions export so you can filter to all subscriptions that started with a gift and see how quickly they converted compared to their creation date.

Renewals

For those customers who did not provide billing information at the time of sign-up, you will need to encourage them to add billing information before a subscription renewal where additional payment is due, past their gift card credit or any other credits on their account. If a customer's subscription started with a gift and a renewal requires additional payment, Recurly will attempt to collect payment from the billing information on the account. If the customer is still missing billing information, the subscription will be expired at the renewal and an email will be sent to the customer.

To avoid subscription churn and encourage paid customer conversions, Recurly will soon have an automated email that will go out to the gift recipient 7 days before a renewal where we know the customer cannot currently cover the cost with credit on the account. The email will encourage the customer to add a payment method to their account in order to continue their subscription.

Upgrades

If a customer attempts to upgrade their subscription that started with a gift, Recurly will attempt to pay the upgrade cost with the billing information on the account. If the customer is still missing billing information, the upgrade request will be blocked with an error asking the customer to add a payment method to their account to complete the change.

Refund a Gift Card Redemption

When a gift card is redeemed, it becomes credit on the customer's account that is used for purchasing your plans or products. If you issue a refund of a subscription purchase that was paid with gift card credit, the gift card credit will be returned to the customer's account, but the credit will no longer be considered a gift card credit and will not be linked to the associated gift card or increase that gift card's balance.

We handle gift card credit refunds this way because Recurly today treats refunded credit as general credit, with no association to past credits or charges. Because Recurly's Gift Cards are not reloadable, once the customer uses the gift card as payment on an invoice, we consider the gift obligation met and any refunded gift credit is general credit for a future invoice.

Emails

Recurly's Gift Cards support four email notifications to either the gifter or the recipient. All four email templates are enabled by default and can be configured on the Email Templates page in the Admin Console. To customize your gift card email templates, see our Gift Card Email Parameters.

Gift Card Purchase Confirmation

The Gift Card Purchase Confirmation email is a receipt for the gifter to confirm their purchase and the delivery details they provided at checkout. The email goes to the gifter immediately upon a successful gift card purchase.

Gift Card Delivery

The Gift Card Delivery email is the e-gift card that provides the recipient with the redemption code. The email goes to the recipient email address provided by the gifter at the time of the gift card purchase. This email is sent immediately after a successful gift card purchase where the delivery method is email and the email template is enabled in your Admin Console.

Soon we will be adding the ability to let the gifter select a future delivery date. Great for early shoppers.

Gift Card Balance Low

For gift card recipients that subscribed without a payment method, the Gift Card Balance Low email attempts to convert the recipient to a paying subscriber by encouraging them to provide a payment method when then gift card balance is about to be used up. This email goes to the email address on the recipient's account 7 days before a subscription renewal where they will owe additional money and:

  • The account does not have billing information
  • The subscription started with a gift card
  • The subscription has not yet converted, meaning there has never been a successful transaction associated with the subscription

We have two email parameters you can use in subscription emails to add additional messaging to gift subscription customers encouraging them to add their payment method. For example, the New Subscription email or the Renewal Reminder email. See the last two gift card parameters here.

Gift Card Redemption Reminder

For gift card recipients who haven't redeemed their delivered gift card, the Gift Card Redemption Reminder email reminds them to redeem their gift card in order to increase the chance of redemption and use. This email goes to the email address on the recipient's account one calendar month from the delivered_at date. This email will only go out if the delivery method was email and the Gift Card Delivery email was sent out. This email will not go out if the delivery method was post or if the Gift Card Delivery template was disabled during the original delivery, since Recurly will not know when the delivery occurred.

We do not allow you to set when the email goes out and we only send one email. If you resend the Gift Card Delivery email after the Gift Card Redemption Reminder email has gone out, the delivered_at date will be updated and the Gift Card Redemption Reminder will be queued up again to go out a month later if the gift card has not yet been redeemed.

Exports

The Gift Cards feature has a new export called "Gift Cards" and will create new data in some of our existing exports.

Gift Cards Export

The Gift Cards export includes a row for every purchased gift card on your site. Here you can see what gift card amounts are most popular, who is purchasing the most gift cards, who is redeeming gift cards, and what gift cards haven't been redeemed or still have remaining balances.

View documentation on the Gift Cards export.

Subscriptions Export

The Subscriptions export includes two columns specific to the Gift Cards feature that help you track subscriptions that started with a gift card and when they converted to a paying customer.

Name
Example
Description

started_with_gift

TRUE, FALSE

TRUE if the subscription was started with a gift card, whether or not billing information was collected.

converted_at

2016-09-02 15:53:18 UTC

Date of the first successful transaction for the subscription. Can only have a value if started_with_gift is TRUE. converted_at compared to the subscription's activated_at will give you the time to conversion.

Subscriptions - Churned Export

The Subscriptions - Churned export includes two columns specific to the Gift Cards feature that help you track subscriptions that started with a gift card and when they converted to a paying customer before expiring, or if they never converted and expired at the end of the gift.

Name
Example
Description

started_with_gift

TRUE, FALSE

TRUE if the subscription was started with a gift card, whether or not billing information was collected.

converted_at

2016-09-02 15:53:18 UTC

Date of the first successful transaction for the subscription. Can only have a value if started_with_gift is TRUE. converted_at compared to the subscription's activated_at will give you the time to conversion.

Webhooks

Recurly's Gift Cards can issue six possible notification events:

  • Purchased
  • Canceled
  • Updated
  • Regenerated
  • Redeemed
  • Updated Balance

See details of each gift card notification in our Webhooks documentation.

API

Gift cards can be purchased and redeemed using our API with at least version 2.4.

Recurly.js

Purchase Gift Card

There are no new Recurly.js updates for gift card purchases. Since a gift card purchase cannot be discounted or taxed, the cost to the gifter is the same as the gift card amount, so the Pricing feature of Recurly.js is not needed. You can still securely collect payment details using the Recurly.js token.

Redeem Gift Card

Recurly.js Pricing has been updated to support previews of a gift card credit applied to a new subscription. See Recurly.js Pricing.

Hosted Pages

Gift Card Hosted Payment Page Configurations
The settings for your hosted gift card purchase page are controlled by your hosted page settings. There are three optional payment form fields which will not apply to the gift card purchase page, if selected. These fields are: Editable Quantities, Coupon Codes, and Gift Card Code. Since customers are only allowed to purchase one gift card at a time, an Editable Quantities field will not be an option on the gift card purchase page. Additionally, coupon and gift card redemption for a gift card purchases are not allowed, therefore they will not be displayed.

Gift Card Hosted Payment Page
Recurly offers the ability for your customers to purchase a gift card on the Hosted Payment Pages. This is a new hosted page for gift card purchases. Customers can delivery a gift card using email address as the delivery method. Coupon and gift card redemption are not allowed when purchasing a gift card.

Gift card redemption on Plan Hosted Payment Page
You can allow gift card redemption on the Plan Hosted Payment Pages. If you do not require billing information for gift card redemption, we will still show billing information fields on the gift card purchase page. We will be improving this experience soon.

Hosted Account Management
Existing customers are able to redeem a gift card on Hosted Account Management. Customers can find their gift card purchase history by looking at their invoice history.

Multicurrency Support

Recurly's Gift Cards support multiple currencies. If you are using the Multicurrency feature, you can define a list of preset gift card amounts for each currency. You do not have to define amounts for each of your supported currencies, and each currency can have it's own number of amounts. For example you could have three USD amounts and two EUR amounts.

It is important to note that a gift card can only be redeemed on a subscription that is the same currency as the purchase amount. For example, if a gift card is $10.00 USD, it can only be redeemed on a subscription that also has USD as the currency. The gift card cannot be redeemed on a EUR or other currency subscription.

InComm and Other 3rd Party Gift Cards

You can use another system to generate and sell gift cards and then redeem the corresponding gift credit in Recurly to apply to a subscription purchase. For example, if you want to sell physical gift cards in stores like Walmart and Best Buy, you can establish a relationship with a gift card vendor like InComm.

Gift Card Purchase

When using a third party, like InComm, to generate and sell gift cards, the purchase event is outside of Recurly. You can of course use Recurly's custom adjustments to run a third party gift card purchase through Recurly, but it is important to note that this will not be related to the gift card product you can create in Recurly for Recurly's Gift Cards, and will not create a purchased gift card in Recurly. The only record you will see in Recurly is the invoice and adjustment for the purchase.

Gift Card Redemption

Your third party vendor will probably have a way to redeem the gift card in their system. Once you confirm the gift card is valid to redeem, you can create a corresponding credit in Recurly for the same amount. We recommend that you set the origin of the credit to external_gift_card. This will allow you to use Recurly's feature to not require billing information on a gift subscription purchase if nothing is due from the customer at sign-up. You can only create an external_gift_card credit through the Adjustments API right now. This feature is not supported in the Admin Console UI.

To create an external_gift_card credit, see our Adjustment API documentation:

  • Set the currency to the currency of the gift card.
  • Set the unit_amount_in_cents to the amount of the gift card (must be negative to make a credit).
  • Set the quantity to 1.
  • Set the description to the customer facing line item description. You may want to expose the redemption code here.
  • Set the accounting_code to the internal identifier. This might be an actual accounting code or a way for you to identify the InComm gift card this credit is for.
  • Set the origin to external_gift_card

In order to use the gift card credit on the subscription sign-up, you will need to create the credit before you create the subscription. This unfortunately means that you will not be able to use the all-in-one Create Subscription API call that creates the account and subscription and rolls it all back if anything fails. Instead you will need to create the account, the credit, then the subscription. This means three API calls.

We recommend following these steps:

  1. Check that the gift card is valid with the third party gift card vendor.
  2. When you are ready, redeem the gift card with the third party gift card vendor.
  3. If redemption with the third party vendor fails, or the gift card is invalid, throw an error.
  4. If the redemption with the third party vendor is successful, then fire off the calls to create the account and external_gift_card credit in Recurly.
  5. If the account and credit creation in Recurly fails, you can either expose an error or leave it as a customer service issue to clean up later.
  6. Finally, create the subscription on the account in Recurly.
  7. If creating the subscription fails due to needing a credit card or other reason, the account and credit will at least be in the system. This is important because you want the gift card redeemed and in Recurly as soon as possible so that the gift card does not get lost in a desk drawer and is closer to being used on a purchase.

Billing Information Requirement

If you do not want to require billing information (credit card) from customers redeeming a third party gift card when nothing is due from them at sign-up, you can do so by changing the "Require Billing Information?" setting on the Gift Card Settings page under Configuration. The full feature functionality is detailed here.

There are four requirements to bypass the billing information requirement for gift subscriptions:

  1. The "Require Billing Information?" setting on the Gift Card Settings page must be set to "Not Required".
  2. The invoice total must be zero dollars, so no additional amount it due from the customer.
  3. The invoice must contain a gift credit that has an origin of "gift_card" (generated by the Recurly Gift Cards feature), or "external_gift_card".
  4. Or if condition 3 is not met, the create subscription action must include a gift card redemption code.

Condition 4 does not apply to third part gift cards, only Recurly Gift Cards, because there is no gift card redemption code redeemed in Recurly for third party gift cards, just a special credit. This means the only way to bypass the billing information requirement is condition 3, to have the external_gift_card credit picked up on the first invoice. This will only happen if the charges on the invoice are greater than zero. If the charges are zero dollars or fully discounted, the external_gift_card credit will not be applied. Therefore, a third party gift card redeemed when subscribing to a free trial will always require the customer to provide billing information. Due to this limitation, Recurly recommends that you don't allow free trials for gift card redeemers. You can either subscribe gift card redeemers to a plan without a trial or set the trial_ends_at to timenow in the request to remove the default trial.

Using Recurly and a 3rd Party Vendor Together

If you want to use Recurly for online gift card purchases and a third party gift card vendor for brick-and-mortar physical gift card purchases, you will have two systems generating unique gift card redemption codes. To avoid duplicates, we recommend that you adjust your Recurly redemption code length to be different than your third party gift card vendor. For example, InComm gift cards are usually 16 to 19 characters. Recurly gift cards are 16 characters by default. If you want to use InComm and Recurly together, you could adjust your Recurly gift cards to have a length of 15 or 20 characters.

To change your Recurly gift card redemption code length, contact Recurly Support and tell us the length you want and the Recurly site subdomain you want it on. Right now we only support 15, 16, 17, 18, 19, or 20 characters. When the length is changed, it will affect new Recurly Gift Card purchases moving forward. Any previously purchased Recurly Gift Cards will maintain their original length.

Gift Card Balance

If you would like to show your customers their gift card balance, you can use our API to check their account for uninvoiced external_gift_card credits and sum the amount. We do not have query parameters to help you filter the adjustments list returned, but you can do the following on your side.

  • Use the List Account's Adjustments API call.
  • Filter for origin = external_gift_card.
  • Filter for status = pending.
  • Sum the unit_amount_in_cents to get the balance total.

The external_gift_card origin is also exposed in the Invoices - Line Items export, so your finance team can track unused balances by identifying all adjustments with a status of "pending".