ChargebeeAPI

Create an item price

Idempotency Supported
Try in API Explorer

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

Sample Request

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.

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:
    - testing - desc .
    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:

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

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

price_variant_id
optional, string, max chars=100

An immutable unique identifier of a price variant.

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

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

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

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

trial_period_unit
optional, enumerated string

The unit of time for trial_period .

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

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

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

Parameters for tax_detail

accounting_detail
optional, string

Parameters for accounting_detail

tiers
optional, integer

Parameters for tiers

tax_providers_fields
optional, string

Parameters for tax_providers_fields

Returns

item_priceItem price object

Resource object representing item_price