Quoted subscriptions

When a quote 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"
        },
        {..}
    ]
}

id

string, max chars=50
A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

plan_id

string, max chars=100
Identifier of the plan for this subscription

plan_quantity

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.

setup_fee

optional, in cents, min=0
Amount that will override the default setup fee. The unit depends on the type of currency.

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 values are

dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge 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: 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 values are

onWhenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.offAutomatic 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 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 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 values are

end_of_termThe change is scheduled to be carried out at the end of the billing cycle of the subscription.specific_dateThe change is carried out as of changes_scheduled_at.immediatelyThe change is carried out immediately upon quote conversion.

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.

addons
Show attributes[+]

optional, list of addon
List of addons for this subscription with quantity(if applicable)

Addon attributes

id

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.

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

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)

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 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 is enabled.

proration_type

optional, enumerated string

Possible values are

full_termfull charge will be added for the partial term.partial_termprorated charge will be calculated for the partial term.noneNo charge will be added for the partial term.

event_based_addons
Show attributes[+]

optional, list of event_based_addon
List of non-recurring addons that will be charged on the occurrence of specified event.

Event based addon attributes

id

string, max chars=100
A unique 'id' used to identify the addon.

quantity

integer, min=0
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.

unit_price

in cents, min=0
Amount that will override the Addon's default price. The unit depends on the type of currency.

on_event

enumerated string
Event on which this addon will be charged.

Possible values are

subscription_creationAddon will be charged on subscription creation.subscription_trial_startAddon will be charged when the trial period starts.plan_activationAddon will be charged on plan activation.subscription_activationAddon will be charged on subscription activation.contract_terminationAddon will be charged on contract termination.

charge_once

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

coupons
Show attributes[+]

optional, list of coupon
List of coupons for this subscription

Coupon attributes

coupon_id

string, max chars=100
Used to uniquely identify the coupon

quoted_contract_term
Show attributes[+]

optional, quoted_contract_term
The details of the contract term to be created when this quote is invoiced.

Quoted contract term attributes

contract_start

timestamp(UTC) in seconds
The start date of the contract term

contract_end

timestamp(UTC) in seconds
The end date of the contract term

billing_cycle

integer, min=0
The number of billing cycles of the subscription that the contract term is for.

action_at_term_end

enumerated string, default=renew
Action to be taken when the contract term completes.

Possible values are

renew

Contract term completes and a new contract term is started for the number of billing cycles specified in contract_billing_cycle_on_renewal.

The action_at_term_end for the new contract term is set to renew.

evergreenContract term completes and the subscription renews.cancelContract term completes and subscription is canceled.renew_onceUsed 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.

The action_at_term_end for the new contract term is set to cancel.

total_contract_value

in cents, default=0, min=0
The sum of the totals 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. If the subscription was imported 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, 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

Sample quoted subscription [ JSON ]

Quoted subscription attributes