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:

  • Plan-item prices
  • Addon-item prices
  • Charge-item prices

Sample item price [ JSON ]

{ "created_at": 1594106928, "currency_code": "USD", "external_name": "silver USD", "free_quantity": 0, "id": "silver-USD-monthly", "is_taxable": true, "item_id": "silver", "item_type": "plan", "name": "silver USD monthly", "object": "item_price", "period": 1, "period_unit": "month", "price": 1000, "pricing_model": "per_unit", "resource_version": 1594106928574, "status": "active", "updated_at": 1594106928 }

API Index URL GET

https://{site}.chargebee.com/api/v2/item_prices
id
The identifier for the item price. It is unique and immutable.
string, max chars=100
name
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.
string, max chars=50
item_family_id
Id of the item_family.
optional, string, max chars=100
item_id
The id of the item that the item price belongs to.
optional, string, max chars=100
description
Description of the item price.
optional, string, max chars=500
status
The status of the item price.Possible values are:.
optional, enumerated string
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.
external_name
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=100
pricing_model

The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
enumerated string, default=flat_fee

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.
price
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, in cents, min=0
price_in_decimal
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, string, max chars=33
period

  • 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.
optional, integer, min=1
currency_code
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.
string, max chars=3
period_unit
The unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed.
optional, enumerated string
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.
trial_period
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, integer, min=0
trial_period_unit
The unit of time for trial_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.monthA period of 1 calendar month.
shipping_period
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1
shipping_period_unit
Defines the shipping frequency in association with shipping period.
optional, enumerated string
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.
billing_cycles

The default number of billing cycles a subscription to the plan must run. Can be overridden for a subscription.

Addons can also have billing cycles. However, you must contact Support to enable that. Also, for addons, you can override this while attaching it to a plan. However, if you provide the value while applying the addon to a subscription, then that value takes still higher precedence.

If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
optional, integer, min=1
free_quantity
Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
integer, default=0, min=0
free_quantity_in_decimal
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, string, max chars=33
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at

optional, timestamp(UTC) in seconds
created_at

timestamp(UTC) in seconds
archived_at
Timestamp indicating when this item price was archived.
optional, timestamp(UTC) in seconds
invoice_notes
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, string, max chars=2000
is_taxable
Specifies if the item price should be taxed.
optional, boolean, default=true
metadata
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject
item_type

optional, enumerated string
Possible values are
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.
show_description_in_invoices
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
show_description_in_quotes
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, boolean
List of quantity-based pricing tiers for the item price. Applicable only for tiered, volume, and stairstep pricing_models.
optional, list of tier
Tier attributes
starting_unit
The lower limit of a range of units for the tier.
integer, min=1
ending_unit
The upper limit of a range of units for the tier.
optional, integer
price
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
in cents, default=0, min=0
tax_detail
Show attributes[+]
The tax details for the item price. Includes those details relevant for third-party integrations.
optional, tax_detail
Tax detail attributes
tax_profile_id
The tax profile of the item price.
optional, string, max chars=50
avalara_sale_type
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, enumerated string
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.
avalara_transaction_type
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
avalara_service_type
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
avalara_tax_code
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.
optional, string, max chars=50
taxjar_product_code
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.
optional, string, max chars=50
accounting_detail
Show attributes[+]
Accounting integration details. The values are typically dependent on the accounting integration used. .
optional, accounting_detail
Accounting detail attributes
sku
This maps to the sku or product name in the accounting integration.
optional, string, max chars=100
accounting_code
The identifier of the chart of accounts under which the item price falls in the accounting system.
optional, string, max chars=100
accounting_category1
The field in the accounting system that this attribute maps to is dependent on the accounting integration being used. See the Chargebee UI for details on what this category maps to, or contact Chargebee Support.
optional, string, max chars=100
accounting_category2
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_category3
Netsuite/Intact configuration.
optional, string, max chars=100
accounting_category4
Netsuite/Intact configuration.
optional, string, max chars=100

