POST /item_prices

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

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`price_in_decimal`	String	No	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.
`pricing_model`	String	No	The pricing scheme for this item price. If subscriptions, invoices or differential prices exist for this item price, `pricing_model` cannot be changed. * tiered - There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers. * per_unit - A fixed price per unit quantity. * flat_fee - A fixed price that is not quantity-based. * 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. Valid values: `"tiered"` `"per_unit"` `"stairstep"` `"flat_fee"` `"volume"` Default value: "flat_fee"
`description`	String	No	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.
`currency_code`	String	No	The currency code (ISO 4217 format ) for the item price. Is required when multiple currencies have been enabled.
`shipping_period`	Integer	No	Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.
`tax_detail`	Object	No	Parameters for tax_detail
`tax_detail.tax_profile_id`	String	No	The tax profile of the item price.
`tax_detail.avalara_tax_code`	String	No	The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration .
`tax_detail.taxjar_product_code`	String	No	The TaxJar product code for the item price. Applicable only if you use TaxJar integration .
`tax_detail.hsn_code`	String	No	The HSN code 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 has been enabled as a Tax Region. (An error is returned when this condition is not true.) The AvaTax for Sales integration has been enabled in Chargebee.
`tax_detail.avalara_sale_type`	String	No	Indicates the Avalara sale type for the item price. Applicable only if you use the AvaTax for Communications integration . * vendor_use - Transaction is for an item that is subject to vendor use tax * consumed - Transaction is for an item that is consumed directly * 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 Valid values: `"consumed"` `"retail"` `"vendor_use"` `"wholesale"`
`tax_detail.avalara_service_type`	Integer	No	Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration .
`tax_detail.avalara_transaction_type`	Integer	No	Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration .
`metadata`	Object	No	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](/docs/api/advanced-features#metadata) .
`business_entity_id`	String	No	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.
`trial_period`	Integer	No	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.
`invoice_notes`	String	No	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.
`show_description_in_invoices`	Boolean	No	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. Default value: false
`id`	String	Yes	The identifier for the item price. It is unique and immutable.
`period`	Integer	No	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. 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.
`tiers`	Object	No	Parameters for tiers
`tiers.starting_unit_in_decimal[]`	Array	No	The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as `ending_unit_in_decimal` of the next lower tier. Returned only when the `pricing_model` is `tiered` , `volume` or `stairstep` and multi-decimal pricing is enabled.
`tiers.price_in_decimal[]`	Array	No	The decimal representation of the per-unit price for the tier when the `pricing_model` is `tiered` or `volume`. When the `pricing_model` is `stairstep` , it is the decimal representation of the total price for the addon. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
`tiers.package_size[]`	Array	No	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.
`tiers.price[]`	Array	No	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 .
`tiers.ending_unit[]`	Array	No	The upper limit of a range of units for the tier
`tiers.pricing_type[]`	Array	No
`tiers.starting_unit[]`	Array	No	The lower limit of a range of units for the tier
`tiers.ending_unit_in_decimal[]`	Array	No	The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the `starting_unit_in_decimal` of the next higher tier. Returned only when the `pricing_model` is `tiered` , `volume` or `stairstep` and multi-decimal pricing is enabled.
`tax_providers_fields`	Object	No	Parameters for tax_providers_fields
`tax_providers_fields.field_value[]`	Array	Yes	The value of the corresponding tax field.
`tax_providers_fields.field_id[]`	Array	Yes	Field id of the attribute which tax vendor has provided while getting onboarded with us.
`tax_providers_fields.provider_name[]`	Array	Yes	Name of the tax provider currently supported.
`item_id`	String	Yes	The id of the item that the item price belongs to.
`price`	Integer	No	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 .
`trial_period_unit`	String	No	The unit of time for `trial_period` . * month - A period of 1 calendar month. * day - A period of 24 hours. Valid values: `"month"` `"day"`
`free_quantity`	Integer	No	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 . Default value: 0
`show_description_in_quotes`	Boolean	No	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. Default value: false
`price_variant_id`	String	No	An immutable unique identifier of a price variant.
`trial_end_action`	String	No	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 . * cancel_subscription - The subscription cancels. * activate_subscription - The subscription activates and charges are raised for non-metered items. * site_default - The action configured for the site at the time when the trial ends, takes effect. Valid values: `"site_default"` `"cancel_subscription"` `"activate_subscription"`
`free_quantity_in_decimal`	String	No	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.
`is_taxable`	Boolean	No	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. Default value: true
`accounting_detail`	Object	No	Parameters for accounting_detail
`accounting_detail.sku`	String	No	This maps to the sku or product name in the accounting integration.
`accounting_detail.accounting_category4`	String	No	Used exclusively with the following accounting integrations NetSuite: Provide the "Revenue Recognition Rule Id" for the product from NetSuite. Intacct: If you have configured "Revenue Recognition Templates" for products in Intacct, provide the template ID for the product.
`accounting_detail.accounting_category3`	String	No	Used exclusively with the following accounting integrations NetSuite: If you've categorized your products in NetSuite under Departments, pass the department name here. Use the following format: `: : ....` For example: `Production: Assembly.` Intacct: If you've classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.
`accounting_detail.accounting_code`	String	No	The identifier of the chart of accounts under which the item price falls in the accounting system.
`accounting_detail.accounting_category2`	String	No	Used exclusively with the following accounting integrations Xero: 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: 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: 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: If you've classified your products in Intacct under Dimensions, provide the value of the Dimension here.
`accounting_detail.accounting_category1`	String	No	Used exclusively with the following accounting integrations Xero: If you've categorized your products in Xero, provide the category name and option. Use the format: `:` . For example:`Location: Singapore.` QuickBooks: If you've categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: `::...` NetSuite: If you've categorized your products in NetSuite under Classes, provide the class name here. Use the following format: `: : ....` For example: `Services: Plan.` Intacct: If you've classified your products in Intacct under Locations, provide the name of the Location here.
`billing_cycles`	Integer	No	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.
`period_unit`	String	No	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 . * month - A period of 1 calendar month. * week - A period of 7 days. * year - A period of 1 calendar year. * day - A period of 24 hours. Valid values: `"month"` `"day"` `"week"` `"year"`
`name`	String	Yes	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 .
`proration_type`	String	No	Note Applicable only for item prices with: `item_type` = `addon`. `pricing_model` = `per_unit`. Specifies how to manage charges or credits for the addon item price during a subscription update or estimating a subscription update. * full_term - Charge the full price of the addon item price or give the full credit. Don't apply any proration. * site_default - Use the site-wide proration setting . * partial_term - Prorate the charges or credits for the rest of the current term. Valid values: `"full_term"` `"site_default"` `"partial_term"`
`external_name`	String	No	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.
`usage_accumulation_reset_frequency`	String	No	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. . * never - Accumulates usage without ever resetting it. * subscription_billing_frequency - Accumulates usage until the subscription's billing frequency ends. Valid values: `"never"` `"subscription_billing_frequency"`
`shipping_period_unit`	String	No	Defines the shipping frequency in association with shipping period. * day - A period of 24 hours. * week - A period of 7 days. * year - A period of 1 calendar year. * month - A period of 1 calendar month. Valid values: `"month"` `"day"` `"week"` `"year"`

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.