# Quoted subscriptions

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


When a `[quote](/docs/api/quotes)` is created, it generates the `quoted_subscription` resource. This captures most of the details of the subscription that would eventually be created once the quote is invoiced. This resource is returned along with the quote for most of the associated operations.

## Sample Quoted subscription

```json
{
  "plan_id": "basic",
  "plan_quantity": 1,
  "billing_period": 1,
  "billing_period_unit": "month",
  "object": "quoted_subscription",
  "addons": [
    {
      "id": "ssl",
      "quantity": 1,
      "unit_price": 495,
      "object": "addon"
    }
  ],
  "event_based_addons": [
    {
      "id": "day-pass",
      "quantity": 2,
      "unit_price": 200,
      "on_event": "subscription_creation",
      "charge_once": true,
      "object": "event_based_addon"
    }
  ],
  "coupons": [
    {
      "coupon_id": "plan_addons_coupon",
      "object": "coupon"
    }
  ]
}
```

## Quoted 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.

- `plan_unit_price` (optional, in cents, min=0)
  Amount that will override the Plan's default price. The unit depends on the [type of currency](/docs/api/getting-started) .

- `setup_fee` (optional, in cents, min=0)
  Amount that will override the default setup fee. The unit depends on the [type of currency](/docs/api/getting-started) .

- `billing_period` (optional, integer, min=1)
  Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.

- `billing_period_unit` (optional, enumerated string)
  Defines billing frequency in association with 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 when `operation_type` of the quote is `create_subscription_for_customer`. For subscriptions in the `future` `status` , this is the date/time when the subscription is set to start. The quote can be converted on a date/time after this date. This is called backdating the subscription creation. Backdating is performed when the subscription has already been provisioned but the conversion action has been delayed. Backdating is allowed only when the following prerequisites are met:
  
  -   Backdating is enabled for subscription creation operations.
  -   The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
  -   The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the subscription's plan is 2 months and today is 14th April, the `start_date` cannot be earlier than 14th February.

- `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 plan purchased. 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/v2/pcv-1/currencies) is enabled.

- `changes_scheduled_at` (optional, timestamp(UTC) in seconds)
  Applicable only when `operation_type` of the quote is `change_subscription`. When `change_option` is set to `specific_date` , then this is the date/time at which the subscription change is scheduled to occur. The quote can be converted on a date/time after this date. This is called backdating the subscription change and performed when the subscription change has already been provisioned but the conversion action has been delayed. Backdating is allowed only when the following prerequisites are met:
  
  -   Backdating must be enabled for subscription change operations.
      
  -   Only the following changes can be backdated:
      
  -   Changes in the recurring items or their prices.
      
  -   Addition of non-recurring items.
      
  -   Subscription `status` is `active`, `cancelled`, or `non_renewing`.
      
  -   The current day of the month does not exceed the limit set in Chargebee for backdating subscription change. This limit is the day of the month by which the accounting for the previous month must be closed.
      
  -   The date is on or after `current_term_start`.
      
  -   The date is on or after the last date/time any of the following changes were made:
      
  -   Changes in the recurring items or their prices.
      
  -   Addition of non-recurring items.
      
  -   The date is not more than duration X into the past where X is the billing period of the plan. For example, if the period of the subscription's plan is 2 months and today is 14th April, `changes_scheduled_at` cannot be earlier than 14th February.

- `change_option` (optional, enumerated string)
  Applicable only when `operation_type` of the quote is `change_subscription`. When the quote is converted, this attribute determines the date/time as of when the subscription change is to be carried out.
  Possible enum values:
    - `end_of_term`
      The change is scheduled to be carried out at the end of the billing cycle of the subscription.
    - `specific_date`
      The change is carried out as of `changes_scheduled_at` .
    - `immediately`
      The change is carried out immediately upon quote conversion.

- `free_period` (optional, integer, min=1)

- `free_period_unit` (optional, enumerated string)
  Possible enum values:
    - `day`
    - `week`
    - `month`
    - `year`

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

- `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` .
  - `unit_price` (optional, in cents, min=0)
    The price or per-unit-price of the addon. The value depends on the [type of currency](/docs/api/getting-started).
    
    **Note:**
    
    For recurring addons, this is the final price or per-unit price for each billing period of the subscription, regardless of the [addon period](/docs/api/v2/pcv-1/addons/addon-object#period). For example, consider the following details:
    
    -   The `unit_price` provided is $10
    -   The addon billing period is 1 month.
    -   The plan billing period is 3 months.
    -   The addon is only billed for $10 on each subscription renewal.
  - `amount` (optional, in cents, min=0)
    The total amount for the addon. The format of the value [depends upon the currency](/docs/api/currencies) .
  - `trial_end` (optional, timestamp(UTC) in seconds)
    The time at which the trial ends for the addon. This value can only be set for subscriptions that start with an `active` or `non-renewing` status. Once set, the value can't be changed. (Addon trial periods must be enabled by [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) )
  - `remaining_billing_cycles` (optional, integer, min=0)
    The number of billing cycles this addon will be attached to subscription.
  - `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.
  - `unit_price_in_decimal` (optional, string, max chars=39)
    The decimal representation of the price or per-unit price of the addon. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
    
    **Note:**
    
    For recurring addons, this is the final price or per-unit price for each billing period of the subscription, regardless of the addon period. For example, consider the following details:
    
    -   The `unit_price_in_decimal` provided is $10.75
    -   The addon billing period is 1 month.
    -   The plan billing period is 3 months.
    -   The addon is only billed for $10.75 on each subscription renewal.
  - `amount_in_decimal` (optional, string, max chars=39)
    The decimal representation of the total amount for the addon, in major units of the currency. Always returned when [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.
  - `proration_type` (optional, enumerated string)
    Possible enum values:
      - `full_term`
      - `partial_term`
      - `none`

- `event_based_addons` (optional, list of event_based_addon)
  List of non-recurring addons that will be charged on the occurrence of specified event.
  - `id` (required, string, max chars=100)
    A unique 'id' used to identify the addon.
  - `quantity` (required, integer, min=1)
    Quantity of the addon. Applicable for addons with `pricing_model` other than `flat_fee` .
  - `unit_price` (required, in cents, min=0)
    Amount that will override the Addon's default price. The unit depends on the [type of currency](/docs/api/getting-started) .
  - `on_event` (required, enumerated string)
    Event on which this addon will be charged.
    Possible enum values:
      - `subscription_creation`
        Addon will be charged on subscription creation.
      - `subscription_trial_start`
        Addon will be charged when the trial period starts.
      - `plan_activation`
        Addon will be charged on plan activation.
      - `subscription_activation`
        Addon will be charged on subscription activation.
      - `contract_termination`
        Addon will be charged on contract termination.
  - `charge_once` (required, boolean, default=true)
    If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
  - `quantity_in_decimal` (optional, string, max chars=33)
    The decimal representation of the quantity of the addon. Returned for quantity-based addons when [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.
  - `unit_price_in_decimal` (optional, string, max chars=39)
    The decimal representation of the price or per-unit price of the addon. The value is in major units of the currency. Always returned when [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.

- `coupons` (optional, list of coupon)
  List of coupons for this subscription
  - `coupon_id` (required, string, max chars=100)
    Used to uniquely identify the coupon

- `quoted_contract_term` (optional, quoted_contract_term)
  The details of the contract term to be created when this quote is invoiced.
  - `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/v2/pcv-1/quoted_subscriptions). If the subscription was [imported](/docs/api/v2/pcv-1/quoted_subscriptions) with the contract term, then this value includes the value passed for `total_amount_raised` .
  - `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.