Creates an item price (a price point) for an item.

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_prices \
     -X POST  \
     -u {site_api_key}:\
     -d id="silver-USD-monthly" \
     -d item_id="silver" \
     -d name="silver USD monthly" \
     -d pricing_model="per_unit" \
     -d price=1000 \
     -d external_name="silver USD" \
     -d period_unit="month" \
     -d period=1
copy

Sample Response [ JSON ]

URL Format POST

https://{site}.chargebee.com/api/v2/item_prices
id
The identifier for the item price. It is unique and immutable.
required, string, max chars=100
name
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.
required, string, max chars=50
description
Description of the item price.
optional, string, max chars=500
item_id
The id of the item that the item price belongs to.
required, string, max chars=100
invoice_notes
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, string, max chars=2000
external_name
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=100
currency_code
The currency code (ISO 4217 format) for the item price. Is required when multiple currencies have been enabled.
optional, string, max chars=3
is_taxable
Specifies if the item price should be taxed.
optional, boolean, default=true
free_quantity
Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
optional, integer, default=0, min=0
free_quantity_in_decimal
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, string, max chars=33
metadata
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject
show_description_in_invoices
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
show_description_in_quotes
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, boolean, default=false
pricing_model

The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
optional, enumerated string, default=flat_fee

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.
price
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, in cents, min=0
price_in_decimal
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, string, max chars=33
period_unit
The unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed.
optional, enumerated string
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.
period

  • 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.
optional, integer, min=1
trial_period_unit
The unit of time for trial_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.monthA period of 1 calendar month.
trial_period
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, integer, min=0
shipping_period
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1
shipping_period_unit
Defines the shipping frequency in association with shipping period.
optional, enumerated string
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.
billing_cycles

The default number of billing cycles a subscription to the plan must run. Can be overridden for a subscription.

Addons can also have billing cycles. However, you must contact Support to enable that. Also, for addons, you can override this while attaching it to a plan. However, if you provide the value while applying the addon to a subscription, then that value takes still higher precedence.

If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
optional, integer, min=1
+
tax_detail
Parameters for tax_detail
pass parameters as tax_detail[<param name>]
tax_detail[tax_profile_id]
The tax profile of the item price.
optional, string, max chars=50
tax_detail[avalara_tax_code]
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.
optional, string, max chars=50
tax_detail[avalara_sale_type]
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, enumerated string
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.
tax_detail[avalara_transaction_type]
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
tax_detail[avalara_service_type]
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
tax_detail[taxjar_product_code]
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.
optional, string, max chars=50
+
accounting_detail
Parameters for accounting_detail
pass parameters as accounting_detail[<param name>]
accounting_detail[sku]
This maps to the sku or product name in the accounting integration.
optional, string, max chars=100
accounting_detail[accounting_code]
The identifier of the chart of accounts under which the item price falls in the accounting system.
optional, string, max chars=100
accounting_detail[accounting_category1]
The field in the accounting system that this attribute maps to is dependent on the accounting integration being used. See the Chargebee UI for details on what this category maps to, or contact Chargebee Support.
optional, string, max chars=100
accounting_detail[accounting_category2]
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_detail[accounting_category3]
Netsuite/Intact configuration.
optional, string, max chars=100
accounting_detail[accounting_category4]
Netsuite/Intact configuration.
optional, string, max chars=100
+
tiers
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tiers[starting_unit][0..n]
The lower limit of a range of units for the tier.
optional, integer, min=1
tiers[ending_unit][0..n]
The upper limit of a range of units for the tier.
optional, integer
tiers[price][0..n]
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
optional, in cents, default=0, min=0
tiers[starting_unit_in_decimal][0..n]
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33
tiers[ending_unit_in_decimal][0..n]
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33
tiers[price_in_decimal][0..n]
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the addon. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33
Resource object representing item_price.
always returned

