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    

Coupons Exports

Recurly offers 3 exports relevant to coupons: Coupons, Coupon Redemptions and Coupons- Bulk Unique Coupons

Coupons

This export lists all the coupons that have been created on the site. If you have a fixed amount discount coupon with multiple currencies, you will see a row for each currency of the coupon.

Time Range Filter

Created

Coupons that were created during the selected time range.

Modified

Coupons that were modified during the selected time range. A coupon is modified when its redemption_count increases, if it reaches its max_redemptions or is expired early (as reflected in the deactivated_at column)

Export Contents

Column Name
Example
Description

id

1313528357303980000

The unique identifier for a coupon code.

coupon_code

5off

The code the customer enters to redeem the coupon.

name

5% Off

The Internal Name for the coupon.

discount

5

The fixed amount discount. The amount's currency is reflected in the currency column. This value will remain 0 if the coupon has a percentage discount.

currency

USD

The currency of the fixed amount discount. This value will be empty if the coupon has a percentage discount.

discount_percent

5

The percentage discount. This value will be empty if the coupon has a fixed amount discount.

redeem_by_date

2015-10-10 11:59:59 PST

The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59 end of day pacific time.

redemptions_count

7

The number of times the coupon has been redeemed.

max_redemptions

100

The maximum number of times the coupon can be redeemed.

applies_to_plans

all plans

The plans redemptions of the coupon can discount on customer invoices.

timeframe

forever

The duration of the coupon.

created_at

2012-01-02 06:20:41 PST

The date and time the coupon was created. Used for created date range filter.

deactivated_at

2013-02-02 06:20:41 PST

The date and time the coupon was expired early or reached its max_redemptions.

modified

2012-01-02 06:20:41 PST

The date and time the coupon was last modified, which can be an increase in redemptions or deactivated_at action. Used for modified date range filter.

applies_to_non_plan_charges

TRUE

Whether redemptions of the coupon can discount one-time charges on customer invoices.

redemptions_per_account

1

The number of times a single account can redeem the coupon. If empty, the redemptions per account are set to "unlimited".

redemption_resource

account, subscription

This is the discount level of the coupon. Subscription requires the redemption to have a subscription_id associated with it.

coupon_type

single code, bulk

The type of coupon, which can be a single code coupon or a bulk coupon that has multiple unique codes.

discount_type

percent, fixed_amount, free_trial

Whether the coupon is a percent off, amount off, or custom trial

free_trial_coupon_amount

14

If the discount_type is "free_trial", the number associated with the unit period (e.g. - 14 days would have "14" here)

free_trial_coupon_unit

day, week, month

If the discount_type is "free_trial", the period associated with the amount (e.g. - 14 days would have "day" here)

Coupon Redemptions

This export lists all account redemptions of coupons on your site. The time range reflects the date the redemption was created, which is the 'applied_at' column in the export. There currently isn't a way to filter this export by a specific coupon before downloading the csv.

Export Contents

Column Name
Example
Description

coupon_code

5off

The code the customer entered to redeem the coupon.

account_code

123456789, janedoe@gmail.com

The account code for the account the coupon code was redeemed on.

discount

5

The fixed amount discount rule for the coupon. The currency of the discount is reflected in the currency column. This value will remain 0 if the coupon was a percentage discount coupon.

discount_percent

5

The percentage discount rule for the coupon. This value will be 0 if the coupon was a fixed amount discount coupon.

total_discount

100.50

The total amount discounted on the account to date from the coupon redemption.

applied_at

2013-01-02 06:21:14 PST

The date and time the coupon was redeemed on the account. Used for date range filter.

expires_at

2014-01-02 06:21:14 PST

The date and time the redemption naturally expires on the account after its duration length.

timeframe

forever

The duration of the coupon.

uuid

306f7937d86f088f046dd945a1a24df2

The unique id for the coupon redemption.

currency

USD

The currency of the total_discount and discount column.

coupon_id

1313528357303980000

The unique identifier for the coupon associated with the redemption. Useful for joining data from the Coupons export.

subscription_id

306f7937d86f088f046dd945a1a24df2

The uuid of the subscription tied to the redemption on a customer's account. This value will only exist if the coupon was subscription-level.

