Item prices

API Version

Product Catalog

Library

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

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

item_family_id

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

item_id

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

description

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.

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

price_variant_id

optional, string, max chars=100

An immutable unique identifier of a price variant.

proration_type

optional, enumerated string

Note

Applicable only for item prices with:

item_type = addon.
pricing_model = per_unit.

Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.

Possible values are

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

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

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

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

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

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

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.

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.

Note: free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.

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

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

usage_accumulation_reset_frequency

optional, enumerated string
Specifies the frequency at which the usage counter needs to be reset.

Note: Changes to the usage_accumulation_reset_frequency parameter for item_price is not allowed if the item is already linked to a subscription.

Possible values are

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 collection of key-value pairs that provides extra information about the item price. Learn more.

item_type

optional, enumerated string
Type of item.

Possible values are

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.

deleted

boolean
Indicates whether the item price has been deleted ot not.

business_entity_id

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.

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.

tax_detail
Show attributes [+]

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

tax_providers_fields
Show attributes [+]

optional, list of tax_providers_field
List of vendor specific tax related information.

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.

id

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

name

item_family_id

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

item_id

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

description

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.

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

price_variant_id

optional, string, max chars=100

An immutable unique identifier of a price variant.

proration_type

optional, enumerated string

Note

Applicable only for item prices with:

item_type = addon.
pricing_model = per_unit.

Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.

Possible values are

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

price

price_in_decimal

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

Possible values are

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

trial_end_action

Possible values are

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

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.

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.

Note: free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.

free_quantity_in_decimal

channel

optional, enumerated string
The subscription channel this object originated from and is maintained in.

Possible values are

resource_version

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

usage_accumulation_reset_frequency

optional, enumerated string
Specifies the frequency at which the usage counter needs to be reset.

Note: Changes to the usage_accumulation_reset_frequency parameter for item_price is not allowed if the item is already linked to a subscription.

Possible values are

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

metadata

optional, jsonobject
A collection of key-value pairs that provides extra information about the item price. Learn more.

item_type

optional, enumerated string
Type of item.

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.

deleted

boolean
Indicates whether the item price has been deleted ot not.

business_entity_id

tiers

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

tax_detail

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

tax_providers_fields

optional, list of tax_providers_field
List of vendor specific tax related information.

accounting_detail

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

Try in API Explorer

This API creates an item price (a price point) for an item.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -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

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -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

copy

Click to Copy

Create an addon item price with tiered pricing model

200:

STATUS

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

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

description[]

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.

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.

proration_type[]

optional, enumerated string

Note

Applicable only for item prices with:

item_type = addon.
pricing_model = per_unit.

Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.

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. Is required when multiple currencies have been enabled.

price_variant_id[]

optional, string, max chars=100

An immutable unique identifier of a price variant.

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.

Note: free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.

free_quantity_in_decimal[]

metadata[]

optional, jsonobject
A collection of key-value pairs that provides extra information about the item price.

Note: There's a character limit of 65,535.

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.

usage_accumulation_reset_frequency[]

optional, enumerated string
Specifies the frequency at which the usage counter needs to be reset.

Note: Changes to the usage_accumulation_reset_frequency parameter for item_price is not allowed if the item is already linked to a subscription.

Possible values are

business_entity_id[]

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.

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

Important:

The period + period_unit pair must match a configured billing frequency on your site. The API does not create new frequencies. To use a new frequency (for example, 3 months or 2 weeks), add it in the site settings first. Requests with non-configured combinations fail validation.

Monthly: period=1, period_unit=month (available by default)
Quarterly: period=3, period_unit=month (enable 3-month frequency in settings)
Weekly: period=1, period_unit=week (available by default)

See how billing periods apply.

Possible values are

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.

Important:

The period value, together with period_unit, must equal one of your site's configured billing frequencies. If the combination does not exist, the request fails with an invalid billing period configuration error. Configure the frequency in site settings and retry. See Addons and billing cycle.

trial_period_unit[]

optional, enumerated string
The unit of time for trial_period.

Possible values are

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

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

tax_detail[avalara_tax_code]

optional, string, max chars=50

tax_detail[hsn_code]

optional, string, max chars=50

tax_detail[avalara_sale_type]

optional, enumerated string

Possible values are

tax_detail[avalara_transaction_type]

optional, integer

tax_detail[avalara_service_type]

optional, integer

tax_detail[taxjar_product_code]

