Subscriptions

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: The maximum number of subscriptions for any given customer (active or not) is 900.

Sample SubscriptionJSON

API Index URL

https://[site].chargebee.com/api/v1/subscriptions

Subscriptions attributes

required, string, max chars=50

A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

plan_id

required, string, max chars=100

Identifier of the plan for this subscription

plan_quantity

required, integer, default=1, min=1

Represents the plan quantity for this subscription.

start_date

optional, timestamp(UTC) in seconds

Applicable only for 'future' subscriptions. The scheduled start time of the subscription.

trial_end

optional, timestamp(UTC) in seconds

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.

remaining_billing_cycles

optional, integer, min=0

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.

po_number

optional, string, max chars=100

Purchase order number for this subscription.

status

required, enumerated string

Current state of the subscription

Enum Values

future

The subscription is scheduled to start at a future date.

in_trial

The subscription is in trial.

active

The subscription is active and will be charged for automatically based on the items in it.

non_renewing

The subscription will be canceled at the end of the current term.

cancelled

The subscription has been canceled and is no longer in service.

transferred

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.

trial_start

optional, timestamp(UTC) in seconds

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.

current_term_start

optional, timestamp(UTC) in seconds

Start of the current billing period of the subscription.

current_term_end

optional, timestamp(UTC) in seconds

End of the current billing period of the subscription. Subscription is renewed immediately after this

created_at

optional, timestamp(UTC) in seconds

The time at which the subscription was created.

started_at

optional, timestamp(UTC) in seconds

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

activated_at

optional, timestamp(UTC) in seconds

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

cancelled_at

optional, timestamp(UTC) in seconds

Time at which subscription was cancelled or is set to be cancelled.

cancel_reason

optional, enumerated string

The reason for canceling the subscription. Set by Chargebee automatically.

Enum Values

not_paid

Not Paid

no_card

No Card

fraud_review_failed

Fraud Review Failed

non_compliant_eu_customer

Non Compliant EU Customer

affiliate_token

optional, string, max chars=250

A unique tracking token

created_from_ip

optional, string, max chars=50

The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.

has_scheduled_changes

required, boolean, default=false

If true , there are subscription changes scheduled on next renewal.

due_invoices_count

optional, integer

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 .

due_since

optional, timestamp(UTC) in seconds

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_dues

optional, in cents, min=0

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 .

invoice_notes

optional, string, max chars=2000

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.

meta_data

optional, jsonobject

A set of key-value pairs stored as additional information for the subscription. Learn more .

addons

List of addons for this subscription with quantity(if applicable)

coupons

List of coupons for this subscription

shipping_address

Shipping address for the subscription.