# Item prices

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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](/docs/api/items). 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](https://www.chargebee.com/docs/2.0/plans.html#pricing-models) 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

## Types of item prices[](#types-of-item-prices)

The type of an item price corresponds to the [type of the item](/docs/api/items) 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

## Billing periods for item prices[](#billing-periods-for-item-prices)

The **billing period** of an item price (applicable only to plan-item prices and addon-item prices) is the [`period`](/docs/api/item_prices/item-price-object#period) of the item price in [`period_unit`](/docs/api/item_prices/item-price-object#period_unit)s.

-   When [price variants](/docs/api/price_variants) are **not** enabled, an item can have only one item price for a given currency and billing period.
-   When price variants **are** enabled, an item can have multiple item prices for the same currency and billing period, as long as each has a distinct [`price_variant_id`](/docs/api/item_prices/item-price-object#price_variant_id). An item price created without a `price_variant_id` is treated as the default ("no variant"), and only one such default item price can exist for a given currency and billing period.

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

## Item prices attributes

## 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](/docs/api/invoices) and [hosted pages](/docs/api/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:  
      `- 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.

- `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](/docs/api/invoices) and [hosted pages](/docs/api/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](/docs/api/price_variants).

- `proration_type` (optional, enumerated string)
  **Note** Applicable only for item prices with:
  
  -   `[item_type](/docs/api/item_prices/item_price-object#item_type)` = `addon`.
  -   `[pricing_model](/docs/api/item_prices/item_price-object#pricing_model)` = `per_unit`.
  
  Specifies how to manage charges or credits for the addon item price during a [subscription update](/docs/api/subscriptions/update-subscription-for-items) or [estimating](/docs/api/estimates/estimate-for-updating-a-subscription) a subscription update.
  Possible enum values:
    - `site_default`
      Use the [site-wide proration setting](https://www.chargebee.com/docs/2.0/proration.html#proration-for-subscription-change) .
    - `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](https://www.chargebee.com/docs/2.0/plans.html#pricing-models) for this item price. If subscriptions, invoices or [differential prices](/docs/api/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](/docs/api/currencies) .

- `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](/docs/api/currencies) is enabled.

- `period` (optional, integer, min=1)
  -   When the item `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.
  -   When item `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.](https://www.chargebee.com/docs/2.0/addons-billingcycle.html)
  
  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](https://www.chargebee.com/docs/2.0/supported-currencies.html) ) for the item price. If subscriptions, invoices or [differential prices](/docs/api/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](https://www.chargebee.com/docs/2.0/addons-trial.html) ; contact [Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=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](https://www.chargebee.com/docs/2.0/trial_periods_hidden.html#how-to-define-the-end-of-trial-actions-for-subscriptions) 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](/docs/api/subscriptions/subscription-object#trial_end_action) .
  Possible enum values:
    - `site_default`
      The action [configured for the site](https://www.chargebee.com/docs/1.0/trial_periods_hidden.html#how-to-define-the-end-of-trial-actions-for-subscriptions) 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](/docs/api/subscriptions) for a subscription. Addons can also [have billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html). Also, for addons, you can [override this](/docs/api/attached_items) while attaching it to a plan. However, if you provide the value while [applying the addon to a subscription](/docs/api/subscriptions/subscription-object#subscription_items_item_type), then that value takes still higher precedence. If subscriptions, invoices or [differential prices](/docs/api/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](/docs/api/items/item-object#type) `item_price`.
  -   `free_quantity` is not supported for the [Usage-Based Billing](https://www.chargebee.com/docs/2.0/understanding-usages.html) (UBB). All included or free quantities should be configured exclusively through [entitlements](/docs/api/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](/docs/api/currencies) 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)](/docs/api/in_app_subscriptions) 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)](/docs/api/in_app_subscriptions) 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](mailto: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](/docs/api/invoices/invoice-object#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](https://www.chargebee.com/docs/tax.html) 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](/docs/api/advanced-features#metadata) .

- `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](/docs/api/v2/pcv-1/invoices/create-invoice-for-a-one-time-charge) without being applied to a subscription.

- `show_description_in_invoices` (optional, boolean)
  Whether the item price's description should be shown on [invoice PDFs](/docs/api/invoices/retrieve-invoice-as-pdf). If this Boolean is changed, only invoices generated (or [regenerated](https://www.chargebee.com/docs/invoice-operations.html#actions-for-payment-due-not-paid-invoices_regenerate-invoice) ) 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](/docs/api/quotes/retrieve-quote-as-pdf). 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](/docs/api/business_entities) 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` .
  - `starting_unit` (required, integer, min=1)
    The lower limit of a range of units for the tier
  - `ending_unit` (optional, integer)
    The upper limit of a range of units for the tier
  - `price` (required, in cents, default=0, min=0)
    The per-unit price for the tier when the `pricing_model` is `tiered` or `volume` ; the total cost for the item price when the `pricing_model` is `stairstep`. The value is in the [minor unit of the currency](/docs/api/currencies) .
  - `pricing_type` (optional, enumerated string)
    Pricing type for the tier.
    Possible enum values:
      - `per_unit`
        Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
      - `flat_fee`
        Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the **stairstep** pricing model, `pricing_type` will be set to `flat_fee` by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
      - `package`
        Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20, consuming 400 units will result in a charge of $80 (4 × $20).
  - `package_size` (optional, integer, min=1)
    Package size for the tier when pricing type is `package`. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.

- `tax_detail` (optional, tax_detail)
  The tax details for the item price. Includes those details relevant for third-party integrations.
  - `tax_profile_id` (optional, string, max chars=50)
    The tax profile of the item price.
  - `avalara_sale_type` (optional, enumerated string)
    Indicates the [Avalara sale type](https://developer.avalara.com/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/transaction-information/#lineitem) for the item price. Applicable only if you use the [AvaTax for Communications integration](https://www.chargebee.com/docs/2.0/avatax-for-communication.html) .
    Possible enum values:
      - `wholesale`
        Transaction is a sale to another company that will resell your product or service to another consumer
      - `retail`
        Transaction is a sale to an end user
      - `consumed`
        Transaction is for an item that is consumed directly
      - `vendor_use`
        Transaction is for an item that is subject to vendor use tax
  - `avalara_transaction_type` (optional, integer)
    Indicates the [Avalara transaction type](https://developer.avalara.com/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/transaction-information/#lineitem) for the item price. Applicable only if you use the [AvaTax for Communications integration](https://www.chargebee.com/docs/2.0/avatax-for-communication.html) .
  - `avalara_service_type` (optional, integer)
    Indicates the [Avalara service type](https://developer.avalara.com/communications/dev-guide_rest_v2/customizing-transactions/sample-transactions/transaction-information/#lineitem) for the item price. Applicable only if you use the [AvaTax for Communications integration](https://www.chargebee.com/docs/2.0/avatax-for-communication.html) .
  - `avalara_tax_code` (optional, string, max chars=50)
    The [Avalara tax codes](https://taxcode.avatax.avalara.com) for the item price. Applicable only if you use [AvaTax for Sales integration](https://www.chargebee.com/docs/2.0/avatax-for-sales.html) .
  - `hsn_code` (optional, string, max chars=50)
    The [HSN code](https://cbic-gst.gov.in/gst-goods-services-rates.html) to which the item is mapped for calculating the customer's tax in India. Applicable only when both of the following conditions are true:
    
    -   [**India**](https://www.chargebee.com/docs/indian-gst.html#configuring-indian-gst) has been enabled as a **Tax Region**. (An error is returned when this condition is not true.)
    -   The [**AvaTax for Sales** integration](https://www.chargebee.com/docs/avalara.html) has been enabled in Chargebee.
  - `taxjar_product_code` (optional, string, max chars=50)
    The [TaxJar product code](https://developers.taxjar.com/api/reference/#get-list-tax-categories) for the item price. Applicable only if you use [TaxJar integration](https://www.chargebee.com/docs/2.0/taxjar.html) .

- `tax_providers_fields` (optional, list of tax_providers_field)
  List of vendor specific tax related information.
  - `provider_name` (required, string, max chars=50)
    Name of the tax provider currently supported.
  - `field_id` (required, string, max chars=50)
    Field id of the attribute which tax vendor has provided while getting onboarded with us.
  - `field_value` (required, string, max chars=50)
    The value of the corresponding tax field.

- `accounting_detail` (optional, accounting_detail)
  Accounting integration details. The values are typically dependent on the [accounting integration](https://www.chargebee.com/docs/finance-integration-index.html) used.
  - `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](https://www.chargebee.com/docs/2.0/finance-integration-index.html )
    
    -   [**Xero:**](https://www.chargebee.com/docs/2.0/xero.html ) If you've categorized your products in Xero, provide the category name and option. Use the format: `:` . For example:`Location: Singapore.`
    -   [**QuickBooks:**](https://www.chargebee.com/docs/2.0/quickbooks.html ) If you've categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: `::...`
    -   [**NetSuite:**](https://www.chargebee.com/docs/2.0/netsuite.html ) If you've categorized your products in NetSuite under Classes, provide the class name here. Use the following format: `: : ....` For example: `Services: Plan.`
    -   [**Intacct:**](https://www.chargebee.com/docs/2.0/intacct.html ) 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](https://www.chargebee.com/docs/1.0/finance-integration-index.html )
    
    -   [**Xero:**](https://www.chargebee.com/docs/1.0/xero.html ) If you've categorized your products in Xero, then provide the second category name and option here. Use the format: `: ....` For example, `Region: South`
    -   [**QuickBooks:**](https://www.chargebee.com/docs/1.0/quickbooks.html ) If you've categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: `::....` For example: `Location: North America: Canada`
    -   [**NetSuite:**](https://www.chargebee.com/docs/1.0/netsuite.html ) If you've categorized your products in NetSuite under Locations, provide the location name here. Use the following format `: : ....` For example: `NA:US:CA`
    -   [**Intacct:**](https://www.chargebee.com/docs/1.0/intacct.html ) 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](https://www.chargebee.com/docs/1.0/finance-integration-index.html )
    
    -   [**NetSuite:**](https://www.chargebee.com/docs/1.0/netsuite.html ) If you've categorized your products in NetSuite under Departments, pass the department name here. Use the following format: `: : ....` For example: `Production: Assembly.`
    -   [**Intacct:**](https://www.chargebee.com/docs/1.0/intacct.html ) 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](https://www.chargebee.com/docs/1.0/finance-integration-index.html )
    
    -   [**NetSuite:**](https://www.chargebee.com/docs/1.0/netsuite.html ) Provide the "Revenue Recognition Rule Id" for the product from NetSuite.
    -   [**Intacct:**](https://www.chargebee.com/docs/1.0/intacct.html ) If you have configured "Revenue Recognition Templates" for products in Intacct, provide the template ID for the product.