{"__v":34,"_id":"565f2d840dc99e1900f24bb8","category":{"__v":11,"_id":"565def2677f0090d005819bb","pages":["565def2bb311ea0d00a38597","565f2d5d413e06170093dea4","565f2d840dc99e1900f24bb8","565f2dd8bca87d0d006bc68a","565f2e2423fd5f0d00a12a93","565f2f7c0dc99e1900f24bc2","565f2fadbca87d0d006bc698","565f2fe223fd5f0d00a12a9b","565f3011413e06170093debe","565f3040ea46251700972769","5665df7bd8a06b170063f30b"],"project":"56450a342229d7170010928a","version":"56450a342229d7170010928d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-01T19:04:06.860Z","from_sync":false,"order":1,"slug":"reference","title":"Reference"},"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-02T17:42:28.879Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"[Your subscriptions dashboard][1] provides an overview of all [accounts][2] with subscriptions managed by Recurly. From this view you can sort your subscriptions by account, plan code, subscription status, subscription creation date, or next subscription invoice date. The filters on this view allow you to bucket accounts by subscription status for easy sorting. Categories overlap and are not necessarily distinct, *e.g.* the **Live** filter will return both **Renewing** and **Canceled** subscriptions.\n\n[1]: https://app.recurly.com/go/subscriptions\n[2]: /docs/accounts\n\n\n####All\nAll subscriptions.\n####Renewing\nActive subscriptions that are active and will renew after the current billing period.\n####Future Start\nSubscriptions that will become active when the start date arrives.\n####Last Renewal\nSubscriptions with limited renewals that will expire after the current period.\n####Canceled\nSubscriptions that will not renew after the current billing period.\n####Expired\nSubscriptions that are no longer active.\n####Trial\nActive subscriptions that are in a trial period.\n####Paying\nActive subscriptions that are no longer in trial.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating Subscriptions\"\n}\n[/block]\nAn account can be subscribed to a [plan][8] a number of ways:\n\n* [Recurly Hosted Payment Pages][3]\n* [Recurly.js][4]\n* [Recurly API][5], or\n* [the admin console][6].\n\nPlease see [our getting started guide][7] to see which integration method is best for your business.\n\n[3]: /docs/hosted-payment-pages\n[4]: https://js.recurly.com/\n[5]: https://dev.recurly.com\n[6]: https://app.recurly.com/go/configuration\n[7]: /docs/implementation-guide\n\nTo add a subscription using the admin console, open the customer’s account and click the **Add Subscription** button, then configure the following:\n\n### Plan Details\n\n####Plan\nThe subscription's [subscription plan](/docs/plans).\n#### Currency\n The subscription plan's purchase currency. Set to site's default currency.\n####Price\nThe subscription's base price per billing period. The default price can be overridden here for an individual account.\n####Quantity\nDefault: 1.\n\n### Plan Extras (Optional)\n\n####Setup Fees\nIf applicable, this fee will be charged to the customer at the beginning of their subscription\n####Add Ons\nIf applicable, these products will be rolled into a recurring subscription's invoice as separate line items.\n\n### Billing Details\n\nIn this section, merchants can select for a subscription to start immediately, or enter a future start date for the subscription. For subscriptions with a trial period, the subscription trial will start on this date. Merchants can also have a subscription bill indefinitely or for a set number of billing cycles. The subscription will cancel after the final bill cycle has been charged.\n\n### Collection Method\n\n####Automatic\nCharges the billing info on file for the account.\n####Manual\nGenerates a manual invoice. This is only applicable to merchants who have enabled the manual payments feature. When this collection method is selected you will have the option to assign a PO number, and will also be able to set the net terms for the invoices.\n\n### Multiple Subscriptions\n\nAn account may signup for multiple subscriptions, where each subscription is invoiced and billed separately. There are a couple of ways that Recurly supports multiple subscriptions.\n* You can use increase the number of subscriptions with the **Quantity** field for a plan.\n* You can create multiple subscriptions of the same plan for an account that has separate renewal periods.\n\nTo have the multiple instances of the same plan enabled for your site, please contact <a href=\"mailto:support:::at:::recurly.com\">support@recurly.com</a>. Please note that there is a 60 second delay when creating multiple of the same subscription per an account, unless you use the <a href=\"https://dev.recurly.com/docs/create-subscription\">bulk flag</a> via the create subscription API.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Changing Subscriptions\"\n}\n[/block]\nDowngrades and upgrades are called subscription changes in Recurly. These can be a change in plan, quantity, price, or adding/removing add-ons. Subscription changes include additional updates, like a change in collection method or invoice notes.\n\n### TIMING OF CHANGE\nA subscription can be changed immediately or at the next renewal. Immediate changes will bill the change right away. At renewal changes will reflect the change on the next renewal invoice. It is not currently possible to make an immediate change to the subscription, but bill that change at renewal. Please contact <a href=\"https://support.recurly.com/\" target=\"_blank\">Recurly support</a> if you would like to see this functionality added.\n\n#### DOWNGRADES AND UPGRADES\nIn most cases, we see that merchants prefer to make upgrades immediate and downgrades at renewal. Immediate upgrades allow you provide the customer the higher value product and collect the additional money right away. At renewal downgrades allow you to lock the customer into the agreed upon, and paid for, billing cycle, continuing to provide the customer with the higher value product until the next renewal.\n\n#### DIGITAL VS. PHYSICAL GOODS\nImmediate subscription changes will prorate charges and credits based on time down to the second. This is common for digital services. Due to this time-based proration, we recommend that subscriptions with recurring physical goods only allow at renewal changes.\n\n### IMMEDIATE CHANGES\nImmediate subscription changes will bill for the difference in cost immediately. This means an invoice will be created and, if using automatic collection, a transaction will be attempted on the payment method provided in the Billing Information on the customer's account. If the transaction fails, the invoice and subscription will go into the Dunning process. If you would prefer to block immediate changes where the transaction fails or the account is past due, please see <a href=\"#section-modification-enforcement\">Modification Enforcement</a> below.\n\n#### EMAIL COMMUNICATIONS\nBoth automatic and manually collected subscriptions will issue the Subscription Change email, if enabled, to the customer immediately. \n* Manually collected subscriptions will additionally send the New Invoice email, if enabled, to the customer. \n* Automatically collected subscriptions will additionally send either the Payment Confirmation or Payment Declined email, if enabled, to the customer, depending on whether the transaction was successful or declined.\n\n#### CHARGES AND CREDITS\nRecurly treats all immediate changes as if they were a complete change in the type of revenue, for example, an upgrade from the Silver plan to the Gold plan. This means that we charge for the new version of the subscription, prorated for the time remaining in the billing cycle, and credit for the old version of the subscription, also prorated for the time remaining in the billing cycle. If the subscription change is not a plan change, rather a quantity change, price change, or adding/removing an add-on, you will still see the entire subscription is rebilled. We do not bill only the difference. Here are some examples:\n\n*Example of a Plan Change*\nAn upgrade from the Silver plan to the Gold plan would create these charges and credits:\n* Charge for Gold plan\n* Credit for Silver plan\n\n*Example of a Quantity Change*\nAn upgrade on the same AcmeCRM plan from 5 users to 7 users would create these charges and credits:\n* Charge for AcmeCRM with quantity 7\n* Credit for AcmeCRM with quantity 5\n\nIf the charge is greater than the credit (plus the user's current balance), the user will be charged the difference. If the credit is greater than the charge, then the user will have a credit on their account that will be applied to their next renewal charge.\n\n#### TIME-BASED PRORATION\nImmediate subscription changes will prorate charges and credits based on time down to the second. We use time-based proration because Recurly was initially founded on supporting digital subscription businesses where the cost represents time-based access to a service. If you require other forms of proration, please contact <a href=\"https://support.recurly.com/\" target=\"_blank\">Recurly support</a>, so we can track your request.\n\n*Proration Formula*\nProration is the time remaining in the current billing cycle divided by the time in the subscription's plan period. This is then multiplied by the per unit price to get the correct amount to charge and credit. \n\nWe only charge for the remaining amount of time because the customer will be billed the full price when the subscription renews at the end of the billing cycle, so we want to make sure we don't over charge them and only charge for the actual time they will get to use the new product or service in this cycle. Similarly, we want to credit the customer what they paid for, but will not use. Since they will not use the product or service for the remainder of the billing cycle, this is the portion that is returned as a credit.\n\n**(time remaining in current billing cycle / subscription's plan period) x (per unit price)**\n\nOr more specifically...\n\n**[(current billing cycle end date - time of change) / (plan period end date - plan period start date)] x (per unit price)**\n\nYou probably notice that the denominator of the proration fraction refers to the plan period, not the billing cycle. This is because the billing cycle can be customized through the postpone feature. If the billing cycle end date is changed to be sooner or later, the numerator will reflect that new end date, but the denominator will respect the underlying plan period's end date. For example, if the subscription was for an annual plan, but after the subscription was created the current billing cycle end date was moved in to a shorter date, the denominator would reflect a year while the numerator would reflect the new end date which would be less than a year out. Learn more about the postponing subscriptions below.\n\n#### PLAN PERIOD CHANGES\nImmediate subscription changes where the plan period stays the same (e.g. - monthly to monthly or yearly to yearly) will maintain the current billing cycle on the subscription and follow normal proration rules. If the immediate subscription change is a plan change where the underlying period changes (e.g. - monthly to yearly or yearly to monthly), the subscription billing cycle will start over and the new charges will not be prorated.\n\n*Example Change with Same Period*\nCustomer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the monthly Gold plan on May 20, 2016.\n* Subscription will still have a current billing cycle of May 15 - June 15, 2016\n* Change invoice will have a prorated charge for Gold with dates of May 20 - June 15, 2016\n* Change invoice will have a prorated credit for Silver with dates of May 20 - June 15, 2016\n\n*Example Change with Different Period*\nCustomer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the yearly Silver plan on May 20, 2016.\n* Subscription will now have a billing cycle of May 20, 2016 - May 20, 2017\n* Change invoice will have a full charge for yearly Silver with dates of May 20, 2016 - May 20, 2017\n* Change invoice will have a prorated credit for monthly Silver with dates of May 20 - June 15, 2016\n\n### AT RENEWAL CHANGES\nWhen a subscription change's timeframe is set to renewal, Recurly saves the changes so it can apply the changes when it's time to renew the subscription. Recurly only persists one change request. If you submit a change request to apply at renewal and then submit a second change request before renewal, the first request will be canceled. The second request will be applied immediately or at renewal, as indicated by the timeframe parameter. For \"At renewal\" change requests, there is no need to prorate the amounts. Recurly will adjust the subscription appropriately and then invoice the user at the new amount.\n\nIf you want to update a pending change, please submit the original change plus the updated information. Today, the only parameters are: subscription plan, quantity, and unit amount. Pending changes can be cleared by updating the subscription **Immediately** with no other changes.\n\n### MODIFICATION ENFORCEMENT\nSome merchants may prefer to have their customers current and up-to-date on all payments before allowing a subscription upgrade or downgrade. Recurly allows this to be configured on your Invoice Settings page through two different options:\n\n**Require successful transaction on upgrades**\nWhen upgrading an existing subscription, require that the payment information on file process successfully in order to complete the upgrade. If the payment information is declined, the subscription will be kept on the original plan.\n\n**Require paid invoice to downgrade**\nWhen downgrading an existing subscription, require that all invoices have been successfully paid in order to complete the downgrade. If any invoice is past due, the subscription will be kept on the original plan, and an error will be provided to the customer;  \"Your account is currently past due, please update your billing information before changing your subscription.\"\n\n### PLAN CHANGES AND GRANDFATHERING\n\nIf a subscription's underlying [plan][8] is altered, the changes will only impact new subscribers—your current subscribers remain grandfathered in at the plan terms they agreed to at time of subscription signup. Price grandfathering does not apply to changes in bill cycle (ie, monthly to yearly), however, so changes to billing frequency should be made with a new plan.\n\n[8]: /docs/plans\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Postpone Subscription Renewal\"\n}\n[/block]\nBy default your subscribers are billed on the anniversary date of their subscription signup. If this date needs to change for any reason, a subscription can be postponed. This is the same thing as changing the subscription's next renewal date. A postponed subscription will receive no further invoices until the postpone date occurs, unless you make an immediate subscription change.\n\nWhen a subscription is postponed, the billing cycle dates will be permanently modified for all future renewals. For example, a yearly subscription with a billing cycle of May 15, 2016 - May 20, 2017 that is then postponed to be May 15, 2016 - Dec 10, 2016 will at renewal change the cycle to Dec 10, 2016 - Dec 10, 2017.\n\n### BACKDATE A SUBSCRIPTION\nShortening the renewal date through the postpone action can be used to backdate subscriptions in Recurly. This is more common for B2B merchants where contracts are being signed and the customer has actually started the subscription before you are able to add them to Recurly and bill them.\n\nAdd the customer's subscription to Recurly while they are still in their first billing cycle. This will bill them the full amount of the subscription, or whatever custom amount you enter when adding the subscription. The start date in Recurly will not match when the customer actually started, but now you can postpone the subscription's renewal to realign the dates. On the Subscription Details page for the subscription, click on \"Change Renewal Date\" and select the renewal date that matches the next renewal for the contract or your own system. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription.\n\n### PAUSE A SUBSCRIPTION\nExtending the renewal date through the postpone action can be used to pause a subscription in Recurly. This is useful if you have a customer that is unable to use your product or services for a period of time, but does not want to lose their subscription and you do not want to consider them a churned customer.\n\nGo to the Subscription Details page for the customer's subscription, click on \"Change Renewal Date\" and select the future date when you want the subscription to start again. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription. As long as you do not do any immediate changes on the subscription, the customer will not be billed again until that new future date.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Immediate changes after postponing by extending will prorate more than 100%\",\n  \"body\": \"Be careful if you are allowing immediate changes after extending the renewal date. The time remaining could end up being more than the subscription's plan period, which will create charges and credits that are more than the original per unit price.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Canceling and Reactivating Subscriptions\"\n}\n[/block]\nA subscription that is canceled will continue through its current billing cycle. At the end of the current bill cycle the subscription will terminate and the customer will no longer be billed.\n\nTo cancel a subscription:\n1. Navigate to the **account page**.\n2. Click **Options** under the Subscription.\n3. Click the **Cancel Subscription**.\n4. Choose the **Cancel At Renewal** option.\n\n*Note: If an account has a past due invoice in dunning, canceling/expiring the subscription will not stop collection attempts on that invoice. The invoice will need to be marked as failed in order to stop collection attempts on the invoice.*\n\n*Additionally, if a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list.*\n\n### REACTIVATION\n\nA subscription that is canceled can be reactivated. This will bring the subscription back into an active, renewing state on the customer's original billing cycle. An expired subscription **cannot** be reactivated; instead a new subscription plan will need to be applied to the account.\n\nTo reactivate a canceled subscription:\n1. Navigate to the account page.\n2. Click **Options** under the Subscription.\n2. Click **Reactivate Subscription**.\n3. Click the **Reactivate Subscription** button in the top right corner.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Terminating Subscriptions\"\n}\n[/block]\nA subscription that is terminated will expire immediately. At the time of termination you will be presented with several refund options, if applicable to the account's last invoice. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer's account. You may also terminate a subscription with no refund and then manually refund specific transactions.\n\nTo terminate a subscription:\n1. Navigate to the account page.\n2. Click **Edit** under the subscription.\n3. Click the **Cancel Subscription** button.\n4. Select the appropriate refund option\n5. Click **Terminate Subscription**.","excerpt":"Subscriptions are created when your customer's subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer.","slug":"subscriptions","type":"basic","title":"Subscriptions"}

Subscriptions

Subscriptions are created when your customer's subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer.

[Your subscriptions dashboard][1] provides an overview of all [accounts][2] with subscriptions managed by Recurly. From this view you can sort your subscriptions by account, plan code, subscription status, subscription creation date, or next subscription invoice date. The filters on this view allow you to bucket accounts by subscription status for easy sorting. Categories overlap and are not necessarily distinct, *e.g.* the **Live** filter will return both **Renewing** and **Canceled** subscriptions. [1]: https://app.recurly.com/go/subscriptions [2]: /docs/accounts ####All All subscriptions. ####Renewing Active subscriptions that are active and will renew after the current billing period. ####Future Start Subscriptions that will become active when the start date arrives. ####Last Renewal Subscriptions with limited renewals that will expire after the current period. ####Canceled Subscriptions that will not renew after the current billing period. ####Expired Subscriptions that are no longer active. ####Trial Active subscriptions that are in a trial period. ####Paying Active subscriptions that are no longer in trial. [block:api-header] { "type": "basic", "title": "Creating Subscriptions" } [/block] An account can be subscribed to a [plan][8] a number of ways: * [Recurly Hosted Payment Pages][3] * [Recurly.js][4] * [Recurly API][5], or * [the admin console][6]. Please see [our getting started guide][7] to see which integration method is best for your business. [3]: /docs/hosted-payment-pages [4]: https://js.recurly.com/ [5]: https://dev.recurly.com [6]: https://app.recurly.com/go/configuration [7]: /docs/implementation-guide To add a subscription using the admin console, open the customer’s account and click the **Add Subscription** button, then configure the following: ### Plan Details ####Plan The subscription's [subscription plan](/docs/plans). #### Currency The subscription plan's purchase currency. Set to site's default currency. ####Price The subscription's base price per billing period. The default price can be overridden here for an individual account. ####Quantity Default: 1. ### Plan Extras (Optional) ####Setup Fees If applicable, this fee will be charged to the customer at the beginning of their subscription ####Add Ons If applicable, these products will be rolled into a recurring subscription's invoice as separate line items. ### Billing Details In this section, merchants can select for a subscription to start immediately, or enter a future start date for the subscription. For subscriptions with a trial period, the subscription trial will start on this date. Merchants can also have a subscription bill indefinitely or for a set number of billing cycles. The subscription will cancel after the final bill cycle has been charged. ### Collection Method ####Automatic Charges the billing info on file for the account. ####Manual Generates a manual invoice. This is only applicable to merchants who have enabled the manual payments feature. When this collection method is selected you will have the option to assign a PO number, and will also be able to set the net terms for the invoices. ### Multiple Subscriptions An account may signup for multiple subscriptions, where each subscription is invoiced and billed separately. There are a couple of ways that Recurly supports multiple subscriptions. * You can use increase the number of subscriptions with the **Quantity** field for a plan. * You can create multiple subscriptions of the same plan for an account that has separate renewal periods. To have the multiple instances of the same plan enabled for your site, please contact <a href="mailto:support@recurly.com">support@recurly.com</a>. Please note that there is a 60 second delay when creating multiple of the same subscription per an account, unless you use the <a href="https://dev.recurly.com/docs/create-subscription">bulk flag</a> via the create subscription API. [block:api-header] { "type": "basic", "title": "Changing Subscriptions" } [/block] Downgrades and upgrades are called subscription changes in Recurly. These can be a change in plan, quantity, price, or adding/removing add-ons. Subscription changes include additional updates, like a change in collection method or invoice notes. ### TIMING OF CHANGE A subscription can be changed immediately or at the next renewal. Immediate changes will bill the change right away. At renewal changes will reflect the change on the next renewal invoice. It is not currently possible to make an immediate change to the subscription, but bill that change at renewal. Please contact <a href="https://support.recurly.com/" target="_blank">Recurly support</a> if you would like to see this functionality added. #### DOWNGRADES AND UPGRADES In most cases, we see that merchants prefer to make upgrades immediate and downgrades at renewal. Immediate upgrades allow you provide the customer the higher value product and collect the additional money right away. At renewal downgrades allow you to lock the customer into the agreed upon, and paid for, billing cycle, continuing to provide the customer with the higher value product until the next renewal. #### DIGITAL VS. PHYSICAL GOODS Immediate subscription changes will prorate charges and credits based on time down to the second. This is common for digital services. Due to this time-based proration, we recommend that subscriptions with recurring physical goods only allow at renewal changes. ### IMMEDIATE CHANGES Immediate subscription changes will bill for the difference in cost immediately. This means an invoice will be created and, if using automatic collection, a transaction will be attempted on the payment method provided in the Billing Information on the customer's account. If the transaction fails, the invoice and subscription will go into the Dunning process. If you would prefer to block immediate changes where the transaction fails or the account is past due, please see <a href="#section-modification-enforcement">Modification Enforcement</a> below. #### EMAIL COMMUNICATIONS Both automatic and manually collected subscriptions will issue the Subscription Change email, if enabled, to the customer immediately. * Manually collected subscriptions will additionally send the New Invoice email, if enabled, to the customer. * Automatically collected subscriptions will additionally send either the Payment Confirmation or Payment Declined email, if enabled, to the customer, depending on whether the transaction was successful or declined. #### CHARGES AND CREDITS Recurly treats all immediate changes as if they were a complete change in the type of revenue, for example, an upgrade from the Silver plan to the Gold plan. This means that we charge for the new version of the subscription, prorated for the time remaining in the billing cycle, and credit for the old version of the subscription, also prorated for the time remaining in the billing cycle. If the subscription change is not a plan change, rather a quantity change, price change, or adding/removing an add-on, you will still see the entire subscription is rebilled. We do not bill only the difference. Here are some examples: *Example of a Plan Change* An upgrade from the Silver plan to the Gold plan would create these charges and credits: * Charge for Gold plan * Credit for Silver plan *Example of a Quantity Change* An upgrade on the same AcmeCRM plan from 5 users to 7 users would create these charges and credits: * Charge for AcmeCRM with quantity 7 * Credit for AcmeCRM with quantity 5 If the charge is greater than the credit (plus the user's current balance), the user will be charged the difference. If the credit is greater than the charge, then the user will have a credit on their account that will be applied to their next renewal charge. #### TIME-BASED PRORATION Immediate subscription changes will prorate charges and credits based on time down to the second. We use time-based proration because Recurly was initially founded on supporting digital subscription businesses where the cost represents time-based access to a service. If you require other forms of proration, please contact <a href="https://support.recurly.com/" target="_blank">Recurly support</a>, so we can track your request. *Proration Formula* Proration is the time remaining in the current billing cycle divided by the time in the subscription's plan period. This is then multiplied by the per unit price to get the correct amount to charge and credit. We only charge for the remaining amount of time because the customer will be billed the full price when the subscription renews at the end of the billing cycle, so we want to make sure we don't over charge them and only charge for the actual time they will get to use the new product or service in this cycle. Similarly, we want to credit the customer what they paid for, but will not use. Since they will not use the product or service for the remainder of the billing cycle, this is the portion that is returned as a credit. **(time remaining in current billing cycle / subscription's plan period) x (per unit price)** Or more specifically... **[(current billing cycle end date - time of change) / (plan period end date - plan period start date)] x (per unit price)** You probably notice that the denominator of the proration fraction refers to the plan period, not the billing cycle. This is because the billing cycle can be customized through the postpone feature. If the billing cycle end date is changed to be sooner or later, the numerator will reflect that new end date, but the denominator will respect the underlying plan period's end date. For example, if the subscription was for an annual plan, but after the subscription was created the current billing cycle end date was moved in to a shorter date, the denominator would reflect a year while the numerator would reflect the new end date which would be less than a year out. Learn more about the postponing subscriptions below. #### PLAN PERIOD CHANGES Immediate subscription changes where the plan period stays the same (e.g. - monthly to monthly or yearly to yearly) will maintain the current billing cycle on the subscription and follow normal proration rules. If the immediate subscription change is a plan change where the underlying period changes (e.g. - monthly to yearly or yearly to monthly), the subscription billing cycle will start over and the new charges will not be prorated. *Example Change with Same Period* Customer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the monthly Gold plan on May 20, 2016. * Subscription will still have a current billing cycle of May 15 - June 15, 2016 * Change invoice will have a prorated charge for Gold with dates of May 20 - June 15, 2016 * Change invoice will have a prorated credit for Silver with dates of May 20 - June 15, 2016 *Example Change with Different Period* Customer subscribes to the monthly Silver plan on May 15, 2016 and then upgrades to the yearly Silver plan on May 20, 2016. * Subscription will now have a billing cycle of May 20, 2016 - May 20, 2017 * Change invoice will have a full charge for yearly Silver with dates of May 20, 2016 - May 20, 2017 * Change invoice will have a prorated credit for monthly Silver with dates of May 20 - June 15, 2016 ### AT RENEWAL CHANGES When a subscription change's timeframe is set to renewal, Recurly saves the changes so it can apply the changes when it's time to renew the subscription. Recurly only persists one change request. If you submit a change request to apply at renewal and then submit a second change request before renewal, the first request will be canceled. The second request will be applied immediately or at renewal, as indicated by the timeframe parameter. For "At renewal" change requests, there is no need to prorate the amounts. Recurly will adjust the subscription appropriately and then invoice the user at the new amount. If you want to update a pending change, please submit the original change plus the updated information. Today, the only parameters are: subscription plan, quantity, and unit amount. Pending changes can be cleared by updating the subscription **Immediately** with no other changes. ### MODIFICATION ENFORCEMENT Some merchants may prefer to have their customers current and up-to-date on all payments before allowing a subscription upgrade or downgrade. Recurly allows this to be configured on your Invoice Settings page through two different options: **Require successful transaction on upgrades** When upgrading an existing subscription, require that the payment information on file process successfully in order to complete the upgrade. If the payment information is declined, the subscription will be kept on the original plan. **Require paid invoice to downgrade** When downgrading an existing subscription, require that all invoices have been successfully paid in order to complete the downgrade. If any invoice is past due, the subscription will be kept on the original plan, and an error will be provided to the customer; "Your account is currently past due, please update your billing information before changing your subscription." ### PLAN CHANGES AND GRANDFATHERING If a subscription's underlying [plan][8] is altered, the changes will only impact new subscribers—your current subscribers remain grandfathered in at the plan terms they agreed to at time of subscription signup. Price grandfathering does not apply to changes in bill cycle (ie, monthly to yearly), however, so changes to billing frequency should be made with a new plan. [8]: /docs/plans [block:api-header] { "type": "basic", "title": "Postpone Subscription Renewal" } [/block] By default your subscribers are billed on the anniversary date of their subscription signup. If this date needs to change for any reason, a subscription can be postponed. This is the same thing as changing the subscription's next renewal date. A postponed subscription will receive no further invoices until the postpone date occurs, unless you make an immediate subscription change. When a subscription is postponed, the billing cycle dates will be permanently modified for all future renewals. For example, a yearly subscription with a billing cycle of May 15, 2016 - May 20, 2017 that is then postponed to be May 15, 2016 - Dec 10, 2016 will at renewal change the cycle to Dec 10, 2016 - Dec 10, 2017. ### BACKDATE A SUBSCRIPTION Shortening the renewal date through the postpone action can be used to backdate subscriptions in Recurly. This is more common for B2B merchants where contracts are being signed and the customer has actually started the subscription before you are able to add them to Recurly and bill them. Add the customer's subscription to Recurly while they are still in their first billing cycle. This will bill them the full amount of the subscription, or whatever custom amount you enter when adding the subscription. The start date in Recurly will not match when the customer actually started, but now you can postpone the subscription's renewal to realign the dates. On the Subscription Details page for the subscription, click on "Change Renewal Date" and select the renewal date that matches the next renewal for the contract or your own system. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription. ### PAUSE A SUBSCRIPTION Extending the renewal date through the postpone action can be used to pause a subscription in Recurly. This is useful if you have a customer that is unable to use your product or services for a period of time, but does not want to lose their subscription and you do not want to consider them a churned customer. Go to the Subscription Details page for the customer's subscription, click on "Change Renewal Date" and select the future date when you want the subscription to start again. This new date is when the subscription will next renew and the customer will again be charged the full amount of the subscription. As long as you do not do any immediate changes on the subscription, the customer will not be billed again until that new future date. [block:callout] { "type": "warning", "title": "Immediate changes after postponing by extending will prorate more than 100%", "body": "Be careful if you are allowing immediate changes after extending the renewal date. The time remaining could end up being more than the subscription's plan period, which will create charges and credits that are more than the original per unit price." } [/block] [block:api-header] { "type": "basic", "title": "Canceling and Reactivating Subscriptions" } [/block] A subscription that is canceled will continue through its current billing cycle. At the end of the current bill cycle the subscription will terminate and the customer will no longer be billed. To cancel a subscription: 1. Navigate to the **account page**. 2. Click **Options** under the Subscription. 3. Click the **Cancel Subscription**. 4. Choose the **Cancel At Renewal** option. *Note: If an account has a past due invoice in dunning, canceling/expiring the subscription will not stop collection attempts on that invoice. The invoice will need to be marked as failed in order to stop collection attempts on the invoice.* *Additionally, if a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list.* ### REACTIVATION A subscription that is canceled can be reactivated. This will bring the subscription back into an active, renewing state on the customer's original billing cycle. An expired subscription **cannot** be reactivated; instead a new subscription plan will need to be applied to the account. To reactivate a canceled subscription: 1. Navigate to the account page. 2. Click **Options** under the Subscription. 2. Click **Reactivate Subscription**. 3. Click the **Reactivate Subscription** button in the top right corner. [block:api-header] { "type": "basic", "title": "Terminating Subscriptions" } [/block] A subscription that is terminated will expire immediately. At the time of termination you will be presented with several refund options, if applicable to the account's last invoice. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer's account. You may also terminate a subscription with no refund and then manually refund specific transactions. To terminate a subscription: 1. Navigate to the account page. 2. Click **Edit** under the subscription. 3. Click the **Cancel Subscription** button. 4. Select the appropriate refund option 5. Click **Terminate Subscription**.