Subscription represents the recurring items a customer has subscribed to. The recurring items can be - plan, addons. It may also contain the discount items like coupons.
Subscriptions are invoiced at the start of every term based on the recurring items and charged immediately against the customer's credit card if 'auto_collection' is turned 'on', otherwise the resulting invoice will be created as 'Payment Due'.
Note: Make sure you choose the correct Field ID and Available APIs combination from the table above. All Product Catalog APIs include Plans , Addons , Coupons , Coupon Sets , Coupon Codes .
Sample SubscriptionJSON
API Index URL
Subscriptions attributes
The currency code (ISO 4217 format ) of the subscription
Amount that will override the Plan's default price. The unit depends on the type of currency .
Amount that will override the default setup fee. The unit depends on the type of currency .
- 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 a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.
Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.
Automatic collection of charges will not be made for this subscription. Use this for offline payments.
The decimal representation of the quantity of the plan purchased. Returned for quantity-based plans when multi-decimal pricing is 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 when multi-decimal pricing is enabled.
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 is paused. The subscription will not renew while in this state.
The subscription has been canceled and is no longer in service.
The transferred
status will be reflected on the source business entity's subscription attribute once the customer transfer
activity is completed successfully. This status is only valid for product catalog 2.0
as the Multiple Business Entity features can only be enabled for product catalog 2.0.
Applicable only when End-of-trial Action has 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 action configured for the site at the time when the trial ends, takes effect.
The action configured for the site at the time when the trial ends, takes effect.
The subscription activates and charges are raised for non-metered items.
The subscription cancels.
Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles
or a custom value depending on the site configuration
.
If true
, ignores the hierarchy relationship
and uses customer as payment and invoice owner.
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 subscription has an advance invoicing schedule .
The free_quantity_in_decimal as set for the plan. Returned for quantity-based plans when multi-decimal pricing is enabled.
The decimal representation of the total amount for the plan, in major units of the currency. Always returned when multi-decimal pricing is enabled.
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 from in-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 from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
This attribute is only valid for product catalog 2.0 as the Multiple Business Entity features can only be enabled for product catalog 2.0.
Total number of invoices that are due for payment against the subscription.
Note:
Not supported if consolidated invoicing
is enabled, or when the subscription is for the customer who is in hierarchy
, 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 of due_invoices_count
.
Time since this subscription has unpaid invoices. Note: Not supported if consolidated invoicing is enabled, or when the subscription is for the customer who is in hierarchy , 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 the type of currency
.
Note:
Not supported if consolidated invoicing
is enabled, or when the subscription is for the customer who is in hierarchy
, 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 of total_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 the type of currency . Note: This may not return accurate values since updated asynchronously.
Exchange rate used for base currency conversion.This value is updated to the rate configured on 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 among all the notes displayed 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 is true.
You can retrieve a deleted subscription using the list operation
.
Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive
Indicates whether the invoices for this subscription are generated with a pending status. This attribute is set to true automatically when the subscription has item prices that belong to metered items.
You can also set this to true explicitly using the create/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 a one-time charge at the end of the billing term.
- When you need to inspect all charges before closing invoices for this subscription. Applicable only when Metered Billing is enabled for the site
Set to false
to override for this subscription, the site-level setting
for 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 the customer level
.
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
Note
Multiple Business Entities is a feature available only on Product Catalog 2.0.