Retrieve a specific item price.

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-monthly \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-monthly \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"item_price": { "created_at": 1594106945, "currency_code": "USD", "external_name": "basic USD", "free_quantity": 0, "id": "basic-USD-monthly", "is_taxable": true, "item_id": "basic", "item_type": "plan", "name": "basic USD monthly", "object": "item_price", "period": 1, "period_unit": "month", "price": 1000, "pricing_model": "per_unit", "resource_version": 1594106945077, "status": "active", "updated_at": 1594106945 }}

URL Format GET

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}
Resource object representing item_price.
always returned

Updates an item price with the changes specified. Unspecified item price attributes are not modified.

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_prices/scale-USD \
     -X POST  \
     -u {site_api_key}:\
     -d name="scale USD Yearly" \
     -d price=10000 \
     -d period=1 \
     -d period_unit="year"
copy
curl  https://{site}.chargebee.com/api/v2/item_prices/scale-USD \
     -X POST  \
     -u {site_api_key}:\
     -d name="scale USD Yearly" \
     -d price=10000 \
     -d period=1 \
     -d period_unit="year"

Sample Response [ JSON ]

Show more...
{"item_price": { "created_at": 1594106949, "currency_code": "USD", "external_name": "scale USD", "free_quantity": 0, "id": "scale-USD", "is_taxable": true, "item_id": "scale", "item_type": "plan", "name": "scale USD Yearly", "object": "item_price", "period": 1, "period_unit": "year", "price": 10000, "pricing_model": "flat_fee", "resource_version": 1594106954802, "status": "active", "updated_at": 1594106954 }}

URL Format POST

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}
name
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=50
description
Description of the item price.
optional, string, max chars=500
status
The status of the item price.Possible values are:.
optional, enumerated string
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.
external_name
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=100
currency_code
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=3
invoice_notes
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, string, max chars=2000
is_taxable
Specifies if the item price should be taxed.
optional, boolean
free_quantity
Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
optional, integer, min=0
free_quantity_in_decimal
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, string, max chars=33
metadata
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject
pricing_model

The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model cannot be changed.
optional, enumerated string

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.
price
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, in cents, min=0
price_in_decimal
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, string, max chars=33
period_unit
The unit of time for period. If subscriptions or invoices exist for this item price, period_unit cannot be changed.
optional, enumerated string
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.
period

  • 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.
optional, integer, min=1
trial_period_unit
The unit of time for trial_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.monthA period of 1 calendar month.
trial_period
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, integer, min=0
shipping_period
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
optional, integer, min=1
shipping_period_unit
Defines the shipping frequency in association with shipping period.
optional, enumerated string
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.
billing_cycles

The default number of billing cycles a subscription to the plan must run. Can be overridden for a subscription.

Addons can also have billing cycles. However, you must contact Support to enable that. Also, for addons, you can override this while attaching it to a plan. However, if you provide the value while applying the addon to a subscription, then that value takes still higher precedence.