coupon_type

single code, bulk

The type of coupon, which can be a single code coupon or a bulk coupon that has multiple unique codes.

discount_type

percent, fixed_amount, free_trial

Whether the coupon is a percent off, amount off, or custom trial

free_trial_coupon_amount

14

If the discount_type is "free_trial", the number associated with the unit period (e.g. - 14 days would have "14" here)

free_trial_coupon_unit

day, week, month

If the discount_type is "free_trial", the period associated with the amount (e.g. - 14 days would have "day" here)

Coupons - Bulk Unique Codes

The Coupons - Bulk Unique Codes export allows you to export all unique codes for a specific bulk coupon and see redemption information about each code. This export will only appear on the Exports page if you have created a bulk coupon on your site. Learn more about Bulk Unique Coupons.

Filters

Select the bulk coupon you want to export unique codes from the dropdown. The dropdown displays the internal name of the coupon, followed by the prefix of the codes in parentheses. The dropdown list is sorted by internal name in alphabetical order.

Time Range Filter

Created

Sets the date range to the date the unique code was created, which is the 'created_at' column in the export. Use "All Time" with Created to see the full list of your unique codes. If you added more codes to the bulk coupon throughout the campaign you can filter the dates down to the period in which you created a subset of codes.

Modified

Sets the date range to the last date the unique code was modified, which is the 'modified_at' column in the export. A unique code is modified when it is redeemed (applied_at) or expired early (deactivated_at). expired_at is not a modifying event.

Export Contents

Column Name
Example
Description

bulk_coupon_id

769158967603640335

uuid of the bulk coupon campaign, which is the id in the Coupons export.

bulk_coupon_prefix

save

The prefix of all unique codes, which is the coupon_code of the bulk coupon in the Coupons export.

unique_coupon_code

save-012478

Unique code for the bulk coupon. This value will be the coupon_code in the Coupon Redemptions export, reflecting what the customer entered at redemption.

discount

5

The fixed amount discount rule for the coupon. This value will only show after the unique code has been redeemed and the currency column will reflect the currency of the amount. This value will remain 0 if the coupon was a percentage discount coupon. If you see a 0 in the discount_percent column, you know the coupon discount is a fixed amount discount.

discount_percent

5

The percentage discount rule for the coupon. This value will always show, even if the unique code has not been redeemed. This value will be 0 if the coupon was a fixed amount discount coupon.

timeframe

forever

The duration of the coupon.

redeem_by_date

2015-10-10 11:59:59 PST

The date and time the unique code will expire and can no longer be redeemed. Time is always 11:59:59 end of day pacific time.

created_at

2015-09-07 19:23:03 PST

The date and time the unique code was created.

modified_at

2015-09-07 19:23:03 PST

The date and time the unique code was redeemed (applied_at) or expired early (deactivated_at).

deactivated_at

015-09-07 19:23:03 PST

The date and time the unique code was expired early, if applicable.

applied_at

2013-01-02 06:21:14 PST

The date and time the unique code was redeemed on an account.

expires_at

2014-01-02 06:21:14 PST

The date and time the unique code naturally expires on the account after its duration length.

redemption_uuid

306f7937d86f088f046dd945a1a24df2

The unique id for the unique code's redemption.

account_code

306f7937d86f088f046dd945a1a24df2

The unique id for the unique code's redemption.

subscription_id

306f7937d86f088f046dd945a1a24df2

The uuid of the subscription tied to the unique code redemption on a customer's account. This value will only exist if the coupon was subscription-level and the unique codes has been redeemed.

total_discount

100.50

The total amount discounted on the account to date from the unique code redemption.

currency

USD

The currency of the total_discount and discount column.

discount_type

percent, fixed_amount, free_trial

Whether the coupon is a percent off, amount off, or custom trial

free_trial_coupon_amount

14

If the discount_type is "free_trial", the number associated with the unit period (e.g. - 14 days would have "14" here)

free_trial_coupon_unit

day, week, month

If the discount_type is "free_trial", the period associated with the amount (e.g. - 14 days would have "day" here)

Coupons Exports


Suggested Edits are limited on API Reference Pages

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