optional, string, max chars=50

accounting_detail

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

accounting_detail[sku]

optional, string, max chars=100

accounting_detail[accounting_code]

optional, string, max chars=100

accounting_detail[accounting_category1]

optional, string, max chars=100

accounting_detail[accounting_category2]

optional, string, max chars=100

accounting_detail[accounting_category3]

optional, string, max chars=100

accounting_detail[accounting_category4]

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]

optional, integer, min=1

tiers[ending_unit][0..n]

optional, integer

tiers[price][0..n]

optional, in cents, default=0, min=0

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[price_in_decimal][0..n]

optional, string, max chars=39

tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

tiers[package_size][0..n]

optional, integer, min=1

tax_providers_fields

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

tax_providers_fields[provider_name][0..n]

required, string, max chars=50

tax_providers_fields[field_id][0..n]

required, string, max chars=50

tax_providers_fields[field_value][0..n]

required, string, max chars=50

item_price

always returned
Resource object representing item_price

Try in API Explorer

This API retrieves a specific item price using the id.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

Try in API Explorer

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

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

description[]

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.

proration_type[]

optional, enumerated string

Note

Applicable only for item prices with:

item_type = addon.
pricing_model = per_unit.

Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update.

Possible values are

price_variant_id[]

optional, string, max chars=100

An immutable unique identifier of a price variant.

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.

usage_accumulation_reset_frequency[]

optional, enumerated string
Specifies the frequency at which the usage counter needs to be reset.

Note: Changes to the usage_accumulation_reset_frequency parameter for item_price is not allowed if the item is already linked to a subscription.

Possible values are

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

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.

Note: free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements.

free_quantity_in_decimal[]

metadata[]

optional, jsonobject
A collection of key-value pairs that provides extra information about the item price.

Note: There's a character limit of 65,535.

Learn more.

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

Important:

Monthly: period=1, period_unit=month (available by default)
Quarterly: period=3, period_unit=month (enable 3-month frequency in settings)
Weekly: period=1, period_unit=week (available by default)

See how billing periods apply.

Possible values are

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.

Important:

trial_period_unit[]

optional, enumerated string
The unit of time for trial_period.

Possible values are

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

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

tax_detail[avalara_tax_code]

optional, string, max chars=50

tax_detail[hsn_code]

optional, string, max chars=50

tax_detail[avalara_sale_type]

optional, enumerated string

Possible values are

tax_detail[avalara_transaction_type]

optional, integer

tax_detail[avalara_service_type]

optional, integer

tax_detail[taxjar_product_code]

optional, string, max chars=50

accounting_detail

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

accounting_detail[sku]

optional, string, max chars=100

accounting_detail[accounting_code]

optional, string, max chars=100

accounting_detail[accounting_category1]

optional, string, max chars=100

accounting_detail[accounting_category2]

optional, string, max chars=100

accounting_detail[accounting_category3]

optional, string, max chars=100

accounting_detail[accounting_category4]

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]

optional, integer, min=1

tiers[ending_unit][0..n]

optional, integer

tiers[price][0..n]

optional, in cents, default=0, min=0

tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

tiers[price_in_decimal][0..n]

optional, string, max chars=39

tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

tiers[package_size][0..n]

optional, integer, min=1

tax_providers_fields

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

tax_providers_fields[provider_name][0..n]

required, string, max chars=50

tax_providers_fields[field_id][0..n]

required, string, max chars=50

tax_providers_fields[field_value][0..n]

required, string, max chars=50

item_price

always returned
Resource object representing item_price

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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] = "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] = "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"

price_variant_id[<operator>]

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

Example → price_variant_id[is] = "tamilNadu-India"

trial_period[<operator>]

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

Example → trial_period[is] = "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[after] = "1243545465"

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.
Supported operators : is, is_present

Example → business_entity_id[is] = "business_entity_id"

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"

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, number filter
Filter item prices based on their period.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → period[is] = "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] = "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`.

Try in API Explorer

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

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}:

copy

Click to Copy

200:

STATUS

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

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to 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

copy

Click to Copy

200:

STATUS

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

item_id[]

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

sort_by[<sort-order>]

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

Model Class

Item price attributes

Consent Fields for Item price

Custom Fields for Item price

Create an item price ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve an item price ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update an item price ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List item prices ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete an item price ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List applicable items for a plan-item price ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List applicable item prices for a plan-item price ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL