Item prices

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

string, max chars=100
The identifier for the item price. It is unique and immutable.

name

string, max chars=50
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.

item_family_id

optional, string, max chars=100
Id of the item_family

product_id

optional, string, max chars=100
Identifier of the product

item_id

optional, string, max chars=100
The id of the item that the item price belongs to.

description

optional, string, max chars=500
Description of the item price.

status

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.

external_name

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

pricing_model

enumerated string, default=flat_fee

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

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.

price_in_decimal

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.

period

optional, integer, min=1

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

currency_code

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.

period_unit

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.

trial_period

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.

trial_period_unit

optional, enumerated string
The unit of time for trial_period.

Possible values are

dayA period of 24 hours.monthA period of 1 calendar month.

trial_end_action

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.

shipping_period

optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

shipping_period_unit

optional, enumerated string
Defines the shipping frequency in association with shipping period.

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

optional, integer, min=1

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.

free_quantity

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.

free_quantity_in_decimal

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.

channel

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.

resource_version

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.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this item price was last updated

created_at

timestamp(UTC) in seconds
Timestamp indicating when this item price was created

archived_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this item price was archived.

invoice_notes

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.

is_taxable

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.

metadata

optional, jsonobject
A set of key-value pairs stored as additional information for the item price. Learn more.

item_type

optional, enumerated string
Type of item.

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

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.

show_description_in_quotes

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.

tiers
Show attributes[+]

optional, list of tier
List of quantity-based pricing tiers for the item price. Applicable only for tiered, volume, and stairstep pricing_models.

Tier attributes

starting_unit

integer, min=1
The lower limit of a range of units for the tier

ending_unit

optional, integer
The upper limit of a range of units for the tier

price

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.

tax_detail
Show attributes[+]

optional, tax_detail
The tax details for the item price. Includes those details relevant for third-party integrations.

Tax detail attributes

tax_profile_id

optional, string, max chars=50
The tax profile of the item price.

avalara_sale_type

optional, enumerated string
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax

avalara_transaction_type

optional, integer
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.

avalara_service_type

optional, integer
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.

avalara_tax_code

optional, string, max chars=50
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.

hsn_code

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.)
The AvaTax for Sales integration has been enabled in Chargebee.

taxjar_product_code

optional, string, max chars=50
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.

accounting_detail
Show attributes[+]

optional, accounting_detail
Accounting integration details. The values are typically dependent on the accounting integration used.

Accounting detail attributes

sku

optional, string, max chars=100
This maps to the sku or product name in the accounting integration.

accounting_code

optional, string, max chars=100
The identifier of the chart of accounts under which the item price falls in the accounting system.

accounting_category1

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format: <category-name>: <option>. For example:Location: Singapore.
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... For example: Services: Plan.
Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.

accounting_category2

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format: <category-name>: <option>.... For example, Region: South
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: <parent-location>:<sub-location-1>:<sub-location-2>.... For example: Location: North America: Canada
NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format <parent-location> : <sub-location-1>: <sub-location-2>.... For example: NA:US:CA
Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.

accounting_category3

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format: <parent-department> : <sub-department-1>: <sub-department-2>.... For example: Production: Assembly.
Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.

accounting_category4

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: Provide the “Revenue Recognition Rule Id” for the product from NetSuite.
Intacct: If you have configured “Revenue Recognition Templates” for products in Intacct, provide the template ID for the product.

This API 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

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

# create an addon item price with tiered pricing model
curl  https://{site}.chargebee.com/api/v2/item_prices \
     -X POST  \
     -u {site_api_key}:\
     -d id="day-pass-USD-monthly" \
     -d name="Day Pass USD Monthly" \
     -d item_id="day-pass" \
     -d period=1 \
     -d period_unit="month" \
     -d pricing_model="tiered" \
     -d tiers[starting_unit][0]=1 \
     -d tiers[ending_unit][0]=10 \
     -d tiers[price][0]=100 \
     -d tiers[starting_unit][1]=11 \
     -d tiers[ending_unit][1]=20 \
     -d tiers[price][1]=300 \
     -d tiers[starting_unit][2]=21 \
     -d tiers[price][2]=500

Sample Response [ JSON ]

{"item_price": {
    "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
}}

