Docs

Working with Subscriptions 

A Chargebee subscription connects your customer to your products/services. It determines what your customer has signed up for and how often they're recurringly charged for it.

A subscription is created when a customer signs-up for a plan. Any associated addons or coupons also become a part of it. If the products are shippable, then shipping orders are also created against it.

A Customer record in Chargebee can have any number of subscriptions linked to it, each with its own trial period, pricing, payment options and so on.

Classic UI users can find the relevant content here.

Note
  • On the day of your subscription's renewal, Chargebee will ensure to promptly initiate the renewal process.

Subscription Status 

Future: Subscriptions that will 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 will be charged based on plan, addons and billing period.

Non Renewing: Subscriptions that are scheduled to cancel and will no longer renew.

Paused: Active subscriptions will be stopped temporarily.

Cancelled: Inactive subscriptions that will no longer renew. How charges and credits etc. are handled on cancellation can be configured.

What's in the Subscription Section? 

This section lists all your subscriptions along with a summary of each subscription.

It also gives you options such as filtering views, sending emails, exporting to excel, and downloading shipping labels.

You can perform actions such as delete, change term end, and cancel subscriptions by selecting the subscription. Admins can also perform Bulk Actions such as bulk delete, changing term end for multiple subscription altogether, and bulk cancel.

To perform these actions:

  • Click the Bulk Actions (…) button.
  • Select the customers and select the operation to be performed.

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.

Cancel Subscription: Cancels the selected subscriptions. Enter the necessary details in the Cancel Subscriptions dialog and click Apply Changes. Read more on canceling subscriptions. To cancel subscriptions, select More > Cancel Subscription option.

Creating Subscriptions in Chargebee User Interface 

Click Create Subscription on the subscriptions index page to get started. Select the customer record to which the subscription needs to be associated.

Note

If it is for a new customer, click Create new customer. You need to then fill in the customer details to create a customer record and then create the subscription.

Here are the details you need to fill out to create a new subscription:

Subscription Info 

The ID field is used to uniquely identify the subscription. Refer to our API  for more details.

The Subscription Info section captures information related to the plan you would like to subscribe the customer to:

  • The Plan Name and Quantity fields are used to select the plan that you are selling as well as the quantity. The 2 fields are mandatory. You can append the plan with additional addons and coupons if applicable.

  • The Unit Price fields allow you to override the price of the plan and the addon that you have selected for this subscription. This is only allowed in applicable cases.

  • You can also specify the PO Number in this section. More on that here.

See also
  • Plans and addons for more information on defining your products/services in Chargebee together with their pricing models.
  • Refer to multi-decimal support for more information on charging your customers in fractional amounts or charging for fractional quantities.

If you select a tiered/volume/stairstep priced plan or addon while creating/editing a subscription, you can see the price-breakup by clicking View tier breakdown below the plan.

Note

When creating a new subscription in your Chargebee user interface, the plan selected should have at least 1 trial day. This is because 0 trial day plans would need credit card details to process the charge immediately.

Billing Info 

The Billing Info section captures billing information as relating to the plan you have specified and the customer's billing and shipping information:

Start Date/Time

Start Date/Time is when the subscription starts for the customer. It is a date or time depending on the billing mode of your site. You can set the subscription to start Immediately or Choose Date on which the subscription starts/started. Start date given has an impact on the statuses the subscription can have:

Active: The customer is using the subscription and is paying for it. An invoice will be generated on the date/time the subscription status changes to Active. You can also set the start date/time as a date/time in the past, i.e., the date/time can be any time before the time you're creating the subscription, provided that the date/time falls within the current billing cycle. This will come in handy when you've started providing the service already but are creating the subscription in Chargebee at a later time.

Future: The start date/time is in the future with respect to the date/time the subscription was created. The status will change to Active or Trial on the start date/time mentioned. An invoice will be generated on the date/time the subscription status changes to Active.

In Trial: On the start date/time, if the subscription has a trial period specified, then the status of the subscription will be "In Trial".

Free Period 

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.

Note

Billing Cycles 

This is used to set the number of times a customer will be charged. You can choose between Fixed or Forever billing cycles.

To bill the customer until there is a subscription cancellation or pause, use Forever cycle.

To bill the customer for a certain number of cycles, use Fixed cycle. Here, you can specify a different value as opposed to the number of billing cycles already configured in the plan. The value entered in the new subscription will override the value that was already configured in the plan. More information here.

Auto Collection 

Chargebee supports auto collection at the customer and the Subscription level.

The Auto collection option decides whether the payments for the invoices generated for the subscription are charged automatically.

  • If Auto Collection is turned ON, then Chargebee will charge the customer's payment method (primary or the one assigned to the subscription) automatically when a payment for the subscription is due.

  • If Auto collection is turned OFF, then Chargebee will not automatically charge the customer's payment method when a payment for the subscription is due.

If you haven't configured Auto collection for the subscription, Chargebee will refer to the Auto Collection status at the Customer level to decide when the charge needs to be collected. More on Auto collection for customers.

Note

Configuring Auto collection at the Subscription level overrides the Auto collection setting you have configured at the Customer level.

Assigning 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.

Can I include my Addons during sign up? 

Yes. You can select recurring addons here. Non-recurring addons cannot be added to a plan that has trial days.

Creating Subscriptions for Plans Without Trial Period 

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/bank details using the Add Card/Bank Account option in the subscription's details page.

Another way of creating subscriptions using plans without a trial period is by using the plan's hosted page URL . This will allow you to enter the credit card details while creating the subscription.

Can I Edit an Existing Subscription? 

When you open an existing subscription, there are several details you can view and actions you can perform. The subscription provides you with details such as the plan subscribed to, payment method information, data acquired using custom fields, unbilled charges, configurations and so on. You can also view the subscription related information, non-recurring charges, address, current term charges/credits, invoices and transactions. (The address section will only appear if you add the buyer's address; non-recurring items will appear when a one time charge has been applied using Add One-Time Addon).

Changes can be made using the Action panel on the right.


Action panel lets you perform the following changes:

Action panel lets you perform the following changes:

  • Edit Subscription
  • Create and Send a Quote
  • Request Payment Details
  • Create Quick Charge
  • Add One-Time Addon
  • Add Coupon
  • Bill Future Renewals
  • Pause/Resume Subscription
  • Cancel/Re-Activate Subscription
  • Edit Next Billing Date
  • Delete Subscription

Edit Subscription 

It allows you to change one or more of the following aspects of a subscription:

You can also choose to either apply the changes immediately (the charges may be prorated then), on the next renewal, or even schedule it for a particular day.

Edit Subscription option can be accessed from one of the four places:

  • Customer facing:

    • Portal
  • Merchant facing(In Chargebee user interface):

    • In the customer details page.
    • In subscription details page, on the Actions panel.

Applying Changes 

In the Apply Changes section, you can choose to bring the changes into effect in three timelines,

  1. Immediately
  2. During next renewal(at the end of term)
  3. On a specific date

Immediately bringing the changes into effect also provides you the option to Apply prorated credits and charges to any charge which was generated because of the changes made to the subscription.

During next renewal schedules the changes for the end of term.

On a specific date schedules the changes to take effect only on the set date. This makes the prorate credits and invoicing option unclickable and takes into account the proration setting and unbilled charges setting configured in your Chargebee site. This feature can be enabled only on request, contact support  to get it enabled for your site.

Note
  • Any scheduled change will be overridden if a new change is scheduled. Contact support  if you'd like Chargebee to notify you about the removal of scheduled changes.
  • APIs carrying parameters for proration and unbilled charges will not work in the case of scheduled changes.
See also

Plans and addons for more information on defining your products/services in Chargebee together with their pricing models.

Removing Mandatory Add-ons 

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:

  1. Click Settings > Configure Chargebee > Billing LogIQ > Customers & Subscriptions > Update Subscription.
  2. Click to enable the setting Remove mandatory addons from old plan during subscription plan update > Apply.

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.

Note

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.

Request Payment Method Details 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.

Create and send a quote allows you to create a quote for changing the subscription. Learn more.

Add Card/Bank Account allows you to add a new credit card number or even a bank account if Allow customer to pay via their bank account is enabled. You can also update the details when added.

Add shipping address is used to enter the customer's shipping address. «alter accordingly> You can only change the data in Label field only once, and that's during the first attempt to add shipping address. You can also delete the address, and add a new one if needed.

Add/Update billing address 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.

Cancel/Reactivate Subscription can be used to cancel or re-activate a subscription. You can cancel a subscription immediately, at the next renewal, or even on a specific date. Learn more.

Create Quick Charge lets you add an additional charge to the subscription. It is a onetime charge and does not recur. Learn more.

Add One-time Addon can be used to include an additional non-recurring addon to the subscription. Learn more.

Add Coupon can be used to apply and redeem additional coupons on an existing subscription. Only coupons that are applicable to the subscribed plan are displayed.

Edit Start Date/Time 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 Edit 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.

Edit Trial End Date option will only appear on trial subscriptions. This can be used to extend the trial period if needed.

The subscription details page also has an Activity log that shows you the subscription's history.

Events such as sign up, cancellation and reactivation are shown here.

Use Comments to add information specific to a particular subscription or as a tag that you can use to find subscriptions using filters. The comments section appears at the bottom of the subscription and this option is available for subscriptions, invoices, transactions, plans, addons and coupons.

Can I change/override the plan price for a particular subscription? 

Yes, but price overriding in Chargebee needs to be enabled first.

Also, just like when changing the price of a plan, price change for subscription is only permitted when the plan pricing model for the subscription is flat or per unit.

You can change the price for a new subscription while creating it or for an existing subscription by updating it.

To change the price for an existing subscription:

  1. Navigate to the subscription details page and click on Edit Subscription on the Actions panel.
  2. On the page that appears, you can change the price and, if applicable, the quantity associated with the subscription.

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.

Deleting a Subscription 

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, will be deleted.

The numbers in the following reports will get modified when a Subscription is deleted:

  • Payments
  • New Revenue
  • Signups
  • Activations
  • Cancellations
  • Refunds
Note

The option to delete a Subscription is available only for the role Admin.

You can also delete a Subscription using the Delete a Subscription API .

Finding subscriptions 

You can search for subscriptions using name, id or also by sorting the list based on display name or date in the Chargebee user interface.

There is an advanced filter option included as well to make your search a lot easier.

Invoices and Transactions 

The History section displayed under a subscription contains the details of the invoices and transactions related to the selected subscription. All payments related to the subscriptions are recorded here.

Read more on invoices and transactions.

Automatic payment collection rules 

Three settings govern the automatic collection of payments for invoices using online payment methods:

  • Auto-collection: Can be configured at the customer and subscription level, with the latter taking precedence.
  • Payment collection when payment method is added toggle: Can be configured by navigating to Settings > Configure Chargebee > Billing LogIQ > Payments.
  • Dunning: Automatic retries for payment failures.

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.

FAQs 

1) Can I add Coupons to the Subscriptions on 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:

  • While creating a Subscription: If you are adding a coupon/coupon code on behalf of your Customer while creating a new subscription for them, navigate to Subscription Info in the Create Subscription page, and you will find the option to Add Coupon/Coupon Code.

  • While changing a Subscription: If you're applying the coupon on your Customer's behalf during a Subscription change, you will find the option on Change Subscription (Subscription > Edit Subscription) page.

  • Adding the Coupon/Coupon Code to the Subscription: If you're adding the coupon/coupon code for the customer, at any point of time in the billing cycle, navigate to the respective subscription, and click Add Coupon to add the Coupon/Coupon Code.

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 & FAQs 

