# Subscriptions

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](/docs/api/v1/customers) (`[active](/docs/api/subscriptions/subscription-object#status)` or not) is 900.

## Sample Subscription

```json
{
  "activated_at": 1517506669,
  "created_at": 1517506669,
  "current_term_end": 1519925869,
  "current_term_start": 1517506669,
  "due_invoices_count": 1,
  "due_since": 1517506669,
  "has_scheduled_changes": false,
  "id": "__test__5SK0bLNFRFuBv6r6j",
  "object": "subscription",
  "plan_id": "no_trial",
  "plan_quantity": 1,
  "started_at": 1517506669,
  "status": "active",
  "total_dues": 895
}
```

## Subscriptions attributes

## Input Parameters

- `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](/docs/api/contract_terms): 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](https://www.chargebee.com/docs/2.0/mbe-getting-started-with-customer-transfer.html) activity is completed successfully. This status is only valid for [product catalog 2.0](https://www.chargebee.com/docs/2.0/product-catalog.html) 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](https://www.chargebee.com/docs/consolidated-invoicing.html) is enabled, or when the subscription is for the customer who is in [hierarchy](/docs/api/hierarchies) , 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](https://www.chargebee.com/docs/consolidated-invoicing.html) is enabled, or when the subscription is for the customer who is in [hierarchy](/docs/api/hierarchies) , 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](/docs/api/v1/subscriptions) . **Note:** Not supported if [consolidated invoicing](https://www.chargebee.com/docs/consolidated-invoicing.html) is enabled, or when the subscription is for the customer who is in [hierarchy](/docs/api/hierarchies) , 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](/docs/api/invoices/invoice-object#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](/docs/api/v1/subscriptions) .

- `addons` (optional, list of addon)
  List of addons for this subscription with quantity(if applicable)
  - `id` (required, string, max chars=100)
    Identifier of the addon. Multiple addons can be passed.
  - `quantity` (optional, integer, default=1, min=1)
    Quantity of the addon. Applicable for addons with `pricing_model` other than `flat_fee` .
  - `proration_type` (optional, enumerated string)
    Type of proration for addons
    Possible enum values:
      - `full_term`
        The full price for the addon is charged; no proration is applied.
      - `partial_term`
        The addon charges are prorated for the remaining period in the current term.
      - `none`
        There is no proration done in this instance; therefore, the addon is not charged at all.

- `coupons` (optional, list of coupon)
  List of coupons for this subscription
  - `coupon_id` (required, string, max chars=100)
    Used to uniquely identify the coupon
  - `apply_till` (optional, timestamp(UTC) in seconds)
    The date till when the coupon can be applied. Applicable for `limited_period` [coupons](/docs/api/coupons) only.
  - `applied_count` (required, integer, default=0)
    Number of times this coupon has been applied for this subscription
  - `coupon_code` (optional, string, max chars=50)
    The coupon code used to redeem the coupon. Will be present only when associated code for a coupon is used.

- `shipping_address` (optional, shipping_address)
  Shipping address for the subscription.
  - `first_name` (optional, string, max chars=150)
    The first name of the contact.
  - `last_name` (optional, string, max chars=150)
    The last name of the contact.
  - `email` (optional, string, max chars=70)
    The email address.
  - `company` (optional, string, max chars=250)
    The company name.
  - `phone` (optional, string, max chars=50)
    The phone number.
  - `line1` (optional, string, max chars=150)
    Address line 1
  - `line2` (optional, string, max chars=150)
    Address line 2
  - `line3` (optional, string, max chars=150)
    Address line 3
  - `city` (optional, string, max chars=50)
    The name of the city.
  - `state_code` (optional, string, max chars=50)
    The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search) without the country prefix. Currently supported for USA, Canada, India and UAE. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ` ). For Tamil Nadu (India), set as `TN` (not `IN-TN` ). For British Columbia (Canada), set as `BC` (not `CA-BC` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `state` (optional, string, max chars=50)
    The state/province name.
  - `country` (optional, string, max chars=50)
    The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) .
    
    **Note**: If you enter an invalid country code, the system will return an error.
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option.
  - `zip` (optional, string, max chars=20)
    Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) .