{"__v":25,"_id":"5665e000e93ae70d00b96a2c","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":["571a52326346850e00834334"],"createdAt":"2015-12-07T19:37:36.878Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"## Dashboard\n\nYour [plans dashboard][1] contains a list of plans defined in your Recurly account. You can click on any plan name to view detailed plan information, edit the plan, or link to that plan's [Hosted Payment Page][2].\n\n[1]: https://app.recurly.com/go/plans\n[2]: /docs/hosted\n\n## Creating a Plan\n\nFrom your main plan page, click **New Plan**. To create a new plan you'll need to define the following parameters:\n\n\n####Plan Name\nThis name describes your plan and will appear on <a href='/docs/hosted'>the Hosted Payment Page</a> and the subscriber's invoice. (255 character limit.) Please note that your payment gateway may also place limitations on your subscription name, so it may be best to avoid special characters without checking with your gateway provider.\n####Plan Code\nThis is the plan's unique Recurly identifier and is used in <a href='/docs/hosted'>Hosted Payment Page</a> URLs and to fetch plans via <a href='https://dev.recurly.com'>the API</a>. (Alphanumeric characters only. 50 character limit.)\n####Plan Description\nA description of the plan that will appear on the subscriber's email invoice, if configured in email templates (not displayed by default).\n####Accounting Code\nA value to help identify plans in internal invoice exports. (Alphanumeric characters only. 50 character limit.) \n####Editable Quantity?\nWhether or not subscribers can choose their own quantity.\n####Billing Cycles\nAutomatically terminate subscriptions after a defined number of billing cycles.\n####Charge\nBase dollar amount charged to a plan's subscribers.\n####Billing Interval\nThe frequency with which a subscriber is billed.\n####One Time Setup\nA one-time charge processed at the time of sign-up.\n####Free Trial\nTime the subscriber is allotted on the plan for free. Definable in days or months. The paid subscription will begin at the end of the trial period.\n####Add-ons\nOptional products that can be rolled into a recurring subscription's invoice.\n####Return URL after Success\nAfter Recurly has been able to successfully subscribe your customer via <a href='/docs/hosted'>the Hosted Page</a>, you can redirect the customer to a specific URL. Use ```{{account_code}}``` and ```{{plan_code}}``` to pass in the subscriber's information. *E.g.*, ```http://example.com/signup/success?account={{account_code}}&plan={{plan_code}}```\n####Return URL after Cancel\n*This setting only affects version 1 of our Hosted Payment Page.* If a customer cancels a subscription via <a href='/docs/hosted'>the Hosted Page</a>, Recurly can redirect the customer to a specific URL. Use ```{{account_code}}``` and ```{{plan_code}}``` to pass in the subscriber's information. *E.g.*, ```http://example.com/signup/cancel?account={{account_code}}&plan={{plan_code}}```\n####Bypass Recurly Confirmation\nIf selected, the customer will be sent directly to your **Return URL after Success** upon success, bypassing Recurly's hosted confirmation page.\n\n\n### Add-ons\n\nAn add-on is a charge billed each billing period in addition to a subscription’s base charge. Each plan may have one or more add-ons associated with it. You’ll define your add-ons when creating or editing plans.\n\nSubscribers can use the Hosted Payments Pages to view and select from the available add-ons. API users can specify add-ons when creating or updating subscriptions.\n\nAdd-ons can be customized with the following properties:\n\n####Add-on Name\nDescribes your add-on and will appear in subscribers' invoices. (255 characters limit.)\n####Add-on Code\nIdentifies the add-on in Recurly. Must be unique per plan. (50 character limit.)\n####Price\nAmount to bill for this add-on\n####Editable Quantity?\nWhether or not a customer can choose their own add-on quantity.\n\n## Updating and Deleting Plans\n\nEditing a plan will change the subscription terms for new subscribers only—existing subscribers will continue with the plan terms present at the time of their signup.\n\nDeleting a plan will prevent customers from subscribing to a plan. Existing subscriptions will continue to renew.\n\n## Setup Fees\n\nSetup fees are a one-time transaction charged automatically at the beginning of a subscription billing cycle. For plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a plan.\n\n## Free Trials\n\nplans have an optional trial period that may be specified in days or months. The paid subscription will begin at the end of the trial period.\n\nWhen Recurly processes a new subscription request, it will attempt to charge the full subscription price for subscriptions without a trial. If the subscription has a trial, Recurly will attempt to validate the credit card using a $1.00 authorization (and will immediately void the transaction). If the subscription is canceled any time before the end of the trial, the account will not be charged and the subscription will expire at the end of the trial. Otherwise, the subscription will be billed normally at the end of the trial.\n\nRecurly does not allow accounts to have trial subscriptions without a valid credit card. If you choose to offer trials without credit cards, your application can track the state of the trial and then make the subscribe API calls to Recurly when the trial ends.\n\n## Billing Information Required\n\nRecurly requires valid billing information on an account before a subscription can be applied. We recommend tracking free trials or free subscribers outside of Recurly and adding them into the Recurly interface only when they are ready to become paying subscribers.\n\n## Hosted Payment Pages\n\nBy default, every plan created inside of Recurly will have its own Hosted Payment Page. This is a Recurly-hosted checkout page customers can use to purchase a specific plan. When inspecting a plan's details page, click **View** to open that plan's Hosted Payment Page.  Please [see our Hosted Payment Page documentation][1] for more information on configuring this view.","excerpt":"A plan tells Recurly how often and how much to charge your customers. Plans can be created with free trials, optional products (called add-ons), setup fees, and more. Merchants can create an unlimited amount of plans in their Recurly site.","slug":"plans","type":"basic","title":"Plans & Add-ons"}

Plans & Add-ons

A plan tells Recurly how often and how much to charge your customers. Plans can be created with free trials, optional products (called add-ons), setup fees, and more. Merchants can create an unlimited amount of plans in their Recurly site.

## Dashboard Your [plans dashboard][1] contains a list of plans defined in your Recurly account. You can click on any plan name to view detailed plan information, edit the plan, or link to that plan's [Hosted Payment Page][2]. [1]: https://app.recurly.com/go/plans [2]: /docs/hosted ## Creating a Plan From your main plan page, click **New Plan**. To create a new plan you'll need to define the following parameters: ####Plan Name This name describes your plan and will appear on <a href='/docs/hosted'>the Hosted Payment Page</a> and the subscriber's invoice. (255 character limit.) Please note that your payment gateway may also place limitations on your subscription name, so it may be best to avoid special characters without checking with your gateway provider. ####Plan Code This is the plan's unique Recurly identifier and is used in <a href='/docs/hosted'>Hosted Payment Page</a> URLs and to fetch plans via <a href='https://dev.recurly.com'>the API</a>. (Alphanumeric characters only. 50 character limit.) ####Plan Description A description of the plan that will appear on the subscriber's email invoice, if configured in email templates (not displayed by default). ####Accounting Code A value to help identify plans in internal invoice exports. (Alphanumeric characters only. 50 character limit.) ####Editable Quantity? Whether or not subscribers can choose their own quantity. ####Billing Cycles Automatically terminate subscriptions after a defined number of billing cycles. ####Charge Base dollar amount charged to a plan's subscribers. ####Billing Interval The frequency with which a subscriber is billed. ####One Time Setup A one-time charge processed at the time of sign-up. ####Free Trial Time the subscriber is allotted on the plan for free. Definable in days or months. The paid subscription will begin at the end of the trial period. ####Add-ons Optional products that can be rolled into a recurring subscription's invoice. ####Return URL after Success After Recurly has been able to successfully subscribe your customer via <a href='/docs/hosted'>the Hosted Page</a>, you can redirect the customer to a specific URL. Use ```{{account_code}}``` and ```{{plan_code}}``` to pass in the subscriber's information. *E.g.*, ```http://example.com/signup/success?account={{account_code}}&plan={{plan_code}}``` ####Return URL after Cancel *This setting only affects version 1 of our Hosted Payment Page.* If a customer cancels a subscription via <a href='/docs/hosted'>the Hosted Page</a>, Recurly can redirect the customer to a specific URL. Use ```{{account_code}}``` and ```{{plan_code}}``` to pass in the subscriber's information. *E.g.*, ```http://example.com/signup/cancel?account={{account_code}}&plan={{plan_code}}``` ####Bypass Recurly Confirmation If selected, the customer will be sent directly to your **Return URL after Success** upon success, bypassing Recurly's hosted confirmation page. ### Add-ons An add-on is a charge billed each billing period in addition to a subscription’s base charge. Each plan may have one or more add-ons associated with it. You’ll define your add-ons when creating or editing plans. Subscribers can use the Hosted Payments Pages to view and select from the available add-ons. API users can specify add-ons when creating or updating subscriptions. Add-ons can be customized with the following properties: ####Add-on Name Describes your add-on and will appear in subscribers' invoices. (255 characters limit.) ####Add-on Code Identifies the add-on in Recurly. Must be unique per plan. (50 character limit.) ####Price Amount to bill for this add-on ####Editable Quantity? Whether or not a customer can choose their own add-on quantity. ## Updating and Deleting Plans Editing a plan will change the subscription terms for new subscribers only—existing subscribers will continue with the plan terms present at the time of their signup. Deleting a plan will prevent customers from subscribing to a plan. Existing subscriptions will continue to renew. ## Setup Fees Setup fees are a one-time transaction charged automatically at the beginning of a subscription billing cycle. For plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a plan. ## Free Trials plans have an optional trial period that may be specified in days or months. The paid subscription will begin at the end of the trial period. When Recurly processes a new subscription request, it will attempt to charge the full subscription price for subscriptions without a trial. If the subscription has a trial, Recurly will attempt to validate the credit card using a $1.00 authorization (and will immediately void the transaction). If the subscription is canceled any time before the end of the trial, the account will not be charged and the subscription will expire at the end of the trial. Otherwise, the subscription will be billed normally at the end of the trial. Recurly does not allow accounts to have trial subscriptions without a valid credit card. If you choose to offer trials without credit cards, your application can track the state of the trial and then make the subscribe API calls to Recurly when the trial ends. ## Billing Information Required Recurly requires valid billing information on an account before a subscription can be applied. We recommend tracking free trials or free subscribers outside of Recurly and adding them into the Recurly interface only when they are ready to become paying subscribers. ## Hosted Payment Pages By default, every plan created inside of Recurly will have its own Hosted Payment Page. This is a Recurly-hosted checkout page customers can use to purchase a specific plan. When inspecting a plan's details page, click **View** to open that plan's Hosted Payment Page. Please [see our Hosted Payment Page documentation][1] for more information on configuring this view.