{"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 POST

https://{site}.chargebee.com/api/v2/item_prices

id

required, string, max chars=100
The identifier for the item price. It is unique and immutable.

name

required, string, max chars=50
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.

description

optional, string, max chars=500
Description of the item price.

item_id

required, string, max chars=100
The id of the item that the item price belongs to.

invoice_notes

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.

external_name

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.

currency_code

optional, string, max chars=3
The currency code (ISO 4217 format) for the item price. Is required when multiple currencies have been enabled.

is_taxable

free_quantity

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.

free_quantity_in_decimal

metadata

optional, jsonobject
A set of key-value pairs stored as additional information for the item price. Learn more.

show_description_in_invoices

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.

show_description_in_quotes

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.

pricing_model

optional, enumerated string, default=flat_fee

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

price

price_in_decimal

period_unit

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

optional, integer, min=1

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.

trial_period_unit

optional, enumerated string
The unit of time for trial_period.

Possible values are

dayA period of 24 hours.monthA period of 1 calendar month.

trial_period

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.

shipping_period

optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

shipping_period_unit

optional, enumerated string
Defines the shipping frequency in association with shipping period.

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

optional, integer, min=1

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

If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.

trial_end_action

Possible values are

tax_detail

Parameters for tax_detail
pass parameters as tax_detail[<param name>]

tax_detail[tax_profile_id]

optional, string, max chars=50
The tax profile of the item price.

tax_detail[avalara_tax_code]

optional, string, max chars=50
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.

tax_detail[hsn_code]

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.)
The AvaTax for Sales integration has been enabled in Chargebee.

tax_detail[avalara_sale_type]

optional, enumerated string
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.

Possible values are

tax_detail[avalara_transaction_type]

optional, integer
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.

tax_detail[avalara_service_type]

optional, integer
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.

tax_detail[taxjar_product_code]

optional, string, max chars=50
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.

accounting_detail

Parameters for accounting_detail
pass parameters as accounting_detail[<param name>]

accounting_detail[sku]

optional, string, max chars=100
This maps to the sku or product name in the accounting integration.

accounting_detail[accounting_code]

optional, string, max chars=100
The identifier of the chart of accounts under which the item price falls in the accounting system.

accounting_detail[accounting_category1]

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format: <category-name>: <option>. For example:Location: Singapore.
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... For example: Services: Plan.
Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.

accounting_detail[accounting_category2]

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format: <category-name>: <option>.... For example, Region: South
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: <parent-location>:<sub-location-1>:<sub-location-2>.... For example: Location: North America: Canada
NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format <parent-location> : <sub-location-1>: <sub-location-2>.... For example: NA:US:CA
Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.

accounting_detail[accounting_category3]

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format: <parent-department> : <sub-department-1>: <sub-department-2>.... For example: Production: Assembly.
Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.

accounting_detail[accounting_category4]

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: Provide the “Revenue Recognition Rule Id” for the product from NetSuite.
Intacct: If you have configured “Revenue Recognition Templates” for products in Intacct, provide the template ID for the product.

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]

optional, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

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

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as 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.

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.

tiers[price_in_decimal][0..n]

optional, string, max chars=39
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.

item_price

always returned
Resource object representing item_price

This API retrieves a specific item price using the id.

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 ]

{"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}

item_price

always returned
Resource object representing item_price

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 ]

{"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

optional, string, max chars=50
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.

description

optional, string, max chars=500
Description of the item price.

status

optional, enumerated string
The status of the item price.

Possible values are

external_name

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.

currency_code

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.

invoice_notes

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.

is_taxable

optional, boolean
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.

free_quantity

optional, integer, min=0
Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.

free_quantity_in_decimal

metadata

optional, jsonobject
A set of key-value pairs stored as additional information for the item price. Learn more.

pricing_model

optional, enumerated string

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

price

price_in_decimal

period_unit

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

optional, integer, min=1

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.

trial_period_unit

optional, enumerated string
The unit of time for trial_period.

Possible values are

dayA period of 24 hours.monthA period of 1 calendar month.

trial_period

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.

shipping_period

optional, integer, min=1
Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

shipping_period_unit

optional, enumerated string
Defines the shipping frequency in association with shipping period.

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

optional, integer, min=1

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

If subscriptions, invoices or differential prices exist for this item price, billing_cycles cannot be changed.

trial_end_action

Possible values are

show_description_in_invoices

show_description_in_quotes

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.

tax_detail

Parameters for tax_detail
pass parameters as tax_detail[<param name>]

tax_detail[tax_profile_id]

optional, string, max chars=50
The tax profile of the item price.

tax_detail[avalara_tax_code]

optional, string, max chars=50
The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.

tax_detail[hsn_code]

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.)
The AvaTax for Sales integration has been enabled in Chargebee.

tax_detail[avalara_sale_type]

optional, enumerated string
Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration.

Possible values are

tax_detail[avalara_transaction_type]

optional, integer
Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.

tax_detail[avalara_service_type]

optional, integer
Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.

tax_detail[taxjar_product_code]

optional, string, max chars=50
The TaxJar product code for the item price. Applicable only if you use TaxJar integration.

accounting_detail

Parameters for accounting_detail
pass parameters as accounting_detail[<param name>]

accounting_detail[sku]

optional, string, max chars=100
This maps to the sku or product name in the accounting integration.

accounting_detail[accounting_code]

optional, string, max chars=100
The identifier of the chart of accounts under which the item price falls in the accounting system.

accounting_detail[accounting_category1]

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, provide the category name and option. Use the format: <category-name>: <option>. For example:Location: Singapore.
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: <parent class>:<sub-class-1>:<sub-class-2>...
NetSuite: If you’ve categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... For example: Services: Plan.
Intacct: If you’ve classified your products in Intacct under Locations, provide the name of the Location here.

