A Chargebee subscription connects a customer record to products/services. It describes what the customer has signed up for and how often they're charged for it. The essential components of a subscription are:
- Aplan-item price.
- Any addon- and charge-item prices applied to the subscription.
- Anycoupons applied.
- Anydiscounts applied.
The charges in a subscription are billed via invoices.
Sample SubscriptionJSON
API Index URL
Subscriptions attributes
The unique identifier of thesubscriptionresource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.
NoteIn the event that the subscription resource istransferred along with its associatedcustomer resource to a different business entity, Chargebee assigns a new random value as theid for the subscription. The original identifier is preserved for the transferred copy of thesubscription resource. (See also:Mechanics of business entity transfer.)
Specifies the length of each billing cycle (or term) of the subscription, expressed in the unit defined bybilling_period_unit.
Specifies the unit used to measure thebilling_period.
Applicable only for 'future' subscriptions. The scheduled start time of the subscription.
End of the trial period for the subscription. Presence of this value for 'future' subscription implies the subscription will go into 'in_trial' state when it starts.
- When the subscription is not on a contract term: this value is the number of billing cycles remaining after the current cycle, at the end of which, the subscription cancels.
- When the subscription is on acontract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.
The decimal representation of the quantity of the addon. Returned for quantity-based plans whenmulti-decimal pricingis enabled.
The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned whenmulti-decimal pricingis enabled.
Identifier of the customer with whom this subscription is associated.
Current state of the subscription
The subscription is scheduled to start at a future date.
The subscription is in trial.
The subscription is active and will be charged for automatically based on the items in it.
The subscription will be canceled at the end of the current term.
The subscription ispaused.The subscription will not renew while in this state.
The subscription has been canceled and is no longer in service.
Thetransferredstatus will be reflected on the source business entity's subscription attribute once thecustomer transferactivity is completed successfully.
Start of the trial period for the subscription. Presence of this value forfuturesubscription implies the subscription will go intoin_trialstate when it starts.
Applicable only whenEnd-of-trial Actionhas been enabled for the site. Whenever the subscription has a trial period, this attribute (parameter) is returned (required) and specifies the operation to be carried out for the subscription once the trial ends.
This is the default value. The actionconfigured for the siteat the time when the trial ends, takes effect.
The actionconfigured for the siteat the time when the trial ends, takes effect.
The subscription activates and charges are raised for non-metered items.
The subscription cancels.
Start of the current billing period of the subscription.
End of the current billing period of the subscription. Subscription is renewed immediately after this.
The date/time at which the next billing for the subscription happens. This is usually right aftercurrent_term_endunless multiple subscription terms were invoiced in advance using theterms_to_chargeparameter.
Time at which the subscription was started. Isnullforfuturesubscriptions as it is yet to be started.
Time at which the subscriptionstatuslast changed toactive.For example, this value is updated when anin_trialorcancelledsubscription activates.
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same asbilling_cyclesor a custom value depending on thesite configuration.
Iftrue, ignores thehierarchy relationshipand uses customer as payment and invoice owner.
When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in thepausedstate, it is the date/time when the subscription was paused.
For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.
Time at which subscription was cancelled or is set to be cancelled.
The reason for canceling the subscription. Set by Chargebee automatically.
Not Paid
No Card
Fraud Review Failed
Non Compliant EU Customer
Tax Calculation Failed
Currency incompatible with Gateway
Non Compliant Customer
The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.
Version number of this resource. Theresource_versionis updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
The subscription has anadvance invoicing schedule.
Indicates whether a change is scheduled on the subscription.
Note
WhenRamps are enabled with compatibility mode, this attribute indicates whether one or more ramps are scheduled for the subscription. For more details, seeRamps API compatibility mode.
Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.
The free_quantity_in_decimal as set for the plan. Returned for quantity-based plans whenmulti-decimal pricingis enabled.
The decimal representation of the total amount for the item, in major units of the currency. Always returned whenmulti-decimal pricingis enabled.
This is the date/time at which the most recent cancellation schedule for the subscription was created in Chargebee. Applicable only forcancelledsubscriptions or subscriptions that are scheduled for cancellation.
The subscription channel this object originated from and is maintained in.
The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.
The object data is synchronized with data fromin-app subscription(s)created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.
The object data is synchronized with data fromin-app subscription(s)created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
TheNet Dvalue explicitly set for this subscription. Net D is the number of days within which any invoice raised for the subscription must be paid. When an invoice is raised, and this value is unavailable, the net_term_days defined atthe customer levelis considered.
Note: Present only when thesubscription has beentransferred between business entities.
Represents theid of the active version of thesubscription resource.
TipIf theid andactive_id of asubscription resource are the same, this indicates that you are working with the active version of thatsubscription resource.
Total number of invoices that are due for payment against the subscription.Note:Not supported ifconsolidated invoicingis enabled, or when the subscription is for the customer who is inhierarchy, and the parent of this customer owns and pays for the invoices of the subscription. It is also worth noting that the consolidated invoice amount is not included in the calculation ofdue_invoices_count.
Time since this subscription has unpaid invoices.Note:Not supported ifconsolidated invoicingis enabled, or when the subscription is for the customer who is inhierarchy, and the parent of this customer owns and pays for the invoices of the subscription.
Total invoice due amount for this subscription. The value depends on thetype of currency.Note:Not supported ifconsolidated invoicingis enabled, or when the subscription is for the customer who is inhierarchy, and the parent of this customer owns and pays for the invoices of the subscription. It is also worth noting that the consolidated invoice amount is not included in the calculation oftotal_dues.
Monthly recurring revenue for the subscription. Updated asynchronously, this value catches up with changes to the subscription in less than a minute. The value depends on thetype of currency.Note:This may not return accurate values since updated asynchronously.
Exchange rate used for base currency conversion.This value is updated to therate configuredon your site each time any change is made to the subscription.
The currency code (ISO 4217 format) of the site's base currency.
A customer-facing note added to all invoices associated with this subscription. This note is one amongall the notesdisplayed on the invoice PDF.
A collection of key-value pairs that provides extra information about the subscription.
Note:There's a character limit of 65,535.
Indicates that the subscription has been deleted when the value istrue.You can retrieve a deleted subscription using thelist operation.
The date-time at which the subscription change is scheduled to happen.
NoteThis attribute is not returned when the change is scheduled to happen at the end of the current term.
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app inSettings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation.Must be passed if set as mandatory in the app. The codes are case-sensitive
The period of time by which the first term of the subscription is extended free of charge. The value is expressed in the time unit specified byfree_period_unit. For example,3 withfree_period_unit =month means 3 free months are added to the first term.
The time unit forfree_period.
Charge based on day(s)
Charge based on week(s)
Charge based on month(s)
Charge based on year(s)
Indicates whether the invoices for this subscription are generated with apendingstatus. This attribute is set totrue automatically when the subscription has item prices that belong tometered items.You can also set this totrue explicitly using thecreate/update subscription operations. This is useful in the following scenarios:
- When tracking usages and calculating usage-based charges on your end. You can then add them to the subscription as aone-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription.Applicable only whenMetered Billing is enabled for the site
Set tofalseto override for this subscription, thesite-level settingfor auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute has a higher precedence than the same attribute at thecustomer level.
The unique ID of thebusiness entityof this subscription. This is always the same as thebusiness entityof the customer.
Indicates whether the subscription should be decommissioned when it is canceled. If set totrue all subscription operations will be disabled except deletion.
Note: Decommission operation is irreversible. Once set totrue it cannot be updated tofalse and thus subscription will remain decommissioned permanently.
The pricing details ofsubscription_itemswhich havepricing_modelastiered,volumeorstairstep.
Specify limits on how credits and excesspayments are applied to individual invoices for the subscription.
Prerequisite
- Credit flexibility must be enabled for the site.
Constraints
- These limits do not apply toconsolidated invoices.
List ofdiscountscurrently attached to the subscription.
Note
- Discounts of
duration_typeone_timeare removed from the list after a single application to the subscription. - Discounts of
duration_typelimited_periodare removed from the list once the specifiedperiodexpires since their attachment to the subscription.