Can I exempt selected customers from paying taxes?
Unable to create a subscription: "Cannot create the subscription as there is no valid card on file". How do I proceed?
How to move a subscription from one customer to another?
How to retrieve a coupon Id from the subscription_created webhook event?
Error: Reactivation date is incompatible with plan terms
How do I index into tiers and retrieve tier prices (subscription.item_tiers not working
How to remove addons from a subscription via API in PC 2.0?
How to filter the list the plans in cancelled state by source? Where can I view the source?
How do I get the subscription id from web-hooks during cancel subscription.
How to get notified of my customer's subscription renewal events in Chargebee?
What is the Jump to Section under Customer/Subscription details page?
What is ChartMogul?
Error when removing scheduled cancellation: Billing cycle cannot be lesser than 1
How to manually sync status for in-progress transactions?
Salesforce-Unable to create a quote for any existing subscription for a upgrade in SF
Can I change the plan of an existing subscription on behalf of the customer ?
What happens when the number of billing cycle is 0?
How do I create/manage a subscription with users or licences ?
What's the difference between the subscription created, subscription activated and subscription started events?
How to change next billing for multiple subscriptions?
How to get a list of all subscriptions in the customer details page for Reseller type business- (above 20 subscriptions)?
How do I add or remove coupons in Subscriptions?
How do I remove/change/add an addon to a subscription that already has one or more addon via APIs (PC 1.0)?
How can I delete a subscription in Chargebee?
How can I reactivate a subscription using the APIs?
How do I apply Coupons to subscriptions?
How to check the billing amount before an invoice is generated?
How to retrieve the next billing date of a subscription?
Can we have multiple subscriptions in Chargebee?
How do I change my subscription status from Non-Renewing to Active?
How to enable Proration Settings in Chargebee
How to apply coupon while creating a subscription?
Charge /Invoice one-time fee in Chargebee
Subscription Status as Active when payment failed on renewal
Changing the billing date to a different date
How to change the term end date for a specific subscription?
How to prevent multiple users or subscriptions with the same email address?
Limiting duplicate subscriptions via API
Can I make changes to a subscription at a specific future date?
My customer has added a payment method but they are not being charged automatically for payments. Why is this happening?
How to customize my customer IDs in sequential order?
What happens when Auto collection is switched OFF at the subscription level?
How to replace or remove addons on a subscription via API?
How to change a cancelled subscription to a non-renewing subscription?
How to give my customers the credits for the unused period when there is a subscription change?
Where should I set the billing cycle: plan or subscription level?
How to let my customer select a different plan during reactivation from the portal?
Using account Hierarchy with Chargebee.
How do I restore a deleted Subscription? Undoing Delete operation
How to move a subscription from one customer to another? - with account hierarchy
ChargeBee::InvalidRequestError "customer[company] : wrong value"
Don't provide credit notes while downgrading/changing a subscription
How to create a subscription which will start in future?
How to create an active subscription which will bill in the future?
Generate a report that shows add-ons by customer/subscription
How to change the billing cycles & frequency on an existing subscription?
Regenerate invoice error - "There were errors while submitting"
How do I set a Free Billing Period (manual free trial) for an existing Active subscription?
"You must have one active reason to display on self-serve portal" error
How can I apply multiple Manual discounts via API to an existing subscription?
How does Payment Terms with Auto Collection "On" work?
What are the reasons the invoice will not be generated for non-recurring addons?
How do coupons and taxes work on Chargebee’s checkout page?
Timezone for Subscription filters in Chargebee
How to get the recent subscription of each individual customer via API?
How can I make a subscription change immediately using API?
Subscription Id is not being received in Chargebee response when transaction is created
Is it possible to move the subscription's start date once it's activated?
Error: “Sorry, the operation has been cancelled as it took more than expected time to complete. Please try again after some time.”
Can we apply the setup cost while changing a subscription in PC 1.0 sites?
Edit Subscription Error - Changing subscriptions term/trial period is not allowed
Will a manual discount be shown in the response of the List Subscriptions API?
How to not let existing subscribers receive gift subscriptions.
Estimate API for metered line items
How to create a subscription with a higher first payment and lower subsequent payments?
Is it possible to receive Apple App Store notifications on my server first and then pass them to Chargebee?
Account hierarchy and proration calculation
Maximum number of days for Pause Subscription
How to fetch historical subscription data that is more than 12 months data old?
How to change the plan of a canceled subscription without reactivation?
Is there any customer information shared while using App Stores?
What does this statement mean: "This customer has signed up but has not set up their Self-Serve Portal account."?‌
Error “Subscription is in contract so you cannot pause” while pausing the subscription
Unable to backdate subscription cancellation when a contract term is applied
How to configure self-serve calendar billing for E-Commerce business?
How to create a subscription with a future start date using a plan and a charge and invoice the charge alone on subscription creation using Hosted page URL?
How to add usage via API?
How to add contract terms to an existing subscription without invoicing the un-billed charges
Why do we not send Modified "Next billing date" as an event when using the Bill Future Renewal feature.
Error: The next renewal date cannot be the same as the current renewal date.
Can account hierarchy be overriden at a subscription level?
How to enable Account Hierarchy in Chargebee?
How to add a charge to the upcoming renewal ?
How can I retrieve more than one shipping address for a subscription using retrieve_a_subscription API?
I added metadata to a non-renewing subscription, and the subscription status changed to Active, why?
Was this article helpful?
Loading…