ChargebeeAPI

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

id
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

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

Possible 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

Array containing object of parameters for addons

coupons

Array containing object of parameters for coupons

shipping_address

Object of parameters for shipping_address