Subscriptions

The unique identifier of the subscription resource. You have the option to specify this value when creating a customer. If not specified, Chargebee automatically generates a unique identifier.

The currency code (ISO 4217 format ) of the subscription

Specifies the length of each billing cycle (or term) of the subscription, expressed in the unit defined by billing_period_unit.

Specifies the unit used to measure the billing_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 a contract term: this value is the number of billing cycles remaining in the contract term after the current billing cycle.

Purchase order number for this subscription.

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

The decimal representation of the quantity of the addon. 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.

Identifier of the customer with whom this subscription is associated.

Current state of the subscription

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

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.

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 after current_term_end unless multiple subscription terms were invoiced in advance using the terms_to_charge parameter.

The time at which the subscription was created.

Time at which the subscription was started. Is null for future subscriptions as it is yet to be started.

Time at which the subscription status last changed to active. For example, this value is updated when an in_trial or cancelled subscription activates.

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.

When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, 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.

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. The resource_version is 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.

Timestamp indicating when the item was last updated.

The subscription has an advance invoicing schedule .

Indicates whether a change is scheduled on the subscription.

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 when multi-decimal pricing is enabled.

The decimal representation of the total amount for the item, in major units of the currency. Always returned when multi-decimal pricing is enabled.

This is the date/time at which the most recent cancellation schedule for the subscription was created in Chargebee. Applicable only for cancelled subscriptions or subscriptions that are scheduled for cancellation.

The subscription channel this object originated from and is maintained in.

The Net D value 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 at the customer level is considered.

Represents the id of the active version of the subscription resource.

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.

Learn more .

Indicates that the subscription has been deleted when the value is true. You can retrieve a deleted subscription using the list operation .

The date-time at which the subscription change is scheduled to happen.

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

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 by free_period_unit. For example, 3 with free_period_unit = month means 3 free months are added to the first term.

The time unit for free_period.

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 unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

Indicates whether the subscription should be decommissioned when it is canceled. If set to true all subscription operations will be disabled except deletion.