ChargebeeAPI

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_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 priceJSON

Item prices attributes

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 .

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.

status
optional, enumerated string

The status of the item price.

Possible Enum Values
active

The item price can be used in subscriptions.

archived

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

deleted

Indicates 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

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:

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.

pricing_model
required, 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
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
required, 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 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.

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.

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

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.

free_quantity
required, 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.

channel
optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible Enum Values
web

The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.

app_store

The 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_store

The 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
required, 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 Enum Values
never

Accumulates usage without ever resetting it.

subscription_billing_frequency

Accumulates usage until the subscription's billing frequency ends.

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 Enum Values
plan

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

addon

A recurring component that can be added to a subscription in addition to its plan.

charge

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

deleted
required, 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
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.