You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.
Home
Getting started
Authentication
Versioning
Upgrade to Product Catalog 2.0
List operations
Error handling & rate limits
Webhooks
Currencies
Advanced features
Customers
Subscriptions
Invoices and Credit Notes
Quotes
Estimates
Orders
Product Catalog
Hosted Pages
Payments
Payment sources
Payment intents
Cards
Virtual bank accounts
Transactions
3DS card payments
Payment parameters
Events
Exports
Testing
More Resources
Plans
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.
Sample plan [ JSON ]
{
"addon_applicability": "all",
"charge_model": "flat_fee",
"currency_code": "USD",
"enabled_in_hosted_pages": true,
"enabled_in_portal": true,
"free_quantity": 0,
"giftable": false,
"id": "silver",
"invoice_name": "sample plan",
"is_shippable": false,
"name": "Silver",
"object": "plan",
"period": 1,
"period_unit": "month",
"price": 5000,
"pricing_model": "flat_fee",
"resource_version": 1517505797000,
"show_description_in_invoices": false,
"show_description_in_quotes": false,
"status": "active",
"taxable": true,
"updated_at": 1517505797
}
API Index URL GET
https://{site}.chargebee.com/api/v2/plans
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
Description about the plan to show in the hosted pages & customer portal.
integer, default=1, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
enumerated string, default=month
Defines billing frequency in association with billing period.
Defines billing frequency in association with 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).
optional, enumerated string
Time unit for the trial period.
Time unit for the trial period.
Possible values are
dayIn days.monthIn months.
optional, enumerated string
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Possible values are
site_defaultThe action configured for the site at the time when the trial ends, takes effect.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
enumerated string, default=flat_fee
Defines how the recurring charges for the subscription is calculated.
Defines how the recurring charges for the subscription is calculated.
Possible 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.
integer, default=0, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
enumerated string, default=active
The plan state
The plan state
Possible 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.deletedIndicates the plan has been deleted.
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic
boolean, default=true
If true, allow checkout through plan specific hosted page URL for this plan.
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.
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
enumerated string, default=all
Indicates if all or only some addons are applicable with the plan.
Indicates if all or only some addons are applicable with the plan.
Possible values are
allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with 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.
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 HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
The HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
- India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
- The AvaTax for Sales integration has been enabled in Chargebee.
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.
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible 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.
optional, integer
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.
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.
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, string, max chars=100
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.
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.
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format:
<category-name>: <option>. For example:Location: Singapore. - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format:
<parent class>:<sub-class-1>:<sub-class-2>... - NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format:
<parent class>: <sub-class-1>: <sub-class2>....For example:Services: Plan. - Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format:
<category-name>: <option>....For example,Region: South - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format:
<parent-location>:<sub-location-1>:<sub-location-2>....For example:Location: North America: Canada - NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format
<parent-location> : <sub-location-1>: <sub-location-2>....For example:NA:US:CA - Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format:
<parent-department> : <sub-department-1>: <sub-department-2>....For example:Production: Assembly. - Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- NetSuite: Provide the “Revenue Recognition Rule Id” for the product from NetSuite.
- Intacct: If you have configured “Revenue Recognition Templates” for products in Intacct, provide the template ID for the product.
optional, boolean, default=false
If enabled, charges for this plan/addon will be added to orders.
If enabled, charges for this plan/addon will be added to orders.
optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, enumerated string
Defines the shipping frequency in association with shipping period.
Defines the shipping frequency in association with shipping period.
Possible values are
yearShip based on year(s).monthShip based on month(s).weekShip based on week(s).dayShip based on day(s).
optional, long
Version number of this resource. The
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.
optional, timestamp(UTC) in seconds
Timestamp indicating when this plan was last updated. This attribute will be present only if the resource has been updated after 2016-11-09.
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, string, max chars=500
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic
optional, string, max chars=33
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.
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=39
The price of the plan when the
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, enumerated string
The subscription channel this object originated from and is maintained in.
The subscription channel this object originated from and is maintained in.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
.
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, boolean, default=true
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, boolean, default=false
Whether the
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
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.
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, list of tier
List of tiers for this plan(applicable only if it is tiered/volume/stairtstep pricing
List of tiers for this plan(applicable only if it is tiered/volume/stairtstep pricing
Tier attributes
in cents, default=0, min=0
The per-unit price for the tier when the
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, string, max chars=33
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
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
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=39
The decimal representation of the per-unit price for the tier when the
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, list of applicable_addon
List of addons applicable with this plan.
List of addons applicable with this plan.
optional, list of attached_addon
Indicates if the addon is attached with the plan as mandatory or recommended.
Indicates if the addon is attached with the plan as mandatory or recommended.
Attached addon attributes
string, max chars=100
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
optional, integer, min=1
The number of billing cycles this addon will be attached to the plan.
The number of billing cycles this addon will be attached to the plan.
enumerated string
Specifies attachment type of the addon to the plan
Specifies attachment type of the addon to the plan
Possible values are
recommendedAddon will be charged with this plan unless specifically removed.mandatoryAddon will be always charged with this plan.
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.
The decimal representation of the quantity of the addon. Returned for quantity-based addons when multi-decimal pricing is enabled.
optional, list of event_based_addon
List of addons that will be charged on occurrence of specific event on subscribing to the plan.
List of addons that will be charged on occurrence of specific event on subscribing to the plan.
Event based addon attributes
integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
enumerated string
Event on which the addon will be charged
Event on which the 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.
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.
If enabled, the addon will be charged only at the first occurrence of the event. Applicable only for non-recurring add-ons.
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.
The decimal representation of the quantity of the addon. Returned for quantity-based addons when multi-decimal pricing is enabled.
Create a plan¶
Sample Request
curl https://{site}.chargebee.com/api/v2/plans \
-u {site_api_key}:\
-d id="silver" \
-d name="Silver" \
-d invoice_name="sample plan" \
-d price=5000
copy
Sample Response [ JSON ]
URL Format POST
https://{site}.chargebee.com/api/v2/plans
Input Parameters
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
Description about the plan to show in the hosted pages & customer portal.
optional, enumerated string
Time unit for the trial period.
Time unit for the trial period.
Possible values are
dayIn daysmonthIn months
optional, enumerated string
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Possible values are
site_defaultThe action configured for the site at the time when the trial ends, takes effect.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
optional, integer, default=1, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, enumerated string, default=month
Defines billing frequency in association with billing period.
Defines billing frequency in association with 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)
optional, in cents, min=0
The price of the plan. The unit depends on the type of currency.
The price of the plan. The unit depends on the type of currency.
optional, string, max chars=39
The price of the plan when the
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. .
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the plan.
The currency code (ISO 4217 format) of the plan.
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, enumerated string, default=flat_fee
Defines how the recurring charges for the subscription is calculated.
Defines how the recurring charges for the subscription is calculated.
Possible 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.
optional, integer, default=0, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
optional, string, max chars=33
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. .
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, enumerated string, default=all
Indicates if all or only some addons are applicable with the plan.
Indicates if all or only some addons are applicable with the plan.
Possible values are
allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, boolean, default=true
If true, allow checkout through plan specific hosted page URL for this plan.
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.
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
optional, boolean, default=true
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
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.
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 HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
The HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
- India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
- The AvaTax for Sales integration has been enabled in Chargebee.
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.
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
optional, integer
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.
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.
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, string, max chars=100
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.
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.
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format:
<category-name>: <option>. For example:Location: Singapore. - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format:
<parent class>:<sub-class-1>:<sub-class-2>... - NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format:
<parent class>: <sub-class-1>: <sub-class2>....For example:Services: Plan. - Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format:
<category-name>: <option>....For example,Region: South - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format:
<parent-location>:<sub-location-1>:<sub-location-2>....For example:Location: North America: Canada - NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format
<parent-location> : <sub-location-1>: <sub-location-2>....For example:NA:US:CA - Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format:
<parent-department> : <sub-department-1>: <sub-department-2>....For example:Production: Assembly. - Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations.
Used exclusively with the following accounting integrations.
optional, boolean, default=false
If enabled, charges for this plan/addon will be added to orders.
If enabled, charges for this plan/addon will be added to orders.
optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, enumerated string
Defines the shipping frequency in association with shipping period.
Defines the shipping frequency in association with shipping period.
Possible values are
yearShip based on year(s)monthShip based on month(s)weekShip based on week(s)dayShip based on day(s)
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, boolean, default=false
Whether the
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
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.
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, enumerated string, default=active
The plan state.
The plan state.
Possible 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.
optional, string, max chars=500
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
The url to redirect on successful claim. Eg: https://yoursite.com/claim_success.html?plan=basic.
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
pass parameters as tiers[<param name>][<idx:0..n>]
optional, in cents, default=0, min=0
The per-unit price for the tier when the
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, string, max chars=33
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
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
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
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=39
The decimal representation of the per-unit price for the tier when the
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.
Parameters for applicable_addons. Multiple applicable_addons can be passed by specifying unique indices.
pass parameters as applicable_addons[<param name>][<idx:0..n>]
pass parameters as applicable_addons[<param name>][<idx:0..n>]
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>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
Identifier of the addon. Multiple addons can be passed.
optional, integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
optional, string, max chars=33
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.
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, enumerated string
Event on which the addon will be charged
Event on which the 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.
Parameters for attached_addons. Multiple attached_addons can be passed by specifying unique indices.
pass parameters as attached_addons[<param name>][<idx:0..n>]
pass parameters as attached_addons[<param name>][<idx:0..n>]
optional, string, max chars=100
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
optional, integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
optional, string, max chars=33
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.
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, integer, min=1
The number of billing cycles this addon will be attached to the plan.
The number of billing cycles this addon will be attached to the plan.
Returns
always returned
Resource object representing plan
Resource object representing plan
Update a plan¶
When updating plans that are already linked to an invoice or a subscription, you can only update the following parameters:
- name
- invoice_name
- setup_cost
- price
- trial_period
- trial_period_unit
- redirect_url
- enabled_in_hosted_pages
- meta_data
Sample Request
curl https://{site}.chargebee.com/api/v2/plans/cb_trial \
-u {site_api_key}:\
-d invoice_name="sample plan"
copy
curl https://{site}.chargebee.com/api/v2/plans/cb_trial \
-u {site_api_key}:\
-d invoice_name="sample plan"
Sample Response [ JSON ]
URL Format POST
https://{site}.chargebee.com/api/v2/plans/{plan_id}
Input Parameters
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=500
Description about the plan to show in the hosted pages & customer portal.
Description about the plan to show in the hosted pages & customer portal.
optional, integer, min=0
The free time window for your customer to try your product. If zero is passed, the trial period will be removed.
The free time window for your customer to try your product. If zero is passed, the trial period will be removed.
optional, enumerated string
Time unit for the trial period.
Time unit for the trial period.
Possible values are
dayIn daysmonthIn months
optional, enumerated string
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Applicable only when End-of-trial Action has been enabled for the site. Whenever the plan 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. This can be overridden at the subscription-level.
Possible values are
site_defaultThe action configured for the site at the time when the trial ends, takes effect.activate_subscriptionThe subscription activates and charges are raised for non-metered items.cancel_subscriptionThe subscription cancels.
optional, integer, min=1
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
optional, enumerated string
Defines billing frequency in association with billing period.
Defines billing frequency in association with 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)
optional, in cents, min=0
The price of the plan. The unit depends on the type of currency.
The price of the plan. The unit depends on the type of currency.
optional, string, max chars=39
The price of the plan when the
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=3
The currency code (ISO 4217 format) of the plan. Applicable if Multicurrency is enabled.
The currency code (ISO 4217 format) of the plan. Applicable if Multicurrency is enabled.
optional, integer, min=1
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
The number of billing cycles the subscription is active. The subscription is moved to non renewing state and then to cancelled state automatically.
optional, enumerated string
Defines how the recurring charges for the subscription is calculated.
Defines how the recurring charges for the subscription is calculated.
Possible 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.
optional, integer, min=0
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
Free quantity the subscriptions of this plan will have. Only the quantity more than this will be charged for the subscription.
optional, string, max chars=33
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. .
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, enumerated string
Indicates if all or only some addons are applicable with the plan.
Indicates if all or only some addons are applicable with the plan.
Possible values are
allAll addons are applicable with this plan.restrictedOnly addons marked as 'applicable_addons' are applicable with the plan.
optional, string, max chars=500
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
The url to redirect on successful checkout. Eg: https://yoursite.com/success.html?plan=basic.
optional, boolean
If true, allow checkout through plan specific hosted page URL for this plan.
If true, allow checkout through plan specific hosted page URL for this plan.
optional, boolean
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
If enabled, customers can switch to this plan using the 'Change Subscription' option in the customer portal.
optional, boolean
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
Specifies whether taxes apply to this plan. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
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.
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 HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
The HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
- India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
- The AvaTax for Sales integration has been enabled in Chargebee.
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.
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
optional, integer
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.
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.
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, string, max chars=100
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.
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.
This field is to capture the Account code setup in your Accounting system for integration purposes only.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format:
<category-name>: <option>. For example:Location: Singapore. - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format:
<parent class>:<sub-class-1>:<sub-class-2>... - NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format:
<parent class>: <sub-class-1>: <sub-class2>....For example:Services: Plan. - Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format:
<category-name>: <option>....For example,Region: South - QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format:
<parent-location>:<sub-location-1>:<sub-location-2>....For example:Location: North America: Canada - NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format
<parent-location> : <sub-location-1>: <sub-location-2>....For example:NA:US:CA - Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations
Used exclusively with the following accounting integrations
- NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format:
<parent-department> : <sub-department-1>: <sub-department-2>....For example:Production: Assembly. - Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.
optional, string, max chars=100
Used exclusively with the following accounting integrations.
Used exclusively with the following accounting integrations.
optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, enumerated string
Defines the shipping frequency in association with shipping period.
Defines the shipping frequency in association with shipping period.
Possible values are
yearShip based on year(s)monthShip based on month(s)weekShip based on week(s)dayShip based on day(s)
optional, string, max chars=2000
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, boolean
Whether the
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
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.
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.
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
pass parameters as tiers[<param name>][<idx:0..n>]
optional, in cents, min=0
The per-unit price for the tier when the
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, string, max chars=33
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
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
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
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=39
The decimal representation of the per-unit price for the tier when the
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.
Parameters for applicable_addons. Multiple applicable_addons can be passed by specifying unique indices.
pass parameters as applicable_addons[<param name>][<idx:0..n>]
pass parameters as applicable_addons[<param name>][<idx:0..n>]
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>]
pass parameters as event_based_addons[<param name>][<idx:0..n>]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
Identifier of the addon. Multiple addons can be passed.
optional, integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
optional, string, max chars=33
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.
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, enumerated string
Event on which the addon will be charged
Event on which the 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.
Parameters for attached_addons. Multiple attached_addons can be passed by specifying unique indices.
pass parameters as attached_addons[<param name>][<idx:0..n>]
pass parameters as attached_addons[<param name>][<idx:0..n>]
optional, string, max chars=100
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
Identifier of the addon attached with the plan. Only recurring addons can be attached with the plan.
optional, integer, min=1
Quantity of the addon. Applicable for addons with
Quantity of the addon. Applicable for addons with
pricing_model other than flat_fee.
optional, string, max chars=33
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.
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, integer, min=1
The number of billing cycles this addon will be attached to the plan.
The number of billing cycles this addon will be attached to the plan.
Returns
always returned
Resource object representing plan
Resource object representing plan
List plans¶
Sample Request
curl https://{site}.chargebee.com/api/v2/plans \
-G \
-u {site_api_key}:\
--data-urlencode limit=3 \
--data-urlencode status[is]="active"
copy
curl https://{site}.chargebee.com/api/v2/plans \
-G \
-u {site_api_key}:\
--data-urlencode limit=3 \
--data-urlencode status[is]="active"
Sample Response [ JSON ]
URL Format GET
https://{site}.chargebee.com/api/v2/plans
Input Parameters
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set
offset to the value of next_offset obtained in the previous iteration of the API call.
optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
Filter Params
For operator usages, see the Pagination and Filtering section.
optional, string filter
A unique ID for your system to identify the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "Enterprise"
A unique ID for your system to identify the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "Enterprise"
optional, string filter
The display name used in web interface for identifying the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → name[is_not] = "plan_enterprise"
The display name used in web interface for identifying the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → name[is_not] = "plan_enterprise"
optional, in cents filter
The price of the plan. The unit depends on the type of currency.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → price[gte] = "1200"
The price of the plan. The unit depends on the type of currency.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → price[gte] = "1200"
optional, integer filter
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → period[gte] = "3"
Defines billing frequency. Example: to bill customer every 3 months, provide "3" here.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → period[gte] = "3"
optional, enumerated string filter
Defines billing frequency in association with billing period. Possible values are : day, week, month, year.
Supported operators : is, is_not, in, not_in
Example → period_unit[is] = "month"
Defines billing frequency in association with billing period. Possible values are : day, week, month, year.
Supported operators : is, is_not, in, not_in
Example → period_unit[is] = "month"
optional, integer filter
The free time window for your customer to try your product.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present
Example → trial_period[is] = "14"
The free time window for your customer to try your product.
Supported operators : is, is_not, lt, lte, gt, gte, between, is_present
Example → trial_period[is] = "14"
optional, enumerated string filter
Time unit for the trial period. Possible values are : day, month.
Supported operators : is, is_not, in, not_in
Example → trial_period_unit[is] = "day"
Time unit for the trial period. Possible values are : day, month.
Supported operators : is, is_not, in, not_in
Example → trial_period_unit[is] = "day"
optional, enumerated string filter
Indicates if all or only some addons are applicable with the plan. Possible values are : all, restricted.
Supported operators : is, is_not, in, not_in
Example → addon_applicability[is_not] = "all"
Indicates if all or only some addons are applicable with the plan. Possible values are : all, restricted.
Supported operators : is, is_not, in, not_in
Example → addon_applicability[is_not] = "all"
optional, boolean filter
Specifies if the plan should be gifted or not. Possible values are : true, false
Supported operators : is
Example → giftable[is] = "true"
Specifies if the plan should be gifted or not. Possible values are : true, false
Supported operators : is
Example → giftable[is] = "true"
optional, enumerated string filter
Defines how the recurring charges for the subscription is calculated. Possible values are : flat_fee, per_unit, tiered, volume, stairstep.
Supported operators : is, is_not, in, not_in
Example → pricing_model[is] = "flat_fee"
Defines how the recurring charges for the subscription is calculated. Possible values are : flat_fee, per_unit, tiered, volume, stairstep.
Supported operators : is, is_not, in, not_in
Example → pricing_model[is] = "flat_fee"
optional, enumerated string filter
The plan state. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in
Example → status[is] = "active"
The plan state. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in
Example → status[is] = "active"
optional, timestamp(UTC) in seconds filter
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
Supported operators : after, before, on, between
Example → updated_at[before] = "1243545465"
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
Supported operators : after, before, on, between
Example → updated_at[before] = "1243545465"
optional, string filter
The currency code (ISO 4217 format) of the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → currency_code[is] = "USD"
The currency code (ISO 4217 format) of the plan.
Supported operators : is, is_not, starts_with, in, not_in
Example → currency_code[is] = "USD"
Returns
always returned
Resource object representing plan
Resource object representing plan
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.
Retrieve a plan¶
Sample Request
curl https://{site}.chargebee.com/api/v2/plans/sub_free \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/plans/sub_free \
-u {site_api_key}:
Sample Response [ JSON ]
URL Format GET
https://{site}.chargebee.com/api/v2/plans/{plan_id}
Returns
always returned
Resource object representing plan
Resource object representing plan
Sample admin console URL
https://{site}.chargebee.com/admin-console/plans/123x
Delete a plan¶
Deletes or archives a plan. This endpoint behaves differently based on the scenarios listed below:
- When the plan has subscriptions/invoices linked, it is not deleted. Instead, it is moved to the
archivedstate. Subscriptions already on it continue to renew. However, until the plan is unarchived,- No other subscription can use the plan
- You cannot update the plan
- When the plan does not have any subscriptions or invoices linked to it, the endpoint permanently deletes the plan from your Chargebee site. You cannot undo this action.
Sample Request
curl https://{site}.chargebee.com/api/v2/plans/demo_plan/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/plans/demo_plan/delete \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
URL Format POST
https://{site}.chargebee.com/api/v2/plans/{plan_id}/delete
Returns
always returned
Resource object representing plan
Resource object representing plan
Copy a plan¶
Creates a plan in this site by copying its configurations from another site. Copying of archived plans is not supported.
Note: The attribute tax_profile_id is not copied. In effect, if the plan is taxable, it will be mapped to the Primary tax profile.
This API is not enabled for live sites by default. Please contact support to get this enabled.
Sample Request
curl https://{site}.chargebee.com/api/v2/plans/copy \
-u {site_api_key}:\
-d from_site="merchant-test" \
-d id_at_from_site="silver-plan-new"
copy
curl https://{site}.chargebee.com/api/v2/plans/copy \
-u {site_api_key}:\
-d from_site="merchant-test" \
-d id_at_from_site="silver-plan-new"
Sample Response [ JSON ]
URL Format POST
https://{site}.chargebee.com/api/v2/plans/copy
Input Parameters
required, string, max chars=50
Your Chargebee site name having the plan to be copied.
Note: Unless you are copying from a twin site (acme & acme-test are twin sites), contact support to have this allow-listed.
Your Chargebee site name having the plan to be copied.
Note: Unless you are copying from a twin site (acme & acme-test are twin sites), contact support to have this allow-listed.
required, string, max chars=100
Id of the plan to be copied. The new plan created in this site will have the same Id.
Id of the plan to be copied. The new plan created in this site will have the same Id.
Returns
always returned
Resource object representing plan
Resource object representing plan
Unarchive a plan¶
archived earlier.
Sample Request
curl https://{site}.chargebee.com/api/v2/plans/archieved_plan/unarchive \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/plans/archieved_plan/unarchive \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
URL Format POST
https://{site}.chargebee.com/api/v2/plans/{plan_id}/unarchive
Returns
always returned
Resource object representing plan
Resource object representing plan