Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Create an item price

Idempotency Supported

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

Prerequisites & Constraints

  • Either price or price_in_decimal is required when pricing_model is flat_fee or per_unit.
  • tiers is applicable only when pricing_model is tiered, volume, or stairstep.

Sample Request

create an addon item price with tiered pricing model

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/item_prices

Input Parameters

id
required, string, max chars=100

The identifier for the item price. It is unique and immutable.

Constraints
  • id must not contain spaces or the / character.
  • id must be unique across all item prices.
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 .

Constraint
  • name must be unique across all item prices.
description
optional, string, max chars=2000

Description of the item price.

Constraint
  • description must not exceed 500 characters excluding HTML tags. The total length, including HTML tags, must not exceed 2000 characters.

    Note: inputs that require sanitization, such as incomplete HTML tags, may be altered and grow in length, and the request is rejected if the sanitized content exceeds these limits.
item_id
required, string, max chars=100

The id of the item that the item price belongs to.

Constraint
  • item_id must reference an existing item in the catalog.
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

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

Prerequisite
  • Item-level Proration must be enabled for your site to provide proration_type.
Constraints
  • proration_type is applicable only when pricing_model is per_unit.
  • proration_type is applicable only when the associated item_type is addon.
Enum Values
site_default

Use the site-wide proration setting .

partial_term

Prorate the charges or credits for the rest of the current term.

full_term

Charge the full price of the addon item price or give the full credit. Don't apply any proration.

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.

Constraints
  • currency_code must be one of the currencies configured for your site.
  • currency_code is required when multiple currencies are enabled for your site.
price_variant_id
optional, string, max chars=100

An immutable unique identifier of a price variant.

Constraint
  • Variant Pricing (or migration mode) must be enabled for your site to provide price_variant_id.
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.

free_quantity
optional, integer, default=0, min=0

Free quantity the subscriptions of this plan item_price will have. Only the quantity exceeding this value will be charged in the subscription.

Note:

  • free_quantity is currently supported only for plan item_price.
  • free_quantity is not supported for the Usage-Based Billing (UBB). All included or free quantities should be configured exclusively through entitlements .
Constraints
  • free_quantity is applicable only when the associated item_type is plan.
  • free_quantity is not applicable when pricing_model is flat_fee.
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.

Constraints
  • free_quantity_in_decimal is not applicable when pricing_model is flat_fee.
  • Multi-decimal Pricing must be enabled for your site to provide 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.

.

Constraints
  • usage_accumulation_reset_frequency is applicable only when the associated item is metered.
  • usage_accumulation_reset_frequency is applicable only when pricing_model is tiered.
Enum Values
never

Accumulates usage without ever resetting it.

subscription_billing_frequency

Accumulates usage until the subscription's billing frequency ends.

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.

Constraint
  • Multiple Business Entities must be enabled for your site to provide business_entity_id.
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.

Enum Values
flat_fee

A fixed price that is not quantity-based.

per_unit

A fixed price per unit quantity.

tiered

There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.

volume

The per unit price is based on the tier that the total quantity falls in.

stairstep

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

Constraints
  • price is applicable only when pricing_model is flat_fee or per_unit.
  • price must not exceed the maximum allowed value configured for your site.
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.

Constraints
  • price_in_decimal is applicable only when pricing_model is flat_fee or per_unit.
  • Multi-decimal Pricing must be enabled for your site to provide price_in_decimal.
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 .

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 .
Required if
  • period_unit is required when the associated item's type is plan or addon.
Constraint
  • period_unit must not be provided when the associated item's type is charge.
Enum Values
day

A period of 24 hours.

week

A period of 7 days.

month

A period of 1 calendar month.

year

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

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.

Required if
  • period is required when the associated item's type is plan or addon.
Constraint
  • period must not be provided when the associated item's type is charge.
trial_period_unit
optional, enumerated string

The unit of time for trial_period .

Constraints
  • trial_period is required when trial_period_unit is provided.
  • trial_period_unit must not be provided when the associated item's type is charge.
Enum Values
day

A period of 24 hours.

month

A period of 1 calendar month.

trial_period
optional, integer, min=0

The trial period of the plan in trial_period_unit s. You can also set trial periods for addons ; contact Support to enable that feature.

Constraints
  • trial_period_unit is required when trial_period is provided.
  • trial_period must not be provided when the associated item's type is charge.
shipping_period
optional, integer, min=1

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

Constraints
  • shipping_period_unit is required when shipping_period is provided.
  • shipping_period must not be provided when the associated item's type is charge.
shipping_period_unit
optional, enumerated string

Defines the shipping frequency in association with shipping period.

Constraints
  • shipping_period is required when shipping_period_unit is provided.
  • shipping_period_unit must not be provided when the associated item's type is charge.
Enum Values
day

A period of 24 hours.

week

A period of 7 days.

month

A period of 1 calendar month.

year

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

Constraint
  • billing_cycles must not be provided when the associated item's type is charge.
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 .

Constraints
  • trial_end_action must not be provided when the associated item's type is charge.
  • trial_end_action is applicable only when the associated item_type is plan.
Enum Values
site_default

The action configured for the site at the time when the trial ends, takes effect.

activate_subscription

The subscription activates and charges are raised for non-metered items.

cancel_subscription

The subscription cancels.

tax_detail
Parameters for tax_detail
pass parameters as tax_detail[<param name>]
accounting_detail
Parameters for accounting_detail
pass parameters as accounting_detail[<param name>]
tiers[0..n]
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tax_providers_fields[0..n]
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices.
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]

Returns

item_price
Item price object
Resource object representing item_price