accounting_detail[accounting_category2]

optional, string, max chars=100
Used exclusively with the following accounting integrations

Xero: If you’ve categorized your products in Xero, then provide the second category name and option here. Use the format: <category-name>: <option>.... For example, Region: South
QuickBooks: If you’ve categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: <parent-location>:<sub-location-1>:<sub-location-2>.... For example: Location: North America: Canada
NetSuite: If you’ve categorized your products in NetSuite under Locations, provide the location name here. Use the following format <parent-location> : <sub-location-1>: <sub-location-2>.... For example: NA:US:CA
Intacct: If you’ve classified your products in Intacct under Dimensions, provide the value of the Dimension here.

accounting_detail[accounting_category3]

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: If you’ve categorized your products in NetSuite under Departments, pass the department name here. Use the following format: <parent-department> : <sub-department-1>: <sub-department-2>.... For example: Production: Assembly.
Intacct: If you’ve classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.

accounting_detail[accounting_category4]

optional, string, max chars=100
Used exclusively with the following accounting integrations

NetSuite: Provide the “Revenue Recognition Rule Id” for the product from NetSuite.
Intacct: If you have configured “Revenue Recognition Templates” for products in Intacct, provide the template ID for the product.

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]

optional, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

optional, in cents, 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.

tiers[starting_unit_in_decimal][0..n]

tiers[ending_unit_in_decimal][0..n]

tiers[price_in_decimal][0..n]

item_price

always returned
Resource object representing item_price

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 ]

{"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

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset

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.

sort_by[<sort-order>]

optional, string filter
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.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter
Filter item prices based on their id.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "basic_USD"

name[<operator>]

optional, string filter
Filter item prices based on their names.
Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "basic USD"

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"

item_id[<operator>]

optional, string filter
Filter item prices based on their item_id.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_id[is_not] = "basic"

item_family_id[<operator>]

optional, string filter
Filter item prices based on item_family_id.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_family_id[is_not] = "Acme"

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"

currency_code[<operator>]

optional, string filter
Filter item prices based on their currency_code.
Supported operators : is, is_not, starts_with, in, not_in

Example → currency_code[is] = "USD"

trial_period[<operator>]

optional, integer filter
Filter item prices based on their trial_period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → trial_period[lt] = "14"

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"

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"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
Filter item prices based on their updated_at.
Supported operators : after, before, on, between

Example → updated_at[on] = "1243545465"

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[<operator>]

optional, integer filter
Filter item prices based on their period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → period[lt] = "3"

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_not] = "APP STORE"

item_price

always returned
Resource object representing item_price

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

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 ]

{"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

item_price

always returned
Resource object representing item_price

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.

Sample Request

curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_items \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_items \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

{"list": [
    {"item": {
        "applicable_items": [
            {"id": "basic"},
            {..}
        ],
        "enabled_for_checkout": true,
        "enabled_in_portal": true,
        "id": "extra-sms-addon",
        "is_giftable": false,
        "is_shippable": false,
        "item_applicability": "restricted",
        "name": "Extra SMS addon",
        "object": "item",
        "resource_version": 1599817250235,
        "status": "active",
        "type": "addon",
        "updated_at": 1599817250
    }},
    {..}
]}

URL Format GET

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}/applicable_items

limit

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset

sort_by[<sort-order>]

item

always returned
Resource object representing item

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

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 item_applicability and applicable_items defined for the parent item of the plan-item price
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.

Sample Request

curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_item_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

copy

curl  https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_item_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

{"list": [
    {"item_price": {
        "id": "extra-sms-USD-daily",
        "name": "Extra SMS USD Daily",
        "item_family_id": "Product-Family",
        "item_id": "extra-sms-addon",
        "status": "active",
        "external_name": "Extra SMS USD Daily",
        "pricing_model": "flat_fee",
        "price": 2000,
        "period": 1,
        "currency_code": "USD",
        "period_unit": "day",
        "free_quantity": 0,
        "channel": "web",
        "resource_version": 1634889942715,
        "updated_at": 1634889942,
        "created_at": 1634889942,
        "is_taxable": true,
        "item_type": "addon",
        "show_description_in_invoices": false,
        "show_description_in_quotes": false,
        "object": "item_price"
    }},
    {..}
]}

URL Format GET

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}/applicable_item_prices

limit

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset

sort_by[<sort-order>]

Filter Params

For operator usages, see the Pagination and Filtering section.

item_id

optional, string, max chars=100
The id of the item that the item price belongs to.

item_price

always returned
Resource object representing item_price

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

Types of item prices

Sample item price [ JSON ]

API Index URL GET

Item price attributes

Create an item price¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Retrieve an item price¶

Sample Response [ JSON ]

URL Format GET

Returns

Update an item price¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List item prices¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Delete an item price¶

Sample Response [ JSON ]

URL Format POST

Returns

List applicable items for a plan-item price¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

List applicable item prices for a plan-item price¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns