{"__v":26,"_id":"5665e0c7d8a06b170063f311","category":{"__v":29,"_id":"5665dfa0e93ae70d00b96a2a","pages":["5665dfca1b6559190020ae7d","5665e000e93ae70d00b96a2c","5665e0a9e93ae70d00b96a32","5665e0c7d8a06b170063f311","5665e12bd7490819006a503f","5665e1431b6559190020ae86","5665e16f63109d0d0036ba19","5665e192b6c0f60d00eae53d","5665e29ed8a06b170063f315","5665e2b9d7490819006a5044","566630b03360850d00336cb6","566631547cc81e0d00253f1a","566631b38744940d004c3eff","5666328b2342100d007dcbf7","566729ab5d00370d00ede6c2","56672a86f672550d0008523a","56672fd9ee53940d00516267","5667335f5d00370d00ede6db","566735cf6819320d000c2f05","5667362b32dd550d00f3924b","5667373d6819320d000c2f0a","566737c232dd550d00f3924e","5667380ad784a70d00397ce1","56673ee86819320d000c2f1b","56673f95ee53940d0051629d","56673feed784a70d00397cec","5667431e66debc1700503f6a","5667436d66debc1700503f6d","566745066819320d000c2f3d"],"project":"56450a342229d7170010928a","version":"56450a342229d7170010928d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-07T19:36:00.783Z","from_sync":false,"order":2,"slug":"configuration","title":"Configuration"},"parentDoc":null,"project":"56450a342229d7170010928a","user":"55648cf93b87582b003ab8b1","version":{"__v":9,"_id":"56450a342229d7170010928d","project":"56450a342229d7170010928a","createdAt":"2015-11-12T21:52:52.685Z","releaseDate":"2015-11-12T21:52:52.684Z","categories":["56450a352229d7170010928e","56450a472c74cf1900da48ca","565def2677f0090d005819bb","5665dfa0e93ae70d00b96a2a","5665e3db1b6559190020ae8c","5665e47763109d0d0036ba5a","5690123f18c3920d00be8b1c","56944016d8c04d1700e5ae20","569447891005590d0062cace"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"createdAt":"2015-12-07T19:40:55.128Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"## What's New!\nWe recently released a ton of new coupon options. Select a feature below to learn more:\n* <a href=\"/docs/multiple-coupons-per-account\">Multiple Coupons Per Account</a>\n* <a href=\"/docs/bulk-unique-coupons\">Bulk Unique Coupons</a>\n* <a href=\"#section-eligible-charges\">Coupons for One-Time Charges</a>\n* <a href=\"#section-redemptions-per-account\">Limit Redemptions Per Account</a>\n* <a href=\"#section-discount-level\">Subcription-Level Discounts</a>\n* <a href=\"#section-edit-a-coupon\">Edit a Coupon</a>\n* <a href=\"#section-restore-a-coupon\">Restore a Coupon</a>\n* <a href=\"#section-free-trial-coupons\">Free Trial Coupons</a>\n\n\n## Table of Contents\n* <a href=\"#section-features-overview\">Features Overview</a>\n* <a href=\"#section-coupon-accounting\">Coupon Accounting</a>\n* <a href=\"#section-coupons-dashboard\">Coupons Dashboard</a>\n* <a href=\"#section-coupon-settings\">Coupon Settings</a>\n* <a href=\"#section-coupon-overview\">Coupon Overview</a>\n* <a href=\"#section-create-a-coupon\">Create a Coupon</a>\n* <a href=\"#section-redeem-a-coupon\">Redeem a Coupon</a>\n* <a href=\"#section-remove-a-redemption\">Remove a Redemption</a>\n* <a href=\"#section-edit-a-coupon\">Edit a Coupon</a>\n* <a href=\"#section-expire-a-coupon\">Expire a Coupon</a>\n* <a href=\"#section-restore-a-coupon\">Restore a Coupon</a>\n* <a href=\"#section-coupon-and-discount-exports\">Coupon and Discount Exports</a>\n* <a href=\"#section-coupon-examples\">Coupon Examples</a>\n\n## Features Overview\n* Single code coupons for mass distribution with the option to limit maximum redemptions and or set a specific redeem by date\n* Bulk unique codes for individual delivery and tracking\n* Discounts at the account level or tied to specific subscriptions\n* Coupons that discount one-time non-subscription charges\n* Percentage discounts or fixed amount discounts in multiple currencies for one coupon\n* Free trial coupons to give new subscriptions special free trial lengths\n* Offer your discount for one purchase, a limited time, or forever\n* Set how many times a customer can redeem a specific coupon\n* Limit customers to one active coupon, or allow multiple coupons on their account and purchases\n* Ability to edit, expire, and restore coupon campaigns\n\n## Coupon Accounting\nPercentage 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.\n\nPercentage 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.\n\nFree 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.\n\n### Percentage Discounts\nPercentage discounts will apply the same percentage to each eligible charge on the invoice. <strong>Percentage discounts will never discount a plan setup fee.</strong> 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.\n\n<strong>Percentage Discount Example</strong>\nCoupon 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:\n* Plan A - Setup fee of $50.00 will not be discounted\n* Plan A - Plan fee of $15.00 will be discounted 10% for a discount total of ($1.50)\n* Plan A - Add-on of $7.00 will be discounted 10% for a discount total of ($0.70)\n* The total discount on the invoice is ($2.20)\n* The customer pays $69.80\n\n### Fixed Amount Discounts\nFixed amount discounts will apply the specified amount across all eligible charges on the invoice, starting with the first subscription line item.\n* 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.\n* 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.\n* 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.\n\n<strong>Fixed Amount Discount Example</strong>\nCoupon 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:\n* Plan A - Plan fee of $15.00 will get a full discount of ($15.00)\n* 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\n* The total discount on the invoice is ($20.00)\n* The customer pays $2.00\n\n### Multiple Discounts on an Invoice\nMerchants 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 <a href=\"/docs/multiple-coupons-per-account\">Multiple Coupons Per Account</a> feature.\n\n###Free Trial Coupons\n\nFree trial coupons can be used to give new subscriptions different free trial lengths. This is useful to merchants that offer a plan that includes a 1 week free trial, and wants to test how conversion changes when new subscriptions come with that 1 month free trial. 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. \n\nFree 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). \n\nFree trial coupons can also 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.\n\n###A few additional details about free trial coupons: \n\n* They must be redeemed when a customer is creating a new subscription\n* 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\n* 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\n* The free trial invoice line items will correctly display the length of the free trial associated with the coupon\n* The coupon exports include information about the free trial length associated with the coupon and the redemptions\n* Merchants can create free trial coupons as either single use or bulk coupons \n\n\n## Coupons Dashboard\nThe 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. <a href=\"https://app.recurly.com/go/coupons\">Visit the Coupons dashboard in your Recurly site.</a>\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bWQiluBgRVyXu3cK0F9r_coupon-dashboard.png\",\n        \"coupon-dashboard.png\",\n        \"958\",\n        \"510\",\n        \"#55646d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Search\nUse the search bar to quickly find a specific coupon in either the Redeemable or Expired Coupons table. Here are the fields you can search:\n* Internal Name\n* Code\n* Plan Name\n* Plan Code\n* Fixed Amount (e.g. - $10.00 USD can be searched as \"10\")\n* Percentage (e.g. - 50% can be searched as \"50\")\n\n### Redeemable Coupons\nThis table on the Coupons dashboard lists all coupons that can currently be redeemed by customers. Redeemable coupons can be edited or expired early.\n\n### Expired Coupons\nThis 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.\n\nCoupons will expire if:\n* The Maximum Redemptions for the coupon has been reached.\n* The Redeem By Date for the coupon has been reached.\n* There are no remaining unique codes for a bulk coupon.\n\n## Coupon Settings\nOn the Coupons dashboard you will see a button at the top right called <strong>Settings</strong>. On the Settings page we offer some site level coupon options:\n\n### Multiple Coupons Per Account\nBy 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 <a href=\"/docs/multiple-coupons-per-account\">Multiple Coupons Per Account</a> feature documentation.\n\n### One-Time Charges\nBy 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 <strong>Eligible Charges</strong>. There you can select any configuration of one-time charges and or plans.\n\nOne-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.\n\n### Hosted Payment Pages\nIf 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. <a href=\"https://app.recurly.com/go/configuration/hosted_pages\">Visit the Hosted Page Settings in your Recurly site.</a>\n\n## Coupon Overview\nEach 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.\n\n### Coupon Summary\nThe 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.\n\n### Redemptions\nAll 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.\n\n### Not Redeemed\nIf 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.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/rxp4eal1TlmxCxAjgUy6_coupon-overview.png\",\n        \"coupon-overview.png\",\n        \"984\",\n        \"829\",\n        \"#e86a6b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## Create a Coupon\nTo create a new coupon, click the <strong>New Coupon</strong> button at the top right on in the Coupons dashboard. You will see a form with the following fields:\n\n### Internal Name\nThe 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.\n\n### Code\nThe 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\".\n\n<strong>Single Code</strong>\nThe coupon code you specify must be unique across your redeemable coupons. You can only reuse a coupon code if that coupon code exists on a coupon that was either manually expired or it reached it's maximum redemptions. If the coupon expired by reaching it's redeem by date, it cannot be reused.\n\nCoupon codes can be alphanumeric and may include a dash (-), underscore (_), or a plus sign (+).\n\n<strong>Bulk Unique Codes</strong>\nTo learn about creating unique codes for your coupon campaign, read our <a href=\"/docs/bulk-unique-coupons\">Bulk Unique Coupons</a> documentation.\n\n### Type of discount\nThe 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.\n* A fixed amount coupon redemption will apply the currency that matches the invoice.\n* See <a href=\"#section-coupon-accounting\">Coupon Accounting</a> for information on how fixed amount and percentage discounts are applied to line items.\n* 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 free trial, then the length of the free trial coupon should be 1 month.   \n\n### Duration\nThe 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.\n\nThere are three duration choices: Forever, Single Use and Limited Time: \n\n* **Forever** - A recurring discount that will be applied to each billing cycle until manually removed from the account.\n\n* **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.\n\n* **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.\n\n  **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.\n\n  These coupons will also not apply to new charges if the customer upgrades or downgrades mid billing cycle.\n  \n* **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 billing cycle of the eligible plans included in the coupon. <i>Limited lifespan coupons will automatically expire one hour prior to the anniversary of their redemption.</i>\n\n### Maximum Redemptions\nMaximum redemptions is the number of times the coupon code can be redeemed across all customers. By default this field is set to \"Unlimited\". \n* 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.\n* A coupon will expire when it hits its maximum redemptions.\n\n### Redemptions Per Account\nRedemptions 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.\n* 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.\n\n### Redeem By Date\nRedeem 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.\n* 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.\n\n### Eligible Charges\n\nIf 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.\n\n* Plan charges include: setup, plan, and add-on fees\n* One-time charges are created through the \"Create Charge\" option on account pages, or as adjustments in the API\n* If \"Plans\" is selected, the Eligible Plans section will show\n\n### Eligible Plans\nEligible plans is the list of all plans or specific plans that the coupon can discount on an account. All plans is selected by default. If you select <strong>Specific plans</strong>, you will see a table appear where you can select the plans you want to include.\n* If you specified a limited time duration, make sure the plans you select have a billing cycle 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.\n\n### Discount Level\nBy default, coupons redeemed on an account will discount any subscription on the account that is for a plan the coupon discounts. We call this \"Account-level\". You can now select \"Subscription-level\" and require the coupon to be tied to one specific subscription on the account, making sure the discount is only applied to that subscription. Free trial coupons can only be subscription-level, so this section does not appear if the coupon type is free trial.\n\n<strong>Account-level</strong>\n* Coupon redemptions will discount all subscriptions for eligible plans on an account.\n* If a subscription is terminated, active coupon redemptions on the account will remain active on the account.\n\n<strong>Subscription-level</strong>\n* Coupon redemptions will only discount one specific subscription on an account.\n* 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. \n* 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.\n* A subscription can have more than one subscription-level coupon redemption tied to it.\n* 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\n* 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.\n\n<strong>Using Subscription-level for Gift Subscriptions</strong>\nGift 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.\n\n<strong>Subscription-level Redemptions in an Upgrade or Downgrade</strong>\nIf 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.\n\nWe 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.\n\n<strong>Removing subscription-level Redemptions</strong>\nTo 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.\n\n<strong>How Discount Level Affects Redemption Duration</strong>\nSay 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.\n* 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.\n* 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.\n\n### Payment Page Description\nThe 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.\n* 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.\n\n### Invoice Description\nThe invoice description will show in the <strong>Discounts Applied</strong> 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. \n\n\n## Redeem a Coupon\nWhen 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.\n\n### Redeem at Purchase\nIn 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:\n* 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.\n* If the subscription sign-up fails due to a transaction decline, the coupon will not be redeemed on the account.\n* 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.\n* 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.\n* If the coupon is subscription-level, redeeming it in a subscription creation action will automatically tie the redemption to that subscription.\n* 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.\n\n<strong>Hosted Payment Pages</strong>\nTo 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.\n\n<strong>Hosted Payment Pages Coupon Redemption Field</strong>\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1ljpdNjYSGmAFn6I9mSV_coupon_field.png\",\n        \"coupon_field.png\",\n        \"345\",\n        \"96\",\n        \"#3e9fd6\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n<strong>API and Recurly.js</strong>\nYou 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.\n\n<strong>Recurly UI</strong>\nWhen 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.\n\n### Redeem on Account\nIf 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. \n\n<strong>Recurly UI</strong>\nEach account page has it's own Coupon Redemptions page that you can access by clicking on <strong>Manage Coupons</strong> 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.\n\n* 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.\n* 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.\n\n<strong>API and Recurly.js</strong>\nYou 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.\n\n<strong>Hosted Account Management</strong>\nWe 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 <a href=\"https://support.recurly.com/\" target=\"_blank\">support ticket</a>.\n\n## Remove a Redemption\nIf 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 <strong>Manage Coupons</strong> 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 <strong>Remove</strong> action in the right hover actions for the table row.\n\nIf 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.\n\n## Edit a Coupon\nRedeemable 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:\n* Internal Name\n* Maximum Redemptions\n* Redeem By date\n* Redemptions Per Account\n* Payment Page Description\n* Invoice Description _(not applicable to free trial coupons)_\n\nTo 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 <strong>Edit</strong> and you will be taken to the edit page for the coupon. Edit the fields you want to change and click <strong>Save Changes</strong>.\n\n<strong>Note:</strong> 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.\n\n## Expire a Coupon\nCoupons 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.\n\n### Expire Early\nCoupons can be manually expired in an action we call <strong>Expire Early</strong>. To expire a coupon, visit the coupon's overview page and select <strong>Expire Early</strong> 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.\n\n### Automatically Expire\nCoupons 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.\n\nBulk coupons with all unique codes redeemed will be considered Expired in the UI, even though their true status is active in the API.\n\n### Reuse a Coupon Code\nIf 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 grandfathered into 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.\n\nIf a coupon expired by reaching it's redeem by date, you will not be able to reuse the coupon code.\n\n## Restore a Coupon\nIf 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.\n* Internal Name\n* Maximum Redemptions\n* Redeem By date\n* Redemptions Per Account\n* Payment Page Description\n* Invoice Description _(not applicable to free trial coupons)_\n\nTo 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 <strong>Restore</strong> and you will be taken to the restore page for the coupon. Edit the fields you want to change and click <strong>Restore Coupon</strong>.\n\n<strong>Note:</strong> 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.\n\n### Bulk Coupons\nBulk 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.\n* 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.\n* 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.\n* 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.\n\nTo 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.\n\n## Coupon and Discount Exports\nThere 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.\n\n### Coupons\nThis 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.\n\nSee the details of this export in our <a href=\"/docs/export-overview#coupons\">Coupons export documentation</a>.\n\n### Coupon Redemptions\nThis 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.\n\nSee the details of this export in our <a href=\"/docs/export-overview#coupon_redemptions\">Coupon Redemptions export documentation</a>.\n\n### Coupons - Bulk Unique Codes\nThis 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.\n\nSee the details of this export in our <a href=\"/docs/export-overview#coupons-bulk-unique-codes\">Coupons - Bulk Unique Codes documentation</a>.\n\n### Invoices - Summary\nThis export answers which coupons were applied to the invoice, noted in the coupon_code column.\n* The coupon_code column will show a comma separated list of coupon codes if the invoice had more than one coupon code applied.\n* 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.\n* Coupons used to calculate returned credits will show in this list.\n\nSee the details of this export in our <a href=\"docs//export-overview#invoices-summary\">Invoices - Summary export documentation</a>.\n\n### Invoices - Line Items\nThis export answers which coupons were applied to the line item and the total discount they created on the line item.\n* The adjustment_discount column will show the total discount for the line item. \n* 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.\n* You will see a comma separated list of coupon codes if the line item had more than one coupon code applied.\n* 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.\n* Coupons used to calculate returned credits will show in this list.\n\nSee the details of this export in our <a href=\"/docs/export-overview#invoices-line-items\">Invoices - Line Items export documentation</a>.\n\n### Invoices - Line Items - Coupons\nThis 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.\n* This export creates a row for each line item discount. A line item with multiple discounts applied will have multiple rows in the export.\n* 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.\n* 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.\n* Line items for credits will also show any coupons and discounts applied to calculate the correct credits to return.\n* 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. \n\nSee the details of this export in our <a href=\"/docs/export-overview#invoices-line-items-coupons\">Invoices - Line Items Coupons export documentation</a>.\n\n## Coupon Examples\n\n### First Month Free\nCreate a coupon that fully discounts the first month.\n* Discount: 100%\n* Duration: Single Use\n\n<strong>Does your plan have a free trial and a setup fee?</strong>\nCoupon 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.\n\n### Multiple Billing Cycles Discounted\nCreate a coupon that discounts multiple billing cycles.\n* Duration: Limited time (match period to your plan's billing cycle length)\n\nNote: 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.\n\n###Special Occasion\n\nIf 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.","excerpt":"Whether you are implementing a promotion, discount, special offer, or sale strategy, use Recurly's Coupons to create codes your customers can redeem in order to get a discount on their purchases. Track campaign success through the Coupons Dashboard and Exports.","slug":"coupons","type":"basic","title":"Coupons and Discounts"}

Coupons and Discounts

Whether you are implementing a promotion, discount, special offer, or sale strategy, use Recurly's Coupons to create codes your customers can redeem in order to get a discount on their purchases. Track campaign success through the Coupons Dashboard and Exports.

## What's New! We recently released a ton of new coupon options. Select a feature below to learn more: * <a href="/docs/multiple-coupons-per-account">Multiple Coupons Per Account</a> * <a href="/docs/bulk-unique-coupons">Bulk Unique Coupons</a> * <a href="#section-eligible-charges">Coupons for One-Time Charges</a> * <a href="#section-redemptions-per-account">Limit Redemptions Per Account</a> * <a href="#section-discount-level">Subcription-Level Discounts</a> * <a href="#section-edit-a-coupon">Edit a Coupon</a> * <a href="#section-restore-a-coupon">Restore a Coupon</a> * <a href="#section-free-trial-coupons">Free Trial Coupons</a> ## Table of Contents * <a href="#section-features-overview">Features Overview</a> * <a href="#section-coupon-accounting">Coupon Accounting</a> * <a href="#section-coupons-dashboard">Coupons Dashboard</a> * <a href="#section-coupon-settings">Coupon Settings</a> * <a href="#section-coupon-overview">Coupon Overview</a> * <a href="#section-create-a-coupon">Create a Coupon</a> * <a href="#section-redeem-a-coupon">Redeem a Coupon</a> * <a href="#section-remove-a-redemption">Remove a Redemption</a> * <a href="#section-edit-a-coupon">Edit a Coupon</a> * <a href="#section-expire-a-coupon">Expire a Coupon</a> * <a href="#section-restore-a-coupon">Restore a Coupon</a> * <a href="#section-coupon-and-discount-exports">Coupon and Discount Exports</a> * <a href="#section-coupon-examples">Coupon Examples</a> ## 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 * 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 ## 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. <strong>Percentage discounts will never discount a plan setup fee.</strong> 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. <strong>Percentage Discount Example</strong> 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. <strong>Fixed Amount Discount Example</strong> 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 <a href="/docs/multiple-coupons-per-account">Multiple Coupons Per Account</a> feature. ###Free Trial Coupons Free trial coupons can be used to give new subscriptions different free trial lengths. This is useful to merchants that offer a plan that includes a 1 week free trial, and wants to test how conversion changes when new subscriptions come with that 1 month free trial. 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). Free trial coupons can also 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 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. <a href="https://app.recurly.com/go/coupons">Visit the Coupons dashboard in your Recurly site.</a> [block:image] { "images": [ { "image": [ "https://files.readme.io/bWQiluBgRVyXu3cK0F9r_coupon-dashboard.png", "coupon-dashboard.png", "958", "510", "#55646d", "" ] } ] } [/block] ### 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 <strong>Settings</strong>. 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 <a href="/docs/multiple-coupons-per-account">Multiple Coupons Per Account</a> 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 <strong>Eligible Charges</strong>. 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. <a href="https://app.recurly.com/go/configuration/hosted_pages">Visit the Hosted Page Settings in your Recurly site.</a> ## 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/rxp4eal1TlmxCxAjgUy6_coupon-overview.png", "coupon-overview.png", "984", "829", "#e86a6b", "" ] } ] } [/block] ## Create a Coupon To create a new coupon, click the <strong>New Coupon</strong> 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". <strong>Single Code</strong> The coupon code you specify must be unique across your redeemable coupons. You can only reuse a coupon code if that coupon code exists on a coupon that was either manually expired or it reached it's 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 (+). <strong>Bulk Unique Codes</strong> To learn about creating unique codes for your coupon campaign, read our <a href="/docs/bulk-unique-coupons">Bulk Unique Coupons</a> 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 <a href="#section-coupon-accounting">Coupon Accounting</a> 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 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. These coupons will also 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 billing cycle of the eligible plans included in the coupon. <i>Limited lifespan coupons will automatically expire one hour prior to the anniversary of their redemption.</i> ### 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 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 "Create Charge" option on account pages, or as adjustments in the API * If "Plans" is selected, the Eligible Plans section will show ### Eligible Plans Eligible plans is the list of all plans or specific plans that the coupon can discount on an account. All plans is selected by default. If you select <strong>Specific plans</strong>, 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 billing cycle 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. ### Discount Level By default, coupons redeemed on an account will discount any subscription on the account that is for a plan the coupon discounts. We call this "Account-level". You can now select "Subscription-level" and require the coupon to be tied to one specific subscription on the account, making sure the discount is only applied to that subscription. Free trial coupons can only be subscription-level, so this section does not appear if the coupon type is free trial. <strong>Account-level</strong> * 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. <strong>Subscription-level</strong> * Coupon redemptions will only discount one specific subscription on an account. * 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. <strong>Using Subscription-level for Gift Subscriptions</strong> 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. <strong>Subscription-level Redemptions in an Upgrade or Downgrade</strong> 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. <strong>Removing subscription-level Redemptions</strong> 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. <strong>How Discount Level Affects Redemption Duration</strong> 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 <strong>Discounts Applied</strong> 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. <strong>Hosted Payment Pages</strong> 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. <strong>Hosted Payment Pages Coupon Redemption Field</strong> [block:image] { "images": [ { "image": [ "https://files.readme.io/1ljpdNjYSGmAFn6I9mSV_coupon_field.png", "coupon_field.png", "345", "96", "#3e9fd6", "" ] } ] } [/block] <strong>API and Recurly.js</strong> 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. <strong>Recurly UI</strong> 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 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. <strong>Recurly UI</strong> Each account page has it's own Coupon Redemptions page that you can access by clicking on <strong>Manage Coupons</strong> 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. <strong>API and Recurly.js</strong> 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. <strong>Hosted Account Management</strong> 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 <a href="https://support.recurly.com/" target="_blank">support ticket</a>. ## 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 <strong>Manage Coupons</strong> 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 <strong>Remove</strong> 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 <strong>Edit</strong> and you will be taken to the edit page for the coupon. Edit the fields you want to change and click <strong>Save Changes</strong>. <strong>Note:</strong> 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 <strong>Expire Early</strong>. To expire a coupon, visit the coupon's overview page and select <strong>Expire Early</strong> 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 grandfathered into 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 <strong>Restore</strong> and you will be taken to the restore page for the coupon. Edit the fields you want to change and click <strong>Restore Coupon</strong>. <strong>Note:</strong> 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. ### 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 <a href="/docs/export-overview#coupons">Coupons export documentation</a>. ### 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 <a href="/docs/export-overview#coupon_redemptions">Coupon Redemptions export documentation</a>. ### 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 <a href="/docs/export-overview#coupons-bulk-unique-codes">Coupons - Bulk Unique Codes documentation</a>. ### 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 <a href="docs//export-overview#invoices-summary">Invoices - Summary export documentation</a>. ### 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 <a href="/docs/export-overview#invoices-line-items">Invoices - Line Items export documentation</a>. ### 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 <a href="/docs/export-overview#invoices-line-items-coupons">Invoices - Line Items Coupons export documentation</a>. ## Coupon Examples ### First Month Free Create a coupon that fully discounts the first month. * Discount: 100% * Duration: Single Use <strong>Does your plan have a free trial and a setup fee?</strong> 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 billing cycle 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.