An item price is a price point for an item. It defines the currency, pricing model, price, billing period and other attributes for an item. For example, consider a cloud storage service as an item. Then each of the following defines an item price:
The cloud storage sold at USD 10 per month.
The same service sold at AUD 100 per year.
The service sold at a monthly rate determined by the following stairstep pricing model:
1–10 users for EUR 10
11–25 users for EUR 20
26–50 users for EUR 45
51 and above for EUR 100
The billing period of an item price (only applies to plan-item prices and addon-item prices), is the period of the item price in period_units. An item can have only one item price for a given currency and billing period.
Types of item prices
The type of an item price corresponds to the type of the item that the item price belongs to. In other words, item prices can be of the following types:
string, max chars=100 A unique display name for the item price in the Chargebee UI. If external_name is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages.
optional, string, max chars=2000 Description of the item price.
Note:
The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters. For example: <ul><li>testing</li><li>desc</li></ul>. Total with tags: 38 characters, inner text: 'testing desc' (12 characters).
If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
optional, enumerated string The status of the item price.
Possible values are
activeThe item price can be used in subscriptions.archivedThe item price is no longer active and cannot be used in new subscriptions or added to existing ones. Existing subscriptions that already have this item price will continue to renew with the item price.deletedIndicates that the item price has been deleted. The id and name can be reused.
optional, string, max chars=100 The name of the item price used in customer-facing pages and documents. These include invoices and hosted pages. If not provided, then name is used
Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.
Possible values are
site_defaultUse the site-wide proration setting.partial_termProrate the charges or credits for the rest of the current term.full_termCharge the full price of the addon item price or give the full credit. Don't apply any proration.
The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
Possible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.volumeThe per unit price is based on the tier that the total quantity falls in.
optional, in cents, min=0 The cost of the item price 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 the minor unit of the currency.
optional, string, max chars=39 The price of the item 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.
When the item type is plan: The billing period of the plan in period_units. For example, create a 6 month plan by providing period as 6 and period_unit as month.
When item type is addon: The period of the addon in period_units. For example, create an addon with a 2 month period by providing period as 2 and period_unit as month. The period of an addon is the duration for which its price applies. When attached to a plan, the addon is billed for the billing period of the plan. Learn more.
If subscriptions or invoices exist for this item price, period cannot be changed. The period is mandatory when the item type is plan or addon
string, max chars=3 The currency code (ISO 4217 format) for the item price. If subscriptions, invoices or differential prices exist for this item price, currency_code cannot be changed.
optional, enumerated string The unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed. The period_unit is mandatory when the item type is plan or addon
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
optional, integer, min=0 The trial period of the plan in trial_period_units. You can also set trial periods for addons; contact Support to enable that feature.
optional, enumerated string Applicable only when End-of-trial Action has been enabled for the site. Specifies the operation to be carried out for the subscription once the trial ends. Whenever the item.type is plan and a trial period is defined for this item price, this attribute (parameter) is returned (required). 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.
If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
Note: If you want to change the billing_cycles to unlimited renewals, enter an empty string. This value can only be updated if the item_price is not attached to a subscription or invoice. If no billing_cycles value is entered, then by default the value will be set as unlimited billing_cycles renewals.
integer, default=0, min=0 Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
Note:free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.
optional, string, max chars=33 The quantity of the item 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 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, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
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.
optional, boolean, default=true Specifies whether taxes apply to this item price. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
planAn essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription.addonA recurring component that can be added to a subscription in addition to its plan.chargeA non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer directly without being applied to a subscription.
optional, boolean Whether the item price's 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 item price's 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, string, max chars=50 The unique ID of the
business entity of this item_family. This is applicable only when multiple business entities have been created for the site. The value of this attribute indicates that the resource is specific to the given business entity.
in cents, default=0, min=0 The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
optional, enumerated string Pricing type for the tier.
Possible values are
per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20, consuming 400 units will result in a charge of $80 (4 × $20).
optional, integer, min=1 Package size for the tier when pricing type is package. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.
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, 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:
India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
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.
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.
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.
This is a list of the event types we currently support. We will continue
to add more events moving forward. All events follow a uniform pattern -
<resource>_<event_name>. The resources that will be
present in the event content are provided beneath each event type's
description.
Note: If consolidated invoicing is enabled, the
attributes invoice.subscription_id and
credit_note.subscription_id should not be used
(as it will not be present if the invoice / credit note has lines from
multiple subscriptions). Instead to know the related subscriptions,
their line_items' subscription_id attribute should be referred.
string, max chars=100 A unique display name for the item price in the Chargebee UI. If external_name is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages.
optional, string, max chars=2000 Description of the item price.
Note:
The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters. For example: <ul><li>testing</li><li>desc</li></ul>. Total with tags: 38 characters, inner text: 'testing desc' (12 characters).
If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
optional, enumerated string The status of the item price.
Possible values are
activeThe item price can be used in subscriptions.archivedThe item price is no longer active and cannot be used in new subscriptions or added to existing ones. Existing subscriptions that already have this item price will continue to renew with the item price.deletedIndicates that the item price has been deleted. The id and name can be reused.
optional, string, max chars=100 The name of the item price used in customer-facing pages and documents. These include invoices and hosted pages. If not provided, then name is used
Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.
Possible values are
site_defaultUse the site-wide proration setting.partial_termProrate the charges or credits for the rest of the current term.full_termCharge the full price of the addon item price or give the full credit. Don't apply any proration.
The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
Possible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.volumeThe per unit price is based on the tier that the total quantity falls in.
optional, in cents, min=0 The cost of the item price 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 the minor unit of the currency.
optional, string, max chars=39 The price of the item 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.
When the item type is plan: The billing period of the plan in period_units. For example, create a 6 month plan by providing period as 6 and period_unit as month.
When item type is addon: The period of the addon in period_units. For example, create an addon with a 2 month period by providing period as 2 and period_unit as month. The period of an addon is the duration for which its price applies. When attached to a plan, the addon is billed for the billing period of the plan. Learn more.
If subscriptions or invoices exist for this item price, period cannot be changed. The period is mandatory when the item type is plan or addon
string, max chars=3 The currency code (ISO 4217 format) for the item price. If subscriptions, invoices or differential prices exist for this item price, currency_code cannot be changed.
optional, enumerated string The unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed. The period_unit is mandatory when the item type is plan or addon
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
optional, integer, min=0 The trial period of the plan in trial_period_units. You can also set trial periods for addons; contact Support to enable that feature.
optional, enumerated string Applicable only when End-of-trial Action has been enabled for the site. Specifies the operation to be carried out for the subscription once the trial ends. Whenever the item.type is plan and a trial period is defined for this item price, this attribute (parameter) is returned (required). 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.
If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
Note: If you want to change the billing_cycles to unlimited renewals, enter an empty string. This value can only be updated if the item_price is not attached to a subscription or invoice. If no billing_cycles value is entered, then by default the value will be set as unlimited billing_cycles renewals.
integer, default=0, min=0 Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
Note:free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.
optional, string, max chars=33 The quantity of the item 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 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, long Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
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.
optional, boolean, default=true Specifies whether taxes apply to this item price. This value is set and returned even if Taxes have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.
planAn essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription.addonA recurring component that can be added to a subscription in addition to its plan.chargeA non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer directly without being applied to a subscription.
optional, boolean Whether the item price's 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 item price's 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, string, max chars=50 The unique ID of the
business entity of this item_family. This is applicable only when multiple business entities have been created for the site. The value of this attribute indicates that the resource is specific to the given business entity.
required, string, max chars=100 A unique display name for the item price in the Chargebee UI. If external_name is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages.
optional, string, max chars=2000 Description of the item price.
Note:
The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters. For example: <ul><li>testing</li><li>desc</li></ul>. Total with tags: 38 characters, inner text: 'testing desc' (12 characters).
If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
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.
Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.
Possible values are
site_defaultUse the site-wide proration setting.partial_termProrate the charges or credits for the rest of the current term.full_termCharge the full price of the addon item price or give the full credit. Don't apply any proration.
optional, string, max chars=100 The name of the item price used in customer-facing pages and documents. These include invoices and hosted pages. If not provided, then name is used.
optional, boolean, default=true Specifies whether taxes apply to this item price. 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, integer, default=0, min=0 Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
Note:free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.
optional, string, max chars=33 The quantity of the item 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, boolean, default=false Whether the item price's 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 item price's 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, string, max chars=50 The unique ID of the business entity for this item_price. This is applicable only when multiple business entities have been created for the site. When provided, the operation will read or write data associated with the specified business entity. If not provided, the resource will be created at the site level, and the business_entity_id will not be included in the API response.
Note
An alternative way of passing this parameter is by means of a custom HTTP header.
The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
Possible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.volumeThe per unit price is based on the tier that the total quantity falls in.
optional, in cents, min=0 The cost of the item price 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 the minor unit of the currency.
optional, string, max chars=39 The price of the item 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 unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed. The period_unit is mandatory when the item type is plan or addon.
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
When the item type is plan: The billing period of the plan in period_units. For example, create a 6 month plan by providing period as 6 and period_unit as month.
When item type is addon: The period of the addon in period_units. For example, create an addon with a 2 month period by providing period as 2 and period_unit as month. The period of an addon is the duration for which its price applies. When attached to a plan, the addon is billed for the billing period of the plan. Learn more.
If subscriptions or invoices exist for this item price, period cannot be changed. The period is mandatory when the item type is plan or addon.
optional, integer, min=0 The trial period of the plan in trial_period_units. You can also set trial periods for addons; contact Support to enable that feature.
If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
Note: If you want to change the billing_cycles to unlimited renewals, enter an empty string. This value can only be updated if the item_price is not attached to a subscription or invoice. If no billing_cycles value is entered, then by default the value will be set as unlimited billing_cycles renewals.
optional, enumerated string Applicable only when End-of-trial Action has been enabled for the site. Specifies the operation to be carried out for the subscription once the trial ends. Whenever the item.type is plan and a trial period is defined for this item price, this attribute (parameter) is returned (required). 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.
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
per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20, consuming 400 units will result in a charge of $80 (4 × $20).
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices. pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
optional, string, max chars=100 A unique display name for the item price in the Chargebee UI. If external_name is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages.
optional, string, max chars=2000 Description of the item price.
Note:
The description field supports up to 2000 characters, including HTML tags. The inner text (excluding HTML tags) must not exceed 500 characters. For example: <ul><li>testing</li><li>desc</li></ul>. Total with tags: 38 characters, inner text: 'testing desc' (12 characters).
If your input includes characters requiring sanitization, such as incomplete HTML tags, the sanitization process may alter the input and increase its length. If the sanitized content exceeds the allowed limit, the request will be rejected.
Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.
Possible values are
site_defaultUse the site-wide proration setting.partial_termProrate the charges or credits for the rest of the current term.full_termCharge the full price of the addon item price or give the full credit. Don't apply any proration.
optional, enumerated string The status of the item price.
Possible values are
activeThe item price can be used in subscriptions.archivedThe item price is no longer active and cannot be used in new subscriptions or added to existing ones. Existing subscriptions that already have this item price will continue to renew with the item price.
optional, string, max chars=100 The name of the item price used in customer-facing pages and documents. These include invoices and hosted pages. If not provided, then name is used.
optional, string, max chars=3 The currency code (ISO 4217 format) for the item price. If subscriptions, invoices or differential prices exist for this item price, currency_code cannot be changed.
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.
optional, boolean, default=true Specifies whether taxes apply to this item price. 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, integer, default=0, min=0 Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
Note:free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.
optional, string, max chars=33 The quantity of the item 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 pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
Possible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.volumeThe per unit price is based on the tier that the total quantity falls in.
optional, in cents, min=0 The cost of the item price 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 the minor unit of the currency.
optional, string, max chars=39 The price of the item 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.
When the item type is plan: The billing period of the plan in period_units. For example, create a 6 month plan by providing period as 6 and period_unit as month.
When item type is addon: The period of the addon in period_units. For example, create an addon with a 2 month period by providing period as 2 and period_unit as month. The period of an addon is the duration for which its price applies. When attached to a plan, the addon is billed for the billing period of the plan. Learn more.
Note
If subscriptions or invoices exist for this item price, the period cannot be changed.
optional, integer, min=0 The trial period of the plan in trial_period_units. You can also set trial periods for addons; contact Support to enable that feature.
If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
Note: If you want to change the billing_cycles to unlimited renewals, enter an empty string. This value can only be updated if the item_price is not attached to a subscription or invoice. If no billing_cycles value is entered, then by default the value will be set as unlimited billing_cycles renewals.
optional, enumerated string Applicable only when End-of-trial Action has been enabled for the site. Specifies the operation to be carried out for the subscription once the trial ends. Whenever the item.type is plan and a trial period is defined for this item price, this attribute (parameter) is returned (required). 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, boolean Whether the item price's 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 item price's description should be shown on quote PDFs. If this Boolean is changed, only quotes created after the change are affected; past quotes are not.
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
per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20, consuming 400 units will result in a charge of $80 (4 × $20).
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices. pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
Returns a list of item prices satisfying all the conditions specified in the filter parameters below. The list is sorted by the date of creation in descending order.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
optional, string, max chars=1000 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, string filter Filter item prices based on their id.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →id[is] = "basic_USD"
+
id
Filter item prices based on their id. pass parameters as id[<param name>][<operator>]
id[is][operator]
id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
id[is_not][operator]
id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
id[starts_with][operator]
id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
id[in][operator]
id[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
id[not_in][operator]
id[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
name[<operator>]
name[<operator>]
optional, string filter Filter item prices based on their names.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →name[is] = "basic USD"
+
name
Filter item prices based on their names. pass parameters as name[<param name>][<operator>]
name[is][operator]
name[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
name[is_not][operator]
name[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
name[starts_with][operator]
name[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
name[in][operator]
name[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
name[not_in][operator]
name[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
pricing_model[<operator>]
pricing_model[<operator>]
optional, enumerated string filter Filter item prices based on their pricing_model. Possible values are : flat_fee, per_unit, tiered, volume, stairstep Supported operators : is, is_not, in, not_in
Example →pricing_model[is] = "flat_fee"
+
pricing_model
Filter item prices based on their pricing_model. pass parameters as pricing_model[<param name>][<operator>]
pricing_model[is][operator]
pricing_model[is][operator]
optional, enumerated string filter Possible values are : flat_fee, per_unit, tiered, volume, stairstep Supported operators :
Example →
pricing_model[is_not][operator]
pricing_model[is_not][operator]
optional, enumerated string filter Possible values are : flat_fee, per_unit, tiered, volume, stairstep Supported operators :
Example →
pricing_model[in][operator]
pricing_model[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
pricing_model[not_in][operator]
pricing_model[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_id[<operator>]
item_id[<operator>]
optional, string filter Filter item prices based on their item_id.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →item_id[is] = "basic"
+
item_id
Filter item prices based on their item_id. pass parameters as item_id[<param name>][<operator>]
item_id[is][operator]
item_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_id[is_not][operator]
item_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_id[starts_with][operator]
item_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_id[in][operator]
item_id[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_id[not_in][operator]
item_id[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_family_id[<operator>]
item_family_id[<operator>]
optional, string filter Filter item prices based on item_family_id.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →item_family_id[is] = "Acme"
+
item_family_id
Filter item prices based on item_family_id. pass parameters as item_family_id[<param name>][<operator>]
item_family_id[is][operator]
item_family_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_family_id[is_not][operator]
item_family_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_family_id[starts_with][operator]
item_family_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
item_family_id[in][operator]
item_family_id[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_family_id[not_in][operator]
item_family_id[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_type[<operator>]
item_type[<operator>]
optional, enumerated string filter Filter item prices based on item_type. Possible values are : plan, addon, charge Supported operators : is, is_not, in, not_in
Example →item_type[is] = "plan"
+
item_type
Filter item prices based on item_type. pass parameters as item_type[<param name>][<operator>]
item_type[is][operator]
item_type[is][operator]
optional, enumerated string filter Possible values are : plan, addon, charge Supported operators :
Example →
item_type[is_not][operator]
item_type[is_not][operator]
optional, enumerated string filter Possible values are : plan, addon, charge Supported operators :
Example →
item_type[in][operator]
item_type[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
item_type[not_in][operator]
item_type[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
currency_code[<operator>]
currency_code[<operator>]
optional, string filter Filter item prices based on their currency_code.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →currency_code[is] = "USD"
+
currency_code
Filter item prices based on their currency_code. pass parameters as currency_code[<param name>][<operator>]
currency_code[is][operator]
currency_code[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
currency_code[is_not][operator]
currency_code[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
currency_code[starts_with][operator]
currency_code[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
currency_code[in][operator]
currency_code[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
currency_code[not_in][operator]
currency_code[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
price_variant_id[<operator>]
price_variant_id[<operator>]
optional, string filter Filter item prices based on their price_variant_id.Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example →price_variant_id[is] = "tamilNadu-India"
+
price_variant_id
Filter item prices based on their price_variant_id. pass parameters as price_variant_id[<param name>][<operator>]
price_variant_id[is][operator]
price_variant_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
price_variant_id[is_not][operator]
price_variant_id[is_not][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
price_variant_id[starts_with][operator]
price_variant_id[starts_with][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
price_variant_id[in][operator]
price_variant_id[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
price_variant_id[not_in][operator]
price_variant_id[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
trial_period[<operator>]
trial_period[<operator>]
optional, number filter Filter item prices based on their trial_period.Possible values are : Supported operators : is, is_not, lt, lte, gt, gte, between
Example →trial_period[is] = "14"
+
trial_period
Filter item prices based on their trial_period. pass parameters as trial_period[<param name>][<operator>]
trial_period[is][operator]
trial_period[is][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[is_not][operator]
trial_period[is_not][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[lt][operator]
trial_period[lt][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[lte][operator]
trial_period[lte][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[gt][operator]
trial_period[gt][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[gte][operator]
trial_period[gte][operator]
optional, number filter Possible values are : Supported operators :
Example →
trial_period[between][operator]
trial_period[between][operator]
optional, string filter Possible values are : Supported operators :
Example →
trial_period_unit[<operator>]
trial_period_unit[<operator>]
optional, enumerated string filter Filter item prices based on their trial_period_unit. Possible values are : day, month Supported operators : is, is_not, in, not_in
Example →trial_period_unit[is] = "day"
+
trial_period_unit
Filter item prices based on their trial_period_unit. pass parameters as trial_period_unit[<param name>][<operator>]
trial_period_unit[is][operator]
trial_period_unit[is][operator]
optional, enumerated string filter Possible values are : day, month Supported operators :
Example →
trial_period_unit[is_not][operator]
trial_period_unit[is_not][operator]
optional, enumerated string filter Possible values are : day, month Supported operators :
Example →
trial_period_unit[in][operator]
trial_period_unit[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
trial_period_unit[not_in][operator]
trial_period_unit[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
status[<operator>]
status[<operator>]
optional, enumerated string filter Filter item prices based on their status. Possible values are : active, archived, deleted Supported operators : is, is_not, in, not_in
Example →status[is] = "active"
+
status
Filter item prices based on their status. pass parameters as status[<param name>][<operator>]
status[is][operator]
status[is][operator]
optional, enumerated string filter Possible values are : active, archived, deleted Supported operators :
Example →
status[is_not][operator]
status[is_not][operator]
optional, enumerated string filter Possible values are : active, archived, deleted Supported operators :
Example →
status[in][operator]
status[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
status[not_in][operator]
status[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
updated_at[<operator>]
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter Filter item prices based on their updated_at.Possible values are : Supported operators : after, before, on, between
Example →updated_at[after] = "1243545465"
+
updated_at
Filter item prices based on their updated_at. pass parameters as updated_at[<param name>][<operator>]
updated_at[after][operator]
updated_at[after][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
updated_at[before][operator]
updated_at[before][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
updated_at[on][operator]
updated_at[on][operator]
optional, timestamp(UTC) in seconds filter Possible values are : Supported operators :
Example →
updated_at[between][operator]
updated_at[between][operator]
optional, string filter Possible values are : Supported operators :
Example →
business_entity_id[<operator>]
business_entity_id[<operator>]
optional, string filter The unique ID of the
business entity of this item_price. Learn more about all the scenarios before using this filter.
Possible values are : Supported operators : is, is_present
Example →business_entity_id[is] = "business_entity_id"
+
business_entity_id
The unique ID of the
business entity of this item_price. Learn more about all the scenarios before using this filter.
pass parameters as business_entity_id[<param name>][<operator>]
business_entity_id[is][operator]
business_entity_id[is][operator]
optional, string, min chars=1 filter Possible values are : Supported operators :
Example →
business_entity_id[is_present][operator]
business_entity_id[is_present][operator]
optional, enumerated string filter Possible values are : true, false Supported operators :
Example →
include_site_level_resources[<operator>]
include_site_level_resources[<operator>]
optional, enumerated string filter
Default value is true . To exclude site-level resources in specific cases, set this parameter to false.
Possible values are : true, false Supported operators : is
Example →include_site_level_resources[is] = "null"
+
include_site_level_resources
Default value is true . To exclude site-level resources in specific cases, set this parameter to false.
pass parameters as include_site_level_resources[<param name>][<operator>]
include_site_level_resources[is][operator]
include_site_level_resources[is][operator]
optional, enumerated string filter Possible values are : true, false Supported operators :
Example →
period_unit[<operator>]
period_unit[<operator>]
optional, enumerated string filter Filter item prices based on their period_unit. Possible values are : day, week, month, year Supported operators : is, is_not, in, not_in
Example →period_unit[is] = "month"
+
period_unit
Filter item prices based on their period_unit. pass parameters as period_unit[<param name>][<operator>]
period_unit[is][operator]
period_unit[is][operator]
optional, enumerated string filter Possible values are : day, week, month, year Supported operators :
Example →
period_unit[is_not][operator]
period_unit[is_not][operator]
optional, enumerated string filter Possible values are : day, week, month, year Supported operators :
Example →
period_unit[in][operator]
period_unit[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
period_unit[not_in][operator]
period_unit[not_in][operator]
optional, string filter Possible values are : Supported operators :
Example →
period[<operator>]
period[<operator>]
optional, number filter Filter item prices based on their period.Possible values are : Supported operators : is, is_not, lt, lte, gt, gte, between
Example →period[is] = "3"
+
period
Filter item prices based on their period. pass parameters as period[<param name>][<operator>]
period[is][operator]
period[is][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[is_not][operator]
period[is_not][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[lt][operator]
period[lt][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[lte][operator]
period[lte][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[gt][operator]
period[gt][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[gte][operator]
period[gte][operator]
optional, number filter Possible values are : Supported operators :
Example →
period[between][operator]
period[between][operator]
optional, string filter Possible values are : Supported operators :
Example →
channel[<operator>]
channel[<operator>]
optional, enumerated string filter The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store Supported operators : is, is_not, in, not_in
Example →channel[is] = "APP STORE"
+
channel
The subscription channel this object originated from and is maintained in. pass parameters as channel[<param name>][<operator>]
channel[is][operator]
channel[is][operator]
optional, enumerated string filter Possible values are : web, app_store, play_store Supported operators :
Example →
channel[is_not][operator]
channel[is_not][operator]
optional, enumerated string filter Possible values are : web, app_store, play_store Supported operators :
Example →
channel[in][operator]
channel[in][operator]
optional, string filter Possible values are : Supported operators :
Example →
channel[not_in][operator]
channel[not_in][operator]
optional, string filter Possible values are : Supported operators :
always returned 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`.
Deletes an item price, marking its status as deleted. If it is part of a subscription or invoice, the item price status is marked archived instead. Once deleted, the id and name of the item price can be reused to create a new item price.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Notes
Sample Request
Try in API Explorer
Only for Java
copy full code
Click to Copy
curl https://{site}.chargebee.com/api/v2/item_prices/delete-sample/delete \
-X POST \
-u {site_api_key}:
Returns the set of all applicable addon-items for a specific plan-item price. This set consists of all addon-items whose item prices can be applied to a subscription having the plan-item price in it. When determining this set, Chargebee considers the item_applicability and applicable_items defined for the parent item of the plan-item price.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
optional, string, max chars=1000 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.
always returned 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`.
Returns the set of all applicable addon-item prices for a specific plan-item price. This set consists of all the addon-item prices that can be applied to a subscription having the plan-item price. When determining this set, Chargebee considers the following:
the compatibility of the addon-item prices to the plan-item price
Note
If an addon-item price has differential pricing defined against the parent item of the plan-item price, then the pricing information in the addon-item price object returned, reflects the differential pricing.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
optional, string, max chars=1000 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.
always returned 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`.
Settings
Configure SDK
