Specifies the price with billing frequency for a subscription. Create separate plans for varied price or billing frequency. For example, if you need to charge $10 per month for a group of customers and $100 per year for another group of customers, then create separate plans for each.
A unique ID for your system to identify the plan.
string, max chars=100
The display name used in web interface for identifying the plan.
string, max chars=50
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
Description about the plan to show in the hosted pages & customer portal.
optional, string, max chars=500
The price of the plan.
optional, in cents, min=0
The currency code (ISO 4217 format) of the plan.
string, max chars=3
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
integer, default=1, min=1
Defines billing frequency in association with billing period.
enumerated string, default=monthPossible values are
dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).
The free time window for your customer to try your product.
optional, integer, min=1
Time unit for the trial period.
optional, enumerated stringPossible values are
dayIn days.monthIn months.
Defines how the recurring charges for the subscription is calculated.
enumerated string, default=flat_feePossible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
integer, default=0, min=0
One-time setup fee charged as part of the first invoice.
optional, in cents, min=1
The plan state.
enumerated string, default=activePossible values are
activeNew subscriptions can be created with the plan.archivedNo new subscriptions allowed for the plan. Existing subscriptions on this plan will remain as-is and can be migrated to another active plan if required.
Time at which the plan was moved to archived status.
optional, timestamp(UTC) in seconds
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, integer, min=1
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, string, max chars=500
If true, allow checkout through plan specific hosted page URL for this plan.
boolean, default=true
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
boolean, default=true
Indicates if all or only some addons are applicable with the plan.
enumerated string, default=allPossible values are
allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.
The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=50
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
TaxJar integration.
optional, string, max chars=50
Indicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.
optional, string, max chars=100
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
If enabled, charges for this plan/addon will be added to orders.
optional, boolean, default=false
shipping_frequency_period
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1
shipping_frequency_period_unit
Defines the shipping frequency in association with shipping period.
optional, enumerated stringPossible values are
yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
Timestamp indicating when this plan was last updated. This attribute will be present only if the resource has been updated after 2016-11-09.
optional, timestamp(UTC) in seconds
Specifies if the plan should be gifted or not.
boolean, default=false
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
optional, string, max chars=500
The quantity of the plan that is available free-of-charge, represented in decimal. When a subscription is created for this plan or when the plan of a subscription is changed to this one, only the quantity above this number is charged for. Applicable for quantity-based plans and only when
multi-decimal pricing is enabled.
optional, string, max chars=33
The price of the plan when the
pricing_model
is
flat_fee
. When the pricing model is
per_unit
, it is the price per unit quantity of the item. Not applicable for the other pricing models. The value is in decimal and in major units of the currency. Also, this is only applicable when
multi-decimal pricing is enabled.
optional, string, max chars=33
Invoice Notes for this resource.
optional, string, max chars=2000
Specifies if the plan should be taxed or not.
optional, boolean, default=true
Tax profile of the plan.
optional, string, max chars=50
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
show_description_in_invoices
Whether the
plan description should be shown on
invoice PDFs. If this Boolean is changed, only invoices generated (or
regenerated) after the change are affected; past invoices are not.
optional, boolean, default=false
show_description_in_quotes
Whether the
plan description should be shown on
quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
optional, boolean, default=false
List of tiers for this plan(applicable only if it is tiered/volume/stairtstep pricing.
optional, list of tier
The lower limit of a range of units for the tier.
integer, min=1
The upper limit of a range of units for the tier.
optional, integer
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.
in cents, default=0, min=0
The decimal representation of the 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 is enabled.
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 is enabled.
optional, string, max chars=33
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 addon. The value is in major units of the currency. Returned when the plan is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
List of addons applicable with this plan.
optional, list of applicable_addon
Applicable addon attributes
Identifier of the addon appplicable to the plan.
string, max chars=100
Indicates if the addon is attached with the plan as mandatory or recommended.
optional, list of attached_addon
Attached addon attributes
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
string, max chars=100
Quantity of the addon. Applicable only for the quantity based addons.
integer, min=1
The number of billing cycles this addon will be attached to the plan.
optional, integer, min=1
Specifies attachment type of the addon to the plan.
enumerated stringPossible values are
recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.
The decimal representation of the quantity of the addon. Returned for quantity-based addons when
multi-decimal pricing is enabled.
optional, string, max chars=33
List of addons that will be charged on occurrence of specific event on subscribing to the plan.
optional, list of event_based_addon
Event based addon attributes
Identifier of the addon. Multiple addons can be passed.
string, max chars=100
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
integer, min=1
Event on which the addon will be charged.
enumerated stringPossible 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.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
boolean, default=true
The decimal representation of the quantity of the addon. Returned for quantity-based addons when
multi-decimal pricing is enabled.
optional, string, max chars=33
Create a new plan.
A unique ID for your system to identify the plan.
required, string, max chars=100
The display name used in web interface for identifying the plan.
required, string, max chars=50
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
Description about the plan to show in the hosted pages & customer portal.
optional, string, max chars=500
The free time window for your customer to try your product.
optional, integer, min=1
Time unit for the trial period.
optional, enumerated stringPossible values are
dayIn days.monthIn months.
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, integer, default=1, min=1
Defines billing frequency in association with billing period.
optional, enumerated string, default=monthPossible values are
dayCharge based on day(s).weekCharge based on week(s).monthCharge based on month(s).yearCharge based on year(s).
One-time setup fee charged as part of the first invoice.
optional, in cents, min=1
The price of the plan.
optional, in cents, min=0
The price of the plan when the
pricing_model
is
flat_fee
. When the pricing model is
per_unit
, it is the price per unit quantity of the plan. Not applicable for the other pricing models. The value is in decimal and in major units of the currency. Also, this is only applicable when
multi-decimal pricing is enabled. .
optional, string, max chars=33
The currency code (ISO 4217 format) of the plan.
required if Multicurrency is enabled, string, max chars=3
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, integer, min=1
Defines how the recurring charges for the subscription is calculated.
optional, enumerated string, default=flat_feePossible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
optional, integer, default=0, min=0
The quantity of the plan that is available free-of-charge, represented in decimal. When a subscription is created for this plan or when the plan of a subscription is changed to this one, only the quantity above this number is charged for. Applicable for quantity-based plans and only when
multi-decimal pricing is enabled. .
optional, string, max chars=33
Indicates if all or only some addons are applicable with the plan.
optional, enumerated string, default=allPossible values are
allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, string, max chars=500
If true, allow checkout through plan specific hosted page URL for this plan.
optional, boolean, default=true
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
optional, boolean, default=true
Specifies if the plan should be taxed or not.
optional, boolean, default=true
Tax profile of the plan.
optional, string, max chars=50
The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=50
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
TaxJar integration.
optional, string, max chars=50
Indicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, integer
The field is used as Product name/code in your third party accounting application. Chargebee will use it as an alternate name in your accounting application.
optional, string, max chars=100
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
The name of the category of your product in Xero. If you've integrated with QuickBooks, this will be the "Class". Use the format "<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
If enabled, charges for this plan/addon will be added to orders.
optional, boolean, default=false
shipping_frequency_period
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1
shipping_frequency_period_unit
Defines the shipping frequency in association with shipping period.
optional, enumerated stringPossible values are
yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).
Invoice Notes for this resource.
optional, string, max chars=2000
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
show_description_in_invoices
Whether the
plan description should be shown on
invoice PDFs. If this Boolean is changed, only invoices generated (or
regenerated) after the change are affected; past invoices are not.
optional, boolean, default=false
show_description_in_quotes
Whether the
plan description should be shown on
quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
optional, boolean, default=false
Specifies if the plan should be gifted or not.
optional, boolean, default=false
The plan state.
optional, enumerated string, default=activePossible values are
activeNew subscriptions can be created with the plan.archivedNo new subscriptions allowed for the plan. Existing subscriptions on this plan will remain as-is and can be migrated to another active plan if required.
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
optional, string, max chars=500
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tiers[starting_unit][0..n]
The lower limit of a range of units for the tier.
optional, integer, min=1
The upper limit of a range of units for the tier.
optional, integer
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.
optional, in cents, default=0, min=0
tiers[starting_unit_in_decimal][0..n]
The decimal representation of the 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. Applicable only when the
pricing_model
is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled. .
optional, string, max chars=33
tiers[ending_unit_in_decimal][0..n]
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. Applicable only when the
pricing_model
is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled. .
optional, string, max chars=33
tiers[price_in_decimal][0..n]
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 plan. The value is in major units of the currency. Applicable when the plan is quantity-based and
multi-decimal pricing is enabled. .
optional, string, max chars=33
Parameters for applicable_addons. Multiple applicable_addons can be passed by specifying unique indices.
pass parameters as applicable_addons[<param name>][<idx:0..n>]
applicable_addons[id][0..n]
Identifier of the addon appplicable to the plan.
optional, string, max chars=100
Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.
pass parameters as event_based_addons[<param name>][<idx:0..n>]
event_based_addons[id][0..n]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
event_based_addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, min=1
event_based_addons[quantity_in_decimal][0..n]
The decimal representation of the quantity of the addon purchased. Can be provided for quantity-based addons and only when
multi-decimal pricing is enabled. .
optional, string, max chars=33
event_based_addons[on_event][0..n]
Event on which the addon will be charged.
optional, enumerated stringPossible 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.
event_based_addons[charge_once][0..n]
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
optional, boolean, default=true
Parameters for attached_addons. Multiple attached_addons can be passed by specifying unique indices.
pass parameters as attached_addons[<param name>][<idx:0..n>]
attached_addons[id][0..n]
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
optional, string, max chars=100
attached_addons[quantity][0..n]
Quantity of the addon. Applicable only for the quantity based addons.
optional, integer, min=1
attached_addons[quantity_in_decimal][0..n]
The default quantity of the addon to be attached when the quantity is not specified while
creating/
updating the subscription. The value is in decimal. Can be provided for quantity-based addons and only when
multi-decimal pricing is enabled. .
optional, string, max chars=33
attached_addons[billing_cycles][0..n]
The number of billing cycles this addon will be attached to the plan.
optional, integer, min=1
attached_addons[type][0..n]
Specifies attachment type of the addon to the plan.
optional, enumerated stringPossible values are
recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.
When updating plans that are already linked to an invoice or a subscription, you can only update the following parameters: