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    

Bulk Unique Coupons

Bulk Unique Coupons allow you to create one coupon campaign with many unique codes.

Feature Overview

  • Use Recurly's bulk unique code generator to create thousands of unique codes
  • Target segments by sharing a unique coupon code with specific customers through email
  • Report on unique code redemptions and discounts grouped under one coupon campaign
  • Track which marketing methods resulted in the most coupon redemptions by comparing which unique codes where shared in each method

Create a Bulk Coupon

To create a bulk coupon in the Recurly UI, go to your Coupons dashboard, select New Coupon, and select Bulk unique codes as your code type. Refer to our Create a Coupon instructions for details on all coupon options. These are the bulk unique code fields you will need to fill out:

Total Number of Codes

Select the number of unique codes you would like for the campaign.

  • You must select at least 1 and no more than 100,000.
  • After the bulk coupon is created, you have the option to add more unique codes, up to 100,000 for the bulk coupon.

Required Prefix

Specify a prefix that will be the same across all unique codes.

  • The prefix is the coupon code for the campaign as a whole.
  • It must be unique across all redeemable coupons on your site.
  • The prefix can be alphanumeric and may include a dash (-), underscore (_), or a plus sign (+).

Generated Code Format

Specify the format of the dynamically generated portion of the code.

  • This is the unique portion of the code.
  • Format can be alphabetic, alphanumeric, or numeric.

Generated Code length

Specify the character length of the dynamically generated portion of the code.

  • This is the unique portion of the code.
  • Length does not include the prefix or optional suffix.
  • Length must be at least 4 characters for alphabetic and alphanumeric formats, and 6 characters for numeric.
  • Length cannot be longer than 50 characters.

Optional Suffix

You can choose to include a suffix at the end of each unique code. The suffix isn't dynamic and will remain across all unique codes.

  • The suffix can be alphanumeric and may include a dash (-), underscore (_), or a plus sign (+).

Unique Code Preview

The preview will show you a sample generated unique code reflecting your template choices. Note that the prefix and suffix are always separated from the dynamically generated portion with dashes. Your customers will need to enter the entire code, with dashes, at redemption. If you would like a different unique code template, or do not want to include dashes, you can design your own template through the API.

Maximum Redemptions

Maximum redemptions will not show as an option in the Recurly UI when you select the "Bulk unique codes" option. By default, maximum redemptions are set to unlimited in order to allow your number of unique codes to be the limiting factor in redemptions. If you would like to set a maximum redemptions for your bulk coupon, you can do so through the API. If you set a maximum redemptions that is less than the number of unique codes generating, you are saying that not all unique codes can be redeemed, only those redeemed until the maximum redemptions are reached for the coupon.

Redemptions Per Account

Redemptions per account will not show as an option in the Recurly UI when you select the "Bulk unique codes" option. By default, redemptions per account are set to "1". A unique code can only ever be redeemed once. If you want a customer to take part in the campaign more than once, you could set the redemptions per account to a number greater than one. This would allow a customer to redeem more than one unique code on their account. You can set redemptions per account to a number other than "1" through the API.

Fill out the rest of your coupon details and click Create Coupon. You will be taken to the Coupons dashboard and will see an alert that your unique codes are being generated. If you requested a large number of codes you may need to wait a minute or two. Go ahead and refresh the page and you will find your new coupon at the top of the Redeemable Coupons table. Click on the coupon's Internal Name or the View Codes link to visit the coupon's details page and see all of your unique codes and their redemption status.

Export Your Unique Codes

To export a full list of your unique codes, click the Export button at the top right of the bulk coupon's Coupon Overview page. This will take you to the Exports page under Configuration and will automatically select the Coupons - Bulk Unique Codes export, the internal name of your bulk coupon from the dropdown, and the All Time time range. Click the "Download CSV File". The export will show you all of your unique codes and their redemption information.

  • Export on "Created" will show unique codes created in the date range. Filter to a specific date range to isolate unique codes added to the campaign at a specific time.
  • Export on "Modified" will show unique codes created, redeemed, or manually expired in the date range.

How to report on unique code redemptions within a specific time range

This export will list all unique codes for the bulk coupon that were redeemed within the time range, who redeemed the code, when, and how much the code has discounted the account to date.

  1. Use the Coupons - Bulk Unique Codes export and select your bulk coupon from the dropdown.
  2. Set Export on to "Modified".
  3. Set Time Range to the date range you want.
  4. Download the CSV
  5. Filter out all rows that don't have a value in applied_at
  6. Sort the applied_at date and remove any rows where the date is outside of your time range. These rows mean the unique code was manually expired in the time range.

Expire Bulk Coupon or Unique Codes

Expiring a bulk coupon will expire all unique codes in the campaign that have not yet been redeemed. Expired means the unique codes are no longer redeemable. You can also expire specific unique codes in a campaign if you find you no longer want those specific unique codes to be redeemed.

Invoice

The invoice Discounts Applied notes will show the unique code redeemed with the invoice description of the coupon campaign.

Exports

Coupons

The Coupons export will answer which coupons are bulk unique coupon campaigns.

  • Look for the "coupon_type" column. Regular single code coupons will have a type of "single code" and bulk unique coupons will have a type of "bulk".
  • If you see a coupon_type of bulk, you will be able to export all unique codes for that bulk unique coupon in the Coupons - Bulk Unique Codes export.

See the details of this export in our Coupons export documentation.

Coupon Redemptions

The Coupon Redemptions export will answer which bulk unique codes have been redeemed and who they were redeemed by.

  • coupon_code will show the unique code redeemed
  • coupon_type will be "bulk" for a unique code and "single code" for a regular one code coupon

See the details of this export in our Coupon Redemptions export documentation.

Coupons - Bulk Unique Codes

The Coupons - Bulk Unique Codes export will provide a full list of all unique codes for a bulk coupon, as well as the redemption information for any unique codes that have been redeemed. You can access this export from the Coupon Overview page by clicking "Export" at the top right of the page.

See the details of this export in our Coupons - Bulk Unique Codes documentation.

Updated 8 months ago

Bulk Unique Coupons


Bulk Unique Coupons allow you to create one coupon campaign with many unique codes.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.