# Subscriptions

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


A Chargebee subscription connects a customer record to products/services. It describes what the customer has signed up for and how often they're charged for it. The essential components of a subscription are:

-   A [plan-item price](/docs/api/item_prices).
-   Any addon- and charge-item prices applied to the subscription.
-   Any [coupons](/docs/api/coupons) applied.
-   Any [discounts](/docs/api/discounts) applied.

The charges in a subscription are billed via invoices.

**Note:** The maximum number of subscriptions for any given [customer](/docs/api/customers) (`[active](/docs/api/subscriptions/subscription-object#status)` or not) is 900.

#### Subscription billing frequencies[](#subscription-billing-frequencies)

Chargebee offers two billing frequency options for subscriptions:

-   **Plan-based billing** (`default`): Subscriptions are billed based on the billing period defined for the item price of the `item_type` `plan`. [Learn more](https://www.chargebee.com/docs/billing/2.0/subscriptions/subscriptions#plan-based-billing).
    
-   **Multi-frequency billing**: Subscriptions are billed according to the billing period of each recurring item price within the subscription. [Learn more](https://www.chargebee.com/docs/billing/2.0/subscriptions/multi-frequency-billing).
    
    **Important**
    
    [Limitations](https://www.chargebee.com/docs/billing/2.0/subscriptions/multi-frequency-billing#limitations) of Multi-frequency billing.
    
    **Private Beta**
    
    Multi-frequency billing is in private beta. Please reach out to the Chargebee [support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable this feature.
    

The selection of the billing frequency preference is configured at the site level.

#### Item price compatibility in a subscription[](#item-price-compatibility-in-a-subscription)

When creating or updating a subscription, one of the item prices specified under subscription\_items must be a plan-item price. The remaining must be compatible addon- or charge-item prices. An item price is compatible with a plan-item price if their currencies are the same. Additionally, an addon-item price is compatible with a plan-item price only if their billing frequencies meet the following conditions:

`period_unit` for plan-item price

Compatible `period_unit` for addon-item price

Compatible period for addon-item price

`day`

`day`

The `period` of the plan-item price should be divisible by the `period` of the addon-item price.

**Example**

If the `period` of the plan-item price is `10`, then the period of the addon-item price can be `10`, `5`, `2`, or `1`.

`week`

`week` or `day`

The `period` (in days) of the plan-item price should be divisible by the `period` of the addon-item price.

**Example** If the `period` of the plan-item price is `2`, then the period of the addon-item price can be as follows depending on the value of `period_unit`:

-   for `period_unit` as `week`, `period` can be `2` or `1`.
-   for `period_unit` as `day`, `period` can be `14`, `7`, `2`, or `1`.

`month`

`month`

The `period` of the plan-item price should be divisible by the `period` of the addon-item price.

**Example**

If the `period` of the plan-item price is `6`, then the `period` of the addon-item price can be `6`, `3`, `2`, or `1`.

`year`

`year` or `month`

The `period` (in months) of the plan-item price should be divisible by the `period` of the addon-item price.

**Example**

If the `period` of the plan-item price is `2`, then the `period` of the addon-item price can be as follows depending on the value of `period_unit`:

-   for `period_unit` as `year`, `period` can be `2` or `1`.
-   for `period_unit` as `month`, `period` can be `24`, `12`, `8`, `6`, `4`, `3`, `2`, or `1`.

#### Tax provider fields[](#tax-provider-fields)

**Avalara**: Merchants using **Avalara Sales Tax** can optionally associate each item price with a locationCode (from their Avalara company locations), so tax can be resolved correctly at the line item level.

Field ID

Field Value

APIs

`locationCode`

Merchant to configure it on Avalara Platform under company locations

APIs having [Item Prices](/docs/api/item_prices/item-price-object) attributes.

**Anrok**: Canadian customers can have multiple tax registration numbers. We currently support only sharing one tax registration number with Anrok. So we added a new field which can have comma separated multiple tax reg numbers for Anrok. Values configured in the field is passed as it is to Anrok for accurate tax calculation

Field ID

Field Value

APIs

`additionalTaxRegistrationNumber`

Canadian tax registration numbers in comma separated fashion.

APIs involving customer attributes. Also includes APIs where we are creating new customers. Eg: estimate, subscription, hosted pages.

**Vertex**: Chargebee shares field IDs and corresponding values with merchants, who then configure them on the Vertex Platform for seamless integration

**Note:** Field Id like `customerCode` , `customerClass` , and`taxExempted` belong to the customer object.

Field Id like `productCode` , `productClass` , `productTaxCode` , and `productClass` belong to the product object.

Field ID

Field Value

APIs

`productCode`

Merchant to configure it on Vertex Platform

APIs having [Item Prices](/docs/api/item_prices/item-price-object) attributes.

`productClass`

`customerCode`

APIs involving [customer](/docs/api/customers/customer-object) attributes. Also includes APIs where we are creating new customers. For example: [estimate](/docs/api/estimates/estimate-for-creating-a-customer-and-subscription), [subscription](/docs/api/subscriptions), [hosted pages](/docs/api/hosted_pages/checkout-charge-items-and-one-time-charges).

`customerClass`

**Taxamo:** Chargebee shares field IDs and corresponding values with merchants, who then configure them on the Taxamo Platform for seamless integration

Field Id

Field Value

APIs

`productTaxCode`

Merchant to configure it on Taxamo Platform

APIs having [Item Prices](/docs/api/item_prices/item-price-object) attributes.

`productClass`

`taxExempted`

APIs involving [customer](/docs/api/customers/customer-object) attributes. Also includes APIs where we are creating new customers. For example: [estimate](/docs/api/estimates/estimate-for-creating-a-customer-and-subscription), [subscription](/docs/api/subscriptions), [hosted pages](/docs/api/hosted_pages/checkout-charge-items-and-one-time-charges).

**cbtaxes**: With CBTaxes, you can activate India IGST for customers located in Special Economic Zones (SEZ), implement zero-rated tax for SEZ customers, enable India IGST for customers outside of India, and set up zero-rated tax for customers outside of India.

Field ID

Field Value

APIs

`indiaSez`

`SEZ_IGST_TAX`

APIs involving [customer](/docs/api/customers/customer-object) attributes. Also includes APIs where we are creating new customers. For example: [estimate](/docs/api/estimates/estimate-for-creating-a-customer-and-subscription), [subscription](/docs/api/subscriptions), [hosted pages](/docs/api/hosted_pages/checkout-charge-items-and-one-time-charges).

`SEZ_ZERO_RATED_TAX`

`indiaExport`

`EXPORT_IGST_TAX`

`EXPORT_ZERO_RATED_TAX`

**All**: For tax inclusive tax calculation, For tax exclusive tax calculation. This is currently used for price type overriding at customer level

Field ID

Field Value

APIs

`priceType`

`TAX_INCLUSIVE`

APIs involving [customer](/docs/api/customers/customer-object) attributes. Also includes APIs where we are creating new customers. For example: [estimate](/docs/api/estimates/estimate-for-creating-a-customer-and-subscription), [subscription](/docs/api/subscriptions), [hosted pages](/docs/api/hosted_pages/checkout-charge-items-and-one-time-charges).

`TAX_EXCLUSIVE`

`SITE_DEFAULT` or blank

Removes price type override, and allows site level configuration to be used for tax calculation.

#### Ramps API compatibility mode[](#ramps-api-compatibility-mode)

If you want to schedule changes on a subscription, use the [Ramps API](/docs/api/ramps).

If you are currently scheduling changes through the [Update subscription API](/docs/api/subscriptions/update-subscription-for-items), migrate to the Ramps API. To get started, [request access for Subscription Ramps](https://app.chargebee.com/login?forward=https://app.chargebee.com/request_access/subscription-ramps&ref=feature). Chargebee will enable Ramps compatibility mode for your site. Once enabled, you can test the Ramps API without impacting your existing integrations.

The following parts of the Billing API have subtle differences in behavior when the Ramps feature is disabled versus when it is enabled with compatibility mode. (Follow the links to learn more.)

-   The value of the [`subscription.has_scheduled_changes`](/docs/api/subscriptions/subscription-object#has_scheduled_changes) attribute.
-   [Update subscription](/docs/api/subscriptions/update-subscription-for-items#impact-scheduled-changes)
-   [Create Checkout for updating a subscription](/docs/api/hosted_pages/create-checkout-to-update-a-subscription#impact-scheduled-changes)
-   [Remove scheduled changes](/docs/api/subscriptions/remove-scheduled-changes)
-   [Retrieve with scheduled changes](/docs/api/subscriptions/retrieve-with-scheduled-changes)
-   [Create a quote for updating a subscription](/docs/api/quotes/create-a-quote-for-update-subscription-items)
-   [Edit a quote for updating a subscription](/docs/api/quotes/edit-update-subscription-quote-for-items)
-   [Portal sessions](/docs/api/portal_sessions#scheduled-subscription-changes)

## Sample Subscription

```json
{
  "activated_at": 1612890938,
  "auto_collection": "off",
  "billing_period": 1,
  "billing_period_unit": "month",
  "created_at": 1612890938,
  "currency_code": "USD",
  "current_term_end": 1615310138,
  "current_term_start": 1612890938,
  "customer_id": "__test__8asukSOXe0QYSR",
  "deleted": false,
  "due_invoices_count": 1,
  "due_since": 1612890938,
  "has_scheduled_changes": false,
  "id": "__test__8asukSOXe0W3SU",
  "mrr": 0,
  "next_billing_at": 1615310138,
  "object": "subscription",
  "remaining_billing_cycles": 1,
  "resource_version": 1612890938000,
  "started_at": 1612890938,
  "status": "active",
  "subscription_items": [
    {
      "amount": 1000,
      "billing_cycles": 1,
      "free_quantity": 0,
      "item_price_id": "basic-USD",
      "item_type": "plan",
      "object": "subscription_item",
      "quantity": 1,
      "unit_price": 1000
    },
    {
      "amount": 100,
      "item_price_id": "day-pass-USD",
      "item_type": "addon",
      "object": "subscription_item",
      "quantity": 1,
      "unit_price": 100
    }
  ],
  "total_dues": 1100,
  "updated_at": 1612890938
}
```

## Subscriptions attributes

## Input Parameters

- `id` (required, string, max chars=50)
  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.
  
  **Note** In the event that the subscription resource is [transferred](/docs/api/business_entities/transfer-resources-to-another-business-entity) along with its associated `[customer](/docs/api/customers)` resource to a different business entity, Chargebee assigns a new random value as the `id` for the subscription. The original identifier is preserved for the transferred copy of the `subscription` resource. (See also: [Mechanics of business entity transfer](/docs/api/business_entities).)

- `currency_code` (required, string, max chars=3)
  The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the subscription

- `billing_period` (optional, integer, min=1)
  Specifies the length of each billing cycle (or term) of the subscription, expressed in the unit defined by `billing_period_unit`.

- `billing_period_unit` (optional, enumerated string)
  Specifies the unit used to measure the `billing_period`.
  Possible enum values:
    - `day`
      Charge based on day(s)
    - `week`
      Charge based on week(s)
    - `month`
      Charge based on month(s)
    - `year`
      Charge based on year(s)

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

- `auto_collection` (optional, enumerated string)
  Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.
  Possible enum values:
    - `on`
      Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.
    - `off`
      Automatic collection of charges will not be made for this subscription. Use this for offline payments.

- `plan_quantity_in_decimal` (optional, string, max chars=33)
  The decimal representation of the quantity of the addon. Returned for quantity-based plans when [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.

- `plan_unit_price_in_decimal` (optional, string, max chars=39)
  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](/docs/api/currencies) is enabled.

- `customer_id` (required, string, max chars=50)
  Identifier of the customer with whom this subscription is associated.

- `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.
    - `paused`
      The subscription is [paused](https://www.chargebee.com/docs/2.0/pause-subscription.html). The subscription will not renew while in this state.
    - `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.

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

- `trial_end_action` (optional, enumerated string)
  Applicable only when [End-of-trial Action](https://www.chargebee.com/docs/1.0/trial_periods_hidden.html#how-to-define-the-end-of-trial-actions-for-subscriptions) 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.
  Possible enum values:
    - `site_default`
      This is the default value. The action [configured for the site](https://www.chargebee.com/docs/1.0/trial_periods_hidden.html#how-to-define-the-end-of-trial-actions-for-subscriptions) at the time when the trial ends, takes effect.
    - `plan_default`
      The action [configured for the site](https://www.chargebee.com/docs/1.0/trial_periods_hidden.html#how-to-define-the-end-of-trial-actions-for-subscriptions) at the time when the trial ends, takes effect.
    - `activate_subscription`
      The subscription activates and charges are raised for non-metered items.
    - `cancel_subscription`
      The subscription cancels.

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

- `next_billing_at` (optional, timestamp(UTC) in seconds)
  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.

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

- `contract_term_billing_cycle_on_renewal` (optional, integer, min=1, max=100)
  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](https://www.chargebee.com/docs/contract-terms.html#configuring-contract-terms) .

- `override_relationship` (optional, boolean)
  If `true` , ignores the [hierarchy relationship](/docs/api/customers/customer-object#relationship) and uses customer as payment and invoice owner.

- `pause_date` (optional, timestamp(UTC) in seconds)
  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.

- `resume_date` (optional, timestamp(UTC) in seconds)
  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.

- `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
    - `tax_calculation_failed`
      Tax Calculation Failed
    - `currency_incompatible_with_gateway`
      Currency incompatible with Gateway
    - `non_compliant_customer`
      Non Compliant Customer

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

- `resource_version` (optional, long)
  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.

- `updated_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating when the item was last updated.

- `has_scheduled_advance_invoices` (required, boolean, default=false)
  The subscription has an [advance invoicing schedule](/docs/api/advance_invoice_schedules) .

- `has_scheduled_changes` (required, boolean, default=false)
  Indicates whether a change is scheduled on the subscription.
  
  **Note** When [Ramps](ramps) are enabled with compatibility mode, this attribute indicates whether one or more ramps are scheduled for the subscription. For more details, see [Ramps API compatibility mode](/docs/api/subscriptions#ramps-compat-mode).

- `payment_source_id` (optional, string, max chars=40)
  Payment source attached to this subscription. If present, customer's payment sources won't be used to collect any payment for this subscripiton.

- `plan_free_quantity_in_decimal` (optional, string, max chars=33)
  The free\_quantity\_in\_decimal as set for the plan. Returned for quantity-based plans when [multi-decimal pricing](/docs/api/currencies) is enabled.

- `plan_amount_in_decimal` (optional, string, max chars=39)
  The decimal representation of the total amount for the item, in major units of the currency. Always returned when [multi-decimal pricing](/docs/api/currencies) is enabled.

- `cancel_schedule_created_at` (optional, timestamp(UTC) in seconds)
  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.

- `offline_payment_method` (optional, enumerated string)
  The preferred offline payment method for the subscription.
  Possible enum values:
    - `no_preference`
      No Preference
    - `cash`
      Cash
    - `check`
      Check
    - `bank_transfer`
      Bank Transfer
    - `ach_credit`
      ACH Credit
    - `sepa_credit`
      SEPA Credit
    - `boleto`
      Boleto
    - `us_automated_bank_transfer`
      US Automated Bank Transfer
    - `eu_automated_bank_transfer`
      EU Automated Bank Transfer
    - `uk_automated_bank_transfer`
      UK Automated Bank Transfer
    - `jp_automated_bank_transfer`
      JP Automated Bank Transfer
    - `mx_automated_bank_transfer`
      MX Automated Bank Transfer
    - `custom`
      Custom

- `channel` (optional, enumerated string)
  The subscription channel this object originated from and is maintained in.
  Possible enum values:
    - `web`
      The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.
    - `app_store`
      The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.
    - `play_store`
      The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

- `net_term_days` (optional, integer)
  The [Net D](https://www.chargebee.com/docs/net_d.html) value explicitly set for this subscription. Net D is the number of days from [`invoice.date`](/docs/api/invoices/invoice-object#date) until payment for the invoice is due. When an invoice is raised, and this value is unavailable, the net\_term\_days defined at [the customer level](/docs/api/customers/customer-object#net_term_days) is considered.

- `active_id` (optional, string, max chars=50)
  **Note**: Present only when the `subscription` has been [transferred](/docs/api/business_entities/transfer-resources-to-another-business-entity) between business entities.
  
  Represents the `id` of the active version of the `subscription` resource.
  
  **Tip** If the `id` and `active_id` of a `subscription` resource are the same, this indicates that you are working with the active version of that `subscription` resource.

- `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/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` .

- `mrr` (optional, in cents, min=1)
  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](/docs/api/currencies) . **Note:** This may not return accurate values since updated asynchronously.

- `exchange_rate` (optional, bigdecimal, min=1E-9, max=999999999.999999999)
  Exchange rate used for base currency conversion.This value is updated to the [rate configured](https://www.chargebee.com/docs/multi-currency-pricing.html#configuring-multicurrency) on your site each time any change is made to the subscription.

- `base_currency_code` (optional, string, max chars=3)
  The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the site's base currency.

- `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 collection of key-value pairs that provides extra information about the subscription.
  
  **Note:** There's a character limit of 65,535.
  
  [Learn more](/docs/api/advanced-features#metadata) .

- `deleted` (required, boolean)
  Indicates that the subscription has been deleted when the value is `true`. You can retrieve a deleted subscription using the [list operation](/docs/api/subscriptions/list-subscriptions) .

- `changes_scheduled_at` (optional, timestamp(UTC) in seconds)
  The date-time at which the subscription change is scheduled to happen.
  
  **Note** This attribute is not returned when the change is scheduled to happen at the end of the current term.

- `cancel_reason_code` (optional, string, max chars=100)
  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

- `free_period` (optional, integer)
  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.

- `free_period_unit` (optional, enumerated string)
  The time unit for `free_period`.
  Possible enum values:
    - `day`
      Charge based on day(s)
    - `week`
      Charge based on week(s)
    - `month`
      Charge based on month(s)
    - `year`
      Charge based on year(s)

- `create_pending_invoices` (optional, boolean)
  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](/docs/api/subscriptions/create-subscription-for-items#create_pending_invoices)/[update](/docs/api/subscriptions/update-subscription-for-items#create_pending_invoices) 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](https://www.chargebee.com/docs/charges.html) 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](https://www.chargebee.com/docs/metered_billing.html) is enabled for the site

- `auto_close_invoices` (optional, boolean)
  Set to `false` to override for this subscription, the [site-level setting](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing#configuring-metered-billing) 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](/docs/api/customers/customer-object#auto_close_invoices) .

- `business_entity_id` (optional, string, max chars=50)
  The unique ID of the [business entity](/docs/api/advanced-features) of this subscription. This is always the same as the [business entity](/docs/api/subscriptions/subscription-object#customer_id) of the customer.

- `decommissioned` (required, boolean, default=false)
  Indicates whether the subscription has been [decommissioned](/docs/api/subscriptions/cancel-subscription-for-items#decommissioned). If set to `true` all subscription operations are disabled except deletion.
  
  **Note**: Decommission operation is irreversible. Once set to `true` it cannot be updated to `false` and thus subscription will remain decommissioned permanently.

- `subscription_items` (optional, list of subscription_item)
  Details of individual [item prices](/docs/api/item_prices) that are part of this subscription.
  - `item_price_id` (required, string, max chars=100)
    The unique identifier of the item price.
  - `item_type` (required, enumerated string)
    The type of item. There must be one and only one item of type `plan` in this list.
    Possible enum values:
      - `plan`
        Plan
      - `addon`
        Addon
      - `charge`
        Charge
  - `quantity` (optional, integer, min=1)
    The quantity of the item purchased
  - `quantity_in_decimal` (optional, string, max chars=33)
    The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when [multi-decimal pricing](/docs/api/getting-started) is enabled.
  - `unit_price` (optional, in cents, min=0)
    The price/per unit price of the item. When not provided, [the value set](/docs/api/item_prices/item-price-object) for the item price is used. This is only applicable when the `pricing_model` of the item price is `flat_fee` or `per_unit`. Also, it is only allowed when [price overriding](https://www.chargebee.com/docs/price-override.html) is enabled for the site. The value depends on the type of currency. If `changes_scheduled_at` is in the past and a `unit_price` is not passed, then the item price's current unit price is considered even if the item price did not exist on the date as of when the change is scheduled.
  - `unit_price_in_decimal` (optional, string, max chars=39)
    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](/docs/api/getting-started) is enabled.
  - `amount` (optional, in cents, min=0)
    The total amount for the item as determined from `unit_price` , `free_quantity` , `quantity` and `item_tiers` as applicable. The value depends on the [type of currency](/docs/api/currencies) .
  - `current_term_start` (optional, timestamp(UTC) in seconds)
    The beginning of the item's current billing period.
    
    **Note** Applicable only when multi-frequency billing is enabled.
    
    **Private Beta** Multi-frequency billing is in private beta. Please reach out to the Chargebee [support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable this feature.
  - `current_term_end` (optional, timestamp(UTC) in seconds)
    The end of the item's current billing period. Chargebee renews the item immediately following this date.
    
    **Note** Applicable only when multi-frequency billing is enabled.
    
    **Private Beta** Multi-frequency billing is in private beta. Please reach out to the Chargebee [support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable this feature.
  - `next_billing_at` (optional, timestamp(UTC) in seconds)
    The date or time at when the next billing for the item is scheduled to occur. This typically occurs immediately after `current_term_end`.
    
    **Note** Applicable only when multi-frequency billing is enabled.
    
    **Private Beta** Multi-frequency billing is in private beta. Please reach out to the Chargebee [support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable this feature.
  - `amount_in_decimal` (optional, string, max chars=39)
    The decimal representation of the total amount for the item, in major units of the currency. Always returned when [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `billing_period` (optional, integer, min=1)
    Specifies the length of each billing cycle for this subscription item, expressed in the unit defined by `subscription_items.billing_period_unit`.
    
    **Returned only if**
    
    [Multi-Frequency Billing](https://www.chargebee.com/docs/billing/2.0/subscriptions/subscriptions#multi-frequency-billing) is enabled.
  - `billing_period_unit` (optional, enumerated string)
    Specifies the unit used to measure the `subscription_items.billing_period`.
    
    **Returned only if**
    
    [Multi-Frequency Billing](https://www.chargebee.com/docs/billing/2.0/subscriptions/subscriptions#multi-frequency-billing) is enabled.
    Possible enum values:
      - `day`
        A period of 24 hours.
      - `week`
        A period of 7 days.
      - `month`
        A period of 1 calendar month.
      - `year`
        A period of 1 calendar year.
  - `free_quantity` (optional, integer, min=0)
    The `free_quantity` of the plan-item as [specified](/docs/api/item_prices) for the item price.
  - `free_quantity_in_decimal` (optional, string, max chars=33)
    The `free_quantity_in_decimal` as set for the item price. Returned for quantity-based item prices when [multi-decimal pricing](/docs/api/getting-started) is enabled.
  - `trial_end` (optional, timestamp(UTC) in seconds)
    The date/time when the trial period of the item ends. Applies to plan-items and--when [enabled](https://www.chargebee.com/docs/2.0/addons-trial.html) --addon-items as well.
  - `billing_cycles` (optional, integer, min=0)
    For the plan-item price: the value determines the number of billing cycles the subscription runs before canceling automatically. If not provided, then [the value set](/docs/api/item_prices/item-price-object) for the plan-item price is used.
    
    For addon-item prices: If [addon billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html) are enabled then this is the number of subscription billing cycles for which the addon is included. If not provided, then [the value set under attached addons](/docs/api/attached_items/attached-item-object) is used. Further, if that value is not provided, then [the value set for the addon-item price](/docs/api/item_prices/item-price-object) is used.
  - `service_period_days` (optional, integer, min=1, max=730)
    The service period of the item in days from the day of charge.
  - `charge_on_event` (optional, enumerated string)
    When `charge_on_option` option is set to `on_event` , this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items.
    Possible enum values:
      - `subscription_creation`
        the time of creation of the subscription.
      - `subscription_trial_start`
        the time when the trial period of the subscription begins.
      - `plan_activation`
        same as subscription activation, but also includes the case when the plan-item of the subscription is changed.
      - `subscription_activation`
        the moment a subscription enters an `active` or `non-renewing` state. Also includes reactivations of canceled subscriptions.
      - `contract_termination`
        when a contract term is [terminated](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option) .
  - `charge_once` (optional, boolean)
    Indicates if the charge-item is to be charged only once or each time the `charge_on_event` occurs. This parameter only applies to charge-items.
  - `charge_on_option` (optional, enumerated string)
    Indicates when the charge-item is to be charged. This parameter only applies to charge-items.
    Possible enum values:
      - `immediately`
        The item is charged immediately on being added to the subscription.
      - `on_event`
        The item is charged at the occurrence of the event specified as `charge_on_event` .
  - `proration_type` (optional, enumerated string)
    Specifies how to manage charges or credits for the addon during a subscription update.
    
    You can't modify this parameter's value within the current term. Moreover, it is removed from the subscription attributes when the next term starts.
    
    **See also:** `subscription_items[proration_type]` parameter for [Update a subscription API](/docs/api/subscriptions/update-subscription-for-items#subscription_items_proration_type) .
    Possible enum values:
      - `full_term`
        Charge the full price of the addon or give the full credit. Don't apply any proration.
      - `partial_term`
        Prorate the charges or credits from the time of the change till the end of the current term.
      - `none`
        Don't apply any charges or credits for the addon.
  - `usage_accumulation_reset_frequency` (optional, enumerated string)
    Specifies the frequency at which the usage counter needs to be reset.
    Possible enum values:
      - `never`
        Accumulates usage without ever resetting it.
      - `subscription_billing_frequency`
        Accumulates usage until the subscription's billing frequency ends.
  - `description` (optional, string, max chars=500)

- `item_tiers` (optional, list of item_tier)
  The pricing details of `subscription_items` which have `[pricing_model](/docs/api/item_prices/item_price-object#pricing_model)` as `tiered` , `volume` or `stairstep` .
  - `item_price_id` (required, string, max chars=100)
    The id of the item price to which this tier belongs.
  - `starting_unit` (required, integer, min=1)
    The lowest value in the quantity tier.
  - `ending_unit` (optional, integer)
    The highest value in the quantity tier.
  - `price` (required, in cents, default=0, min=0)
    The per-unit price for the tier when the `pricing_model` is `tiered` or `volume`. The total cost for the item price when the `pricing_model` is `stairstep`. The value is in the minor unit of the currency.
  - `starting_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as `ending_unit_in_decimal` of the next lower tier. Returned only when the pricing\_model is `tiered` , `volume` or `stairstep` and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `ending_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the `starting_unit_in_decimal` of the next higher tier. Returned only when the pricing\_model is `tiered` , `volume` or `stairstep` and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `price_in_decimal` (optional, string, max chars=39)
    The decimal representation of the per-unit price for the tier when the `pricing_model` is `tiered` or `volume`. When the `pricing_model` is `stairstep` , it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled.
  - `pricing_type` (optional, enumerated string)
    Pricing type for the tier.
    Possible enum values:
      - `per_unit`
        Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
      - `flat_fee`
        Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the **stairstep** pricing model, `pricing_type` will be set to `flat_fee` by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
      - `package`
        Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
  - `package_size` (optional, integer, min=1)
    Package size for the tier when pricing type is `package`. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
  - `index` (required, integer, min=0)
    The index number of the subscription to which the item price is added. Provide a unique number between `0` and `4` (inclusive) for each subscription that is to be created.

- `charged_items` (optional, list of charged_item)
  List of event based charge items that have already been charged.
  - `item_price_id` (required, string, max chars=100)
    A unique ID for your system to identify the item price.
  - `last_charged_at` (required, timestamp(UTC) in seconds)
    Timestamp indicating when this charge item\_price was last charged for this subscription.

- `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) .
  - `validation_status` (optional, enumerated string, default=not_validated)
    The address verification status.
    Possible enum values:
      - `not_validated`
        Address is not yet validated.
      - `valid`
        Address was validated successfully.
      - `partially_valid`
        The address is valid for taxability but has not been validated for shipping.
      - `invalid`
        Address is invalid.

- `referral_info` (optional, referral_info)
  Referral details if exists for the subscription
  - `referral_code` (optional, string, max chars=50)
    Referral code if available for the subscription
  - `coupon_code` (optional, string, max chars=50)
    Referral coupon code if available for the subscription
  - `referrer_id` (optional, string, max chars=19)
    Referrer id if available for the subscription
  - `external_reference_id` (optional, string, max chars=50)
    External reference id in referral system for the subscription
  - `reward_status` (optional, enumerated string, default=pending)
    Reward status for the referral subscription
    Possible enum values:
      - `pending`
        Pending
      - `paid`
        Paid
      - `invalid`
        Invalid
  - `referral_system` (optional, enumerated string)
    Source referral system for the referral subscription
    Possible enum values:
      - `referral_candy`
        Referral Candy
      - `referral_saasquatch`
        Referral Saasquatch
      - `friendbuy`
        Friendbuy
  - `account_id` (required, string, max chars=50)
    Referral account id
  - `campaign_id` (required, string, max chars=50)
    Referral campaign id
  - `external_campaign_id` (optional, string, max chars=100)
    Referral external campaign id
  - `friend_offer_type` (optional, enumerated string)
    Friend offer type for the referral camapign
    Possible enum values:
      - `none`
        None
      - `coupon`
        Coupon
      - `coupon_code`
        Coupon Code
  - `referrer_reward_type` (optional, enumerated string)
    Referrer reward type for the referral campaign
    Possible enum values:
      - `none`
        None
      - `referral_direct_reward`
        Referral Direct Reward
      - `custom_promotional_credit`
        Custom Promotional Credit
      - `custom_revenue_percent_based`
        Custom Revenue Percent Based
  - `notify_referral_system` (optional, enumerated string)
    Whether or not to notify the referral purchases to the referral system
    Possible enum values:
      - `none`
        None
      - `first_paid_conversion`
        First Paid Conversion
      - `all_invoices`
        All Invoices
  - `destination_url` (optional, string, max chars=250)
    Destination url for the referral campaign
  - `post_purchase_widget_enabled` (required, boolean, default=true)
    Whether post purchase widget is enabled for this campaign

- `billing_override` (optional, billing_override)
  Specify limits on how credits and excess payments are applied to individual invoices for the subscription.
  
  **Prerequisite**
  
  -   [Credit flexibility](https://www.chargebee.com/docs/billing/2.0/invoices-credit-notes-and-quotes/credit-notes#credits-flexibility) must be enabled for the site.
  
  **Constraints**
  
  -   These limits do not apply to [consolidated invoices](https://www.chargebee.com/docs/2.0/consolidated-invoicing.html).
  - `max_excess_payment_usage` (optional, long, min=-1)
    Maximum amount of [excess payments](/docs/api/customers/customer-object#excess_payments) that can be automatically applied to a single invoice associated with this subscription.
    
    **Supported values:**
    
    -   `0`: Auto-application of excess payments is disabled for the subscription.
    -   Any positive value: Maximum amount of excess payments that can be automatically applied to a single invoice for this subscription.
    
    When this attribute is absent, the [site-level Credit flexibility configuration](https://www.chargebee.com/docs/billing/2.0/invoices-credit-notes-and-quotes/credit-notes#credits-flexibility) applies.
  - `max_refundable_credits_usage` (optional, long, min=-1)
    Maximum amount of [refundable credits](/docs/api/customers/customer-object#refundable_credits) that can be automatically applied to a single invoice associated with this subscription.
    
    **Supported values:**
    
    -   `0`: Auto-application of refundable credits is disabled for the subscription.
    -   Any positive value: Maximum amount of refundable credits that can be automatically applied to a single invoice for this subscription.
    
    When this attribute is absent, the [site-level Credit flexibility configuration](https://www.chargebee.com/docs/billing/2.0/invoices-credit-notes-and-quotes/credit-notes#credits-flexibility) applies.

- `contract_term` (optional, contract_term)
  Contract terms for this subscription
  - `id` (required, string, max chars=50)
    Id that uniquely identifies the contract term in the site.
  - `status` (required, enumerated string)
    Current status of contract
    Possible enum values:
      - `active`
        An actively running contract term.
      - `completed`
        The contract term has run its full duration.
      - `cancelled`
        The contract term was ended because: - a change in the subscription caused a [subscription term reset](/docs/api/v2/pcv-1/subscriptions/update-a-subscription#force_term_reset).
        
        -   the subscription was cancelled due to non-payment.
      - `terminated`
        The contract term was terminated ahead of completion.
  - `contract_start` (required, timestamp(UTC) in seconds)
    The start date of the contract term
  - `contract_end` (required, timestamp(UTC) in seconds)
    The end date of the contract term
  - `billing_cycle` (required, integer, min=0)
    The number of billing cycles of the subscription that the contract term is for.
  - `action_at_term_end` (required, enumerated string, default=renew)
    Action to be taken when the contract term completes.
    Possible enum values:
      - `renew`
        -   Contract term completes and a new contract term is started for the number of billing cycles specified in [`contract_billing_cycle_on_renewal`](/docs/api/v2/pcv-1/subscriptions/create-subscription-for-customer#contract_term_billing_cycle_on_renewal).
        -   The `action_at_term_end` for the new contract term is set to `renew`.
      - `evergreen`
        Contract term completes and the subscription renews.
      - `cancel`
        Contract term completes and subscription is canceled.
      - `renew_once`
        Used when you want to renew the contract term just once. Does the following: - Contract term completes and a new contract term is started for the number of billing cycles specified in [`contract_billing_cycle_on_renewal`](/docs/api/v2/pcv-1/subscriptions/create-subscription-for-customer#contract_term_billing_cycle_on_renewal).
        
        -   The `action_at_term_end` for the new contract term is set to `cancel`.
  - `total_contract_value` (required, in cents, default=0, min=0)
    The sum of the [totals](/docs/api/invoices/invoice-object#total) of all the invoices raised as part of the contract term. For `active` contract terms, this is a predicted value. The value depends on the [type of currency](/docs/api/currencies). If the subscription was [imported](/docs/api/v2/pcv-1/subscriptions/import-a-subscription) with the contract term, then this value includes the value passed for `total_amount_raised` .
  - `total_contract_value_before_tax` (required, in cents, default=0, min=0)
    It refers to the total amount of revenue that is expected to be generated from a specific contract term, calculated as the sum of all invoices raised during the term, regardless of payment status. It is based on past performance and the specified currency in the contract. If the subscription was imported, the value for `total_amount_raised_before_tax` is included in the calculation of the total contract value before tax. It's important to note that this value excludes any applicable taxes.
  - `cancellation_cutoff_period` (optional, integer)
    The number of days before [`contract_end`](/docs/api/contract_terms/contract_term-object#contract_end) , during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
  - `created_at` (required, timestamp(UTC) in seconds)
    The date when the contract term was created.
  - `subscription_id` (required, string, max chars=50)
    The [Id](/docs/api/subscriptions/subscription-object#id) of the subscription that this contract term is for.
  - `remaining_billing_cycles` (optional, integer, min=0)
    The number of subscription billing cycles remaining after the current one for the contract term. This attribute is only returned for `active` contract terms.

- `discounts` (optional, list of discount)
  List of [discounts](/docs/api/discounts) currently attached to the subscription.
  
  **Note**
  
  -   Discounts of `[duration_type](/docs/api/discounts/discount-object#duration_type)` `one_time` are removed from the list after a single application to the subscription.
  -   Discounts of `duration_type` `limited_period` are removed from the list once the specified `[period](/docs/api/discounts/discount-object#period)` expires since their attachment to the subscription.
  - `id` (required, string, max chars=50)
    An immutable unique id for the discount. It is always auto-generated.
  - `invoice_name` (optional, string, max chars=100)
    The name of the discount as it should appear on customer-facing pages and documents such as [invoices](/docs/api/invoices) and [hosted pages](/docs/api/hosted_pages). This is auto-generated based on the `type` , `amount` , and `currency_code` of the discount. For example, it can be `10% off` or `10$ off` .
  - `type` (required, enumerated string, default=percentage)
    The type of discount. Possible value are:
    Possible enum values:
      - `fixed_amount`
        The specified amount will be given as discount.
      - `percentage`
        The specified percentage will be given as discount.
      - `offer_quantity`
        A specified number of units of the item price are offered for free. The number of free units is specified in `quantity`. The `offer_quantity` option is valid only when `apply_on` is set to `each_specified_item` and the `[pricing_model](/docs/api/item_prices/item_price-object#pricing_model)` of the item price is `per_unit` .
  - `percentage` (optional, double, min=0.01, max=100)
    The percentage of the original amount that should be deducted from it.
  - `amount` (optional, in cents, min=0)
    The value of the discount. [The format of this value](/docs/api/currencies) depends on the kind of currency.
  - `quantity` (optional, integer, min=1)
    Specifies the number of free units provided for the item, without affecting the total quantity sold. This parameter is applicable only when `discount.type` is `offer_quantity`.
  - `currency_code` (optional, string, max chars=3)
    The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the discount. This is only applicable when `discount.type` is `fixed_amount` .
  - `duration_type` (required, enumerated string, default=forever)
    Specifies the time duration for which this discount is attached to the subscription.
    Possible enum values:
      - `one_time`
        The discount stays attached to the subscription till it is applied on an invoice **once**. It is removed after that from the subscription.
      - `forever`
        The discount is attached to the subscription and applied on the invoices till it is [explicitly removed](/docs/api/subscriptions/update-subscription-for-items#discounts_operation_type) .
      - `limited_period`
        The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by `period` and `period_unit` .
  - `period` (optional, integer, min=1)
    The duration of time for which the discount is attached to the subscription, in `period_units`. Applicable only when `duration_type` is `limited_period`.
  - `period_unit` (optional, enumerated string)
    The unit of time for `period`. Applicable only when `duration_type` is `limited_period`.
    Possible enum values:
      - `day`
        A period of 24 hours.
      - `week`
        A period of 7 days.
      - `month`
        A period of 1 calendar month.
      - `year`
        A period of 1 calendar year.
  - `included_in_mrr` (required, boolean)
    The discount is included in MRR calculations for your site. This attribute is only applicable when `duration_type` is `one_time` and when the [feature is enabled](https://www.chargebee.com/docs/reporting.html#dashboards_flexible-mrr-calculation) in Chargebee. Also, If the [site-level setting](https://www.chargebee.com/docs/reporting.html#chart_flexible-mrr-calculation) is to exclude one-time discounts from MRR calculations, this value is always returned `false`.
  - `apply_on` (required, enumerated string)
    The amount on the invoice to which the discount is applied.
    Possible enum values:
      - `invoice_amount`
        The discount is applied to the invoice `sub_total` .
      - `specific_item_price`
        The discount is applied to the `invoice.line_item.amount` that corresponds to the item price specified by `item_price_id` .
  - `item_price_id` (optional, string, max chars=100)
    The [id of the item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) in the subscription to which the discount is to be applied. Relevant only when `apply_on` = `specific_item_price`.
  - `created_at` (required, timestamp(UTC) in seconds)
    Timestamp indicating when this discount is created.
  - `apply_till` (optional, timestamp(UTC) in seconds)
    Specifies till when the limited period discount is applicable. This attribute will be sent in the response only for `limited_period` duration type discount.
  - `applied_count` (optional, integer)
    Specifies the number of times the discount has been applied.
  - `coupon_id` (required, string, max chars=100)
    Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
    
    **Note:**
    
    When the coupon ID contains a special character; for example: `#`, the API returns an error. Make sure that you [encode](https://www.urlencoder.org/) the coupon ID in the path parameter before making an API call.
  - `index` (required, integer, min=0)
    The index number of the subscription to which the item price is added. Provide a unique number between `0` and `4` (inclusive) for each subscription that is to be created.