Docs
Subscriptions connect your customers to your products or services they opt into on a recurring payment basis. They specify what the customer has subscribed to and the frequency of their recurring charges.
Each subscription must include a plan. Currently, a single subscription cannot have more than one plan. Optionally, it can also incorporate one or more associated addons, charges, coupons, and discounts.
Chargebee offers two billing frequency options for subscriptions:
Plan-based billing (default): Subscriptions are billed based on the billing period defined in the plan.
Multi-frequency billing: Subscriptions are billed according to the billing period of each recurring item price within the subscription, whether it's a plan or addon. Note that a single subscription can hold multiple addons, but not more than one plan.
The selection of the billing frequency option is configured at the site level.
With plan-based billing, the billing frequency of the plan determines the subscription's billing frequency. This default method simplifies subscriptions' offers with a fixed and regular billing schedule.
Consider the following price points:
| Name | Type | Price | Billing Period |
|---|---|---|---|
| 1-Year Plan | Plan | $1000 | 1 year |
| 2-Month Addon | Addon | $100 | 2 months |
If a subscription starts on January 1, 2024, with these price points, the billing schedule under plan-based billing would be:
| Billing Cycle # | Date | Billed Items | Invoice Amount |
|---|---|---|---|
| 1 | Jan 1, 2024 | Plan: $1000, Addon: $600* | One invoice for $1600. |
| 2 | Jan 1, 2025 | Plan: $1000, Addon: $600* | One invoice for $1600. |
**Calculation:
Price of addon = $100
Billing period of addon = 2 months
Annual price of addon = ($100 x (12/2)) = $600
While creating or updating a subscription, Chargebee ensures a plan is selected, along with any compatible addons or charges. Compatibility is based on matching currencies and, for plan-based billing, whether the addon's billing frequency is a divisor of the plan's billing frequency.
The following table illustrates this:
| Plan's Billing Frequency | Compatible Addon Billing Frequency | Example |
|---|---|---|
| Day-based | Day-based. The addon's billing frequency must be a divisor of the plan's billing frequency. | If the plan's billing frequency is 10 days, then the billing frequency of the addons (in days) can be any of the following: 10, 5, 2, or 1. |
| Week-based | Week or day-based. The addon's billing frequency (in days) must be a divisor of the plan's billing frequency (in days). | If the billing frequency of the plan is 2 weeks, then the billing frequency of the addons can be any of the following: 2 weeks, 1 week, 14 days, 7 days, 2 days, or 1 day. |
| Month-based | Month-based. The addon's billing frequency (in months) must be a divisor of the plan's billing frequency (in months). | If the billing frequency of the plan is 6 months, then the billing frequency of the addons (in months) can be any of the following: 6, 3, 2, or 1. |
| Year-based | Year or month-based. The addon's billing frequency (in months) must be a divisor of the plan's billing frequency (in months). | If the billing frequency of the plan is 2 years, then the billing frequency of the addons can be any of the following: 2 years, 1 year, 24 months, 12 months, 8 months, 6 months, 4 months, 3 months, or 1 month. |
Private Beta
Multi-frequency billing is in Private Beta. Please reach out to the Chargebee support to enable this feature.
In multi-frequency billing, the subscription is billed in accordance with the billing period of each recurring item in the subscription. Note that a single subscription can hold multiple addons, but not more than one plan.
Distributes costs over smaller intervals, reducing upfront expenses for customers, aiding sales teams in closing deals, and minimizing cart abandonment among self-serve customers.
Bills each recurring price point independently according to its billing cycle.
Allows for longer duration plans with overages billed more frequently via metered addons. For example, you can create an annual plan with a monthly metered addon for which usage gets billed on a monthly basis for the metered addon.
Consider the following price points:
| Name | Type | Price | Billing Period |
|---|---|---|---|
| 1-Year Plan | Plan | 1000 | 1 year |
| 2-Month Addon | Addon | 100 | 2 months |
If a subscription starts on January 1, 2024, with these price points, the billing schedule under multi-frequency billing would be:
| Billing Cycle # | Date | Billed Items | Invoice Amount(s) |
|---|---|---|---|
| 1 | Jan 1, 2024 | Plan: $1000, Addon: $100 | $1100. |
| 2 | Mar 1, 2024 | Addon: $100 | $100. |
| 3 | May 1, 2024 | Addon: $100 | $100. |
| 4 | Jul 1, 2024 | Addon: $100 | $100. |
| 5 | Sep 1, 2024 | Addon: $100 | $100. |
| 6 | Nov 1, 2024 | Addon: $100 | $100. |
| 7 | Jan 1, 2025 | Plan: $1000, Addon: $100 | $1100. |
While creating or updating a subscription, Chargebee ensures a plan is selected, along with any compatible addons or charges. Compatibility is based on matching currencies and, for multi-frequency billing, whether the addon's billing frequency is less than or equal to the plan's billing frequency.
The following table illustrates this:
| Plan's Billing Frequency | Addon's Billing Frequency | Permissibile? |
|---|---|---|
| 1 month | 1 month | Yes. 1 month is 28-31 days, which is always less than or equal to a month. |
| 1 year | 6 months | Yes. 6 months is less than a year. |
| 1 month | 5 weeks | No. 5 weeks is more than a month. |
| 1 month | 29 days | No. For February, 29 days is often more than a month. |
Ensure that you read and understand the following points before enabling the Multi-frequency billing feature on your Chargebee Billing site:
Addons of different billing frequencies will only be available if the addon's billing frequency is lesser than the plan's billing frequency. Click here for more information.
Chargebee Billing features like Quotes, Contract Terms, Advance Invoicing, Gift Subscriptions, RevenueStory, and Subscription Ramps are incompatible with multi-frequency billing and must therefore be disabled before enabling multi-frequency billing. The Regenerate Invoice operation is not supported for subscriptions via Chargebee application and API, when multi-frequency billing is enabled.
Currently, you will not be able to allow your customers to schedule any changes in the subscription at the end of addons term via Chargebee hosted pages portal.
Dunning flows for the addon invoices will follow the same dunning configurations at the subscription level. It is recommended to keep the setting for When dunning period ends, what happens to the subscription as Retain as active. Given that plan invoices could be raised annually and addon inovices could be raised monthly, if the setting is configured to Cancel the subscription, the subscriptions will be cancelled even when an addon invoice payment fails. For example, a customer pays 10,000$ for a yearly plan, and after two days avails a monthly addon for 100$ for which the payment fails. With the dunning configuration set to cancel the subscription, the subscription will get cancelled due to the addon payment failure, even though there's a yearly plan invoice that was successfully paid.
You will be able to schedule the following changes to the addons of different billing frequency in a subscription:
Add an addon on a specific date or next renewal.
Remove an addon on a specific date or next renewal.
Increase or decrease the price and quantity of the addon on a specific date or next renewal. Note that the "Next Renewal" setting aligns to the renewal of the associated plan in the subscription, but not the addon for which you're scheduling the changes. If you want to schedule the changes for the addon's renewal date, use the "specific date" option. You cannot choose which item's renewal date should the changes be applicable on, wherein we recommend that you choose a specific date if you want to schedule it on a certain date.
The subscription details page in Chargebee displays the details of the subscription along with its status. The following are various statuses of a subscription:
Future: Subscriptions that are yet to go into trial or active state on the specified date in the future.
In Trial: Active subscriptions that are in trial mode.
Active: Active subscriptions that are charged based on plan, addons, and billing period.
Non Renewing: Subscriptions that are scheduled to cancel and will no longer renew.
Paused: Active subscriptions that are stopped temporarily.
Cancelled: Inactive subscriptions that will no longer renew. You can configure how charges and credits are handled on cancellation.
To view all subscriptions in your Chargebee site, click Subscriptions. This page lists all your subscriptions along with a summary of each subscription.
This page displays options such as filtering views, sending emails to customers, exporting the list of subscriptions to CSV file, and downloading shipping labels.
Select one or more subscriptions to perform bulk actions such as delete, change term end, and cancel subscriptions.
Only Admins can perform Bulk Actions such as bulk delete, changing end of term for multiple subscriptions together, and bulk cancel.
Following are the bulk actions that can be performed from the subscription details page:
Delete: Deletes the subscriptions.
Change Term End: Changes the end date of the subscription. On selecting this option, the Change Term End dialog will open. Enter the necessary details and click Apply Changes. This operation affects any upcoming ramps on the subscription by moving the ramps to draft status. If it is necessary to adjust subscription ramps to align with this operation, delete and recreate them as needed.
Cancel Subscription: Cancels the selected subscriptions. Enter the necessary details in the Cancel Subscriptions dialog and click Apply Changes. To cancel subscriptions, select More > Cancel Subscription option. Read more on Canceling subscriptions.
To create a new subscription in your Chargebee site, follow these steps:
Click Subscriptions > Create New Subscription.
In the Pick a Customer dialog, select the customer record for which you are creating this subscription. You can also create a new customer before creating this subscription.
The Create a Subscription page allows you to create a new subscription. The subscription ID field is auto generated and is used to uniquely identify the subscription. Fill out the details described in the upcoming steps to create a new subscription.
The Subscription Info section collects information related to the plan you would like to subscribe the customer to.
Click the Product Family drop down and select the product family of the plan for which you are creating this subscription.
Click + Add Plan and select the plan. The Add Plan dialog displays all the existing plans/addons for selection. Metered components can be easily differentiated using the metered icon.
Select the Currency and the Billing frequency of the plan, and click Add. You can modify this selection by clicking the more icon next to the plan to change the Plan or Frequency.
If Price overriding is enabled in your site, you can edit the price of the plan as required.
Click +Add Recurring Addon to attach addons to the subscription.
Click +Add Charge to attach a charge to the subscription. Select an event when the charge should be applied.
Click +Add coupon or +Add coupon code to apply coupon.
As you add the subscription information, a sneak-peek of the immediate charges for the subscription gets displayed for your reference on the right side. You can click See breakdown to view the complete breakdown of immediate charges.
The Billing Info section captures information related to the billing of the subscription.
Start Date is when the subscription starts for the customer. It is a date or time depending on the billing mode of your site. Start date/time given has an impact on the statuses the subscription can have:
Billing Cycles field is used to set the number of times a customer will be charged. Here, you can specify a different value for the no. of billing cycles than what you have already configured in the plan. The value entered in the new subscription will override the value that was already configured in the plan.
Auto-collection option decides whether the payments for the invoices generated for the subscription are charged automatically. You can select one of the following options:
PO Number uniquely identifies a purchase order and is generally defined by the buyer. You can specify the PO Number for the subscription. More on that here.
Assigning a Payment Method: If a customer has multiple payment methods available, Chargebee supports assigning a payment method exclusively to a particular subscription. If assigned, the payment method will be tried for all charges against the subscription. Find out how to assign a payment method to a subscription here.
The Invoicing Options section captures information related to invoicing the subscription. You can choose to generate an invoice immediately or add to unbilled charges.
The Shipping address section captures the shipping information related to the subscription, if you are dealing with shippable physical goods. You can either apply the billing address of the customer for shipping, or add the shipping address details.
Click Create.
While creating a subscription record, you can enable the Free period setting to offer a fixed number of days/weeks/months/years for the first billing cycle of the subscription, free of charge.
If your plan does not have a trial period, you can create the subscription by setting Auto Collection to OFF. The subscription will be created as an offline subscription. Once the subscription is created, you can add the card details using the Add Credit Card option within the subscription.
Another way of creating subscriptions using plans without a trial period is by using the plan's hosted page URL. This allows you to enter the credit card details while creating the subscription.
When you open up an existing subscription, there are several details you can view and actions you can perform. The subscription provides you with all the details like customer info, CC info, due amount, trial days remaining (if in trial). You can also see subscription info, non-recurring items, address, current term charges/credits, invoices and transactions.
You can perform the following operations from the subscription details page:
The Edit Subscription option can be accessed from one of the following places:
It allows you to change one or more of the following aspects of the subscription such as:
In plan-based billing, when editing a subscription that has ramps scheduled, the ramps move to draft status if the billing frequency of the subscription is changed.
Applying Changes: In the Apply Changes section you can choose to bring the changes into effect in three timelines as follows:
This option lets you add a one-time addon to the subscription. Learn more.
While updating a subscription record via Chargebee Billing User Interface(UI) or API, you can have the mandatory add-ons associated with the old plan removed automatically by enabling the setting Remove mandatory addons from old plan during subscription plan update.
To enable this setting on your Chargebee Billing site, follow the steps below:
After the setting is enabled, mandatory add-ons associated with any old plan will be removed automatically during subscription update done via Chargebee Billing UI or API.
Enabling this setting does not remove the mandatory addons automatically when your customers update subscriptions via self-serve portal. They need to remove the mandatory addons manually. This allows your customers to make an informed decision while modifying subscriptions.
This option lets you add an additional charge to the subscription. It is a one-time charge and does not recur. Learn more.
If you have enabled Metered Billing in your Chargebee site and when the subscription contains metered components, you can use this option to add usage data to the subscription. Click Add Usage, specify the date and time for when the usage is being added and specify the usage units in Quantity field.
You can also do a bulk import of multiple usage data for multiple subscription records using the Bulk Operations feature (for Subscriptions) in Chargebee.
This option can be used to apply and redeem additional coupons on an existing subscription. Only coupons that are applicable to the plan in this subscription will be displayed.
This option allows you to send an email with an auto-generated link that the subscriber can use to add/update their card details. If you use Chargebee's single-page checkout, then please make sure that you've configured the Update Payment Method Page redirect URL that users will be redirected to once they've successfully updated their payment method details.
This option appears only when the subscription is in "Future" state. You can change when the subscription should start using this option. If you need to start the subscription immediately (or on the current day, if your Chargebee site is on day-based billing mode), you can choose the current time/date.
If the subscription was created through the API and a trial period was specified, changing the start date will automatically remove that trial period. In this case, only the plan's trial period (if present) will be considered. Otherwise, the subscription will go into "Active" state.
The Change Next Billing Date option will appear on active subscriptions and is used to change the next renewal date/time. You can change the date/time to a later or an earlier point in time. The subscription will update on the specified date/time.
This option will only appear on trial subscriptions. This can be used to extend the trial period if needed.
The subscription details page also displays the following sections:
This option allows you to add a new credit card number if it is not available or update it if there is a change.
This option is used to enter the customer's shipping address. Once you have added this information, it will appear on the subscription as a new section. You can edit all the address fields except for the Label used. You can delete the address, and add a new one if needed.
If you've enabled any of the billing address fields, you will see this option, and you can use this to add/edit your customers' billing address.
This option can be used to cancel or re-activate a subscription. You can cancel a subscription immediately or at the next renewal. Only subscriptions with credit card info can be reactivated once it is canceled. Learn more.
You can override the price point of a plan while creating or editing the subscription when price overriding is enabled in your Chargebee site.
To change the price for an existing subscription, follow these steps:
If proration is enabled, a new invoice is generated for the subscription at the new price. Refundable credits are raised for the remaining period of the subscription at the old price and applied to the new invoice.
When an invoice is generated with incorrect details, such as an error in the line items, incorrect shipping and billing address etc, you can void that particular invoice and regenerate it using the Regenerate Invoice option.
Refer Regenerate Invoice to learn more about this.
If you wish to delete a Subscription in Chargebee, open the specific Subscription's details page and click the Delete Subscription option available on the actions panel.
This operation is irreversible - all data related to the Subscription, such as Transactions and Invoices, get deleted.
The numbers in the following reports will get modified when a Subscription is deleted:
Three settings govern the automatic collection of payments for invoices using online payment methods:
The following table shows how the settings work in tandem with invoice and subscription statuses.
| Payment collection when payment method is added toggle | Auto-Collection | Invoice Status | Subscription Status | Action |
|---|---|---|---|---|
| Disabled | On or Off | Payment Due | Any | Payment collected on next dunning retry. |
| Enabled | On or Off | Payment Due | Any | Payment is collected immediately even if the next dunning retry is only due later. |
| Enabled or Disabled | Off | Posted | Any | Payment is not collected. |
| Enabled or Disabled | On | Posted | Any | Payment is collected at the end of the payment term. |
| Enabled or Disabled | Off | NA | In trial | Payment is not collected. |
| Enabled or Disabled | On | NA | In trial | Payment is collected at the end of the trial period. |
Product Entitlements in Chargebee allow you to control the features accessible to customers based on the plan or addon they subscribe to. When a feature is activated and mapped to a plan or addon, it is automatically available for all subscriptions of the plan or addon.
You can view entitlements in subscriptions. The feature name, entitlement level, and status are displayed in the entitlement section of the subscription details page.
You can even override the entitlement level for each subscription, to add or change the entitlements to features that are not part of the associated plan or addon. Learn more.
1) Can I add coupons to the subscriptions on the customer's request?
Yes, you can add coupons to the subscription in your Chargebee on customer's request.
There are three scenarios where you can add the coupon:
2) Is it possible to send a quote to a customer which they can review before signing up?
Yes, enable Quotes in Chargebee to send pricing quotes or proforma invoices to your customers.
3) Why can't I find a way to add the time when I specify details such as "subscription start date", "change next billing date"?
The billing mode of your Chargebee site governs whether billing is done to-the-calendar-day or to-the-millisecond. If you have day-based billing mode set for your site, you will not be able to make changes to the billing-related times to a granularity lesser than a calendar day.
Articles & FAQ