If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.
optional, integer, min=1
show_description_in_invoices
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
show_description_in_quotes
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, boolean
+
tax_detail
Parameters for tax_detail
pass parameters as tax_detail[<param name>]
tax_detail[tax_profile_id]
The tax profile of the item price.
optional, string, max chars=50
tax_detail[avalara_tax_code]
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.
optional, string, max chars=50
tax_detail[avalara_sale_type]
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, enumerated string
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.
tax_detail[avalara_transaction_type]
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
tax_detail[avalara_service_type]
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.
optional, integer
tax_detail[taxjar_product_code]
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.
optional, string, max chars=50
+
accounting_detail
Parameters for accounting_detail
pass parameters as accounting_detail[<param name>]
accounting_detail[sku]
This maps to the sku or product name in the accounting integration.
optional, string, max chars=100
accounting_detail[accounting_code]
The identifier of the chart of accounts under which the item price falls in the accounting system.
optional, string, max chars=100
accounting_detail[accounting_category1]
The field in the accounting system that this attribute maps to is dependent on the accounting integration being used. See the Chargebee UI for details on what this category maps to, or contact Chargebee Support.
optional, string, max chars=100
accounting_detail[accounting_category2]
The name of the category of your product in Xero. Use the format<Category>:<Name>". E.g. "Region: North".
optional, string, max chars=100
accounting_detail[accounting_category3]
Netsuite/Intact configuration.
optional, string, max chars=100
accounting_detail[accounting_category4]
Netsuite/Intact configuration.
optional, string, max chars=100
+
tiers
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tiers[starting_unit][0..n]
The lower limit of a range of units for the tier.
optional, integer, min=1
tiers[ending_unit][0..n]
The upper limit of a range of units for the tier.
optional, integer
tiers[price][0..n]
The per-unit price for the tier when the pricing_model is tiered or volume; the total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
optional, in cents, min=0
tiers[starting_unit_in_decimal][0..n]
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33
tiers[ending_unit_in_decimal][0..n]
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33
tiers[price_in_decimal][0..n]
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the addon. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33
Resource object representing item_price.
always returned

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.

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v2/item_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{"list": [ {"item_price": { "created_at": 1594106932, "currency_code": "USD", "external_name": "Day Pass USD Monthly", "free_quantity": 0, "id": "day-pass-USD-monthly", "is_taxable": true, "item_id": "day-pass", "item_type": "addon", "name": "Day Pass USD Monthly", "object": "item_price", "period": 1, "period_unit": "month", "pricing_model": "tiered", "resource_version": 1594106932518, "status": "active", "tiers": [ { "ending_unit": 10, "price": 100, "starting_unit": 1 }, {..} ], "updated_at": 1594106932 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/item_prices
limit
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
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, max chars=1000
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : name, id, updated_at
Supported sort-orders : asc, desc

Example sort_by[asc] = "name"
This will sort the result based on the 'name' attribute in ascending(earliest first) order.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
Filter item prices based on their id.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "basic_USD"
optional, string filter
name[<operator>]
Filter item prices based on their names.
Supported operators : is, is_not, starts_with, in, not_in

Example name[is] = "basic USD"
optional, string filter
pricing_model[<operator>]
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"
optional, enumerated string filter
item_id[<operator>]
Filter item prices based on their item_id.
Supported operators : is, is_not, starts_with, in, not_in

Example item_id[is_not] = "basic"
optional, string filter
item_family_id[<operator>]
Filter item prices based on item_family_id.
Supported operators : is, is_not, starts_with, in, not_in

Example item_family_id[is] = "Acme"
optional, string filter
item_type[<operator>]
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_not] = "plan"
optional, enumerated string filter
currency_code[<operator>]
Filter item prices based on their currency_code.
Supported operators : is, is_not, starts_with, in, not_in

Example currency_code[is] = "USD"
optional, string filter
trial_period[<operator>]
Filter item prices based on their trial_period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example trial_period[gte] = "14"
optional, integer filter
trial_period_unit[<operator>]
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"
optional, enumerated string filter
status[<operator>]
Filter item prices based on their status. Possible values are : active, archived, deleted.
Supported operators : is, is_not, in, not_in

Example status[is_not] = "active"
optional, enumerated string filter
updated_at[<operator>]
Filter item prices based on their updated_at.
Supported operators : after, before, on, between

Example updated_at[after] = "1243545465"
optional, timestamp(UTC) in seconds filter
period_unit[<operator>]
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"
optional, enumerated string filter
period[<operator>]
Filter item prices based on their period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example period[is] = "3"
optional, integer filter
Resource object representing item_price.
always returned
next_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”.
optional, string, max chars=1000

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.

Sample Request
curl  https://{site}.chargebee.com/api/v2/item_prices/delete-sample/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/item_prices/delete-sample/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"item_price": { "created_at": 1594106936, "currency_code": "USD", "external_name": "delete sample USD", "free_quantity": 0, "id": "delete-sample", "is_taxable": true, "item_id": "scale-test", "item_type": "plan", "name": "delete sample", "object": "item_price", "period": 1, "period_unit": "month", "price": 1000, "pricing_model": "per_unit", "resource_version": 1594106939944, "status": "deleted", "updated_at": 1594106939 }}

URL Format POST

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}/delete
Resource object representing item_price.
always returned