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:
period
of the item price in period_unit
s. An item can have only one item price for a given currency and billing period.
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:
{
"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
}
external_name
is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages. name
is used Applicable only for item prices with:
item_type
= addon
.pricing_model
= per_unit
.The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model
cannot be changed.
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. 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. type
is plan
: The billing period of the plan in period_unit
s. For example, create a 6 month plan by providing period
as 6 and period_unit
as month.type
is addon
: The period of the addon in period_unit
s. 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.period
cannot be changed. The period
is mandatory when the item type
is plan
or addon
currency_code
cannot be changed. trial_period_unit
s. You can also set trial periods for addons; contact Support to enable that feature. 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. 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. tiered
, volume
, and stairstep
pricing_models
.This API creates an item price (a price point) for an item.
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
# create an addon item price with tiered pricing model 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
external_name
is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages. Applicable only for item prices with:
item_type
= addon
.pricing_model
= per_unit
.name
is used. The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model
cannot be changed.
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. 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. type
is plan
: The billing period of the plan in period_unit
s. For example, create a 6 month plan by providing period
as 6 and period_unit
as month.type
is addon
: The period of the addon in period_unit
s. 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.period
cannot be changed. The period
is mandatory when the item type
is plan
or addon
. trial_period_unit
s. You can also set trial periods for addons; contact Support to enable that feature. 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. 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. This API retrieves a specific item price using the id.
curl https://{site}.chargebee.com/api/v2/item_prices/basic-USD-monthly \ -u {site_api_key}:
Updates an item price with the changes specified. Unspecified item price attributes are not modified.
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"
external_name
is not provided, this is also used in customer-facing pages and documents such as invoices and hosted pages. Applicable only for item prices with:
item_type
= addon
.pricing_model
= per_unit
.name
is used. currency_code
cannot be changed. The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, pricing_model
cannot be changed.
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. 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. type
is plan
: The billing period of the plan in period_unit
s. For example, create a 6 month plan by providing period
as 6 and period_unit
as month.type
is addon
: The period of the addon in period_unit
s. 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.period
cannot be changed. The period
is mandatory when the item type
is plan
or addon
. trial_period_unit
s. You can also set trial periods for addons; contact Support to enable that feature. 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. 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. 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.
curl https://{site}.chargebee.com/api/v2/item_prices \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
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.
curl https://{site}.chargebee.com/api/v2/item_prices/delete-sample/delete \ -X POST \ -u {site_api_key}:
item_applicability
and applicable_items
defined for the parent item of the plan-item price.curl https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_items \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
item_applicability
and applicable_items
defined for the parent item of the plan-item priceNote
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.
curl https://{site}.chargebee.com/api/v2/item_prices/basic-USD-weekly/applicable_item_prices \ -G \ -u {site_api_key}:\ --data-urlencode limit=2