POST /item_prices

The device from which the customer has made the request

Default value: "application/x-www-form-urlencoded"

skip only webhooks

Possible values:

• "all-disabled"

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.

skip all actions to be done on the events

Possible values:

• "all-disabled"

The email address of your customer/user. Use this when the email address has only ASCII characters.

The IP address of the customer where the request originated

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.

skip only emails

Possible values:

• "all-disabled"

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.

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.

Possible values:

• "tiered"
• "per_unit"
• "stairstep"
• "flat_fee"
• "volume"

Default value: "flat_fee"

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

The currency code (ISO 4217 format) for the item price. Is required when multiple currencies have been enabled.

Defines the shipping frequency. Example: to bill customer every 2 weeks, provide "2" here.

Parameters for tax_detail

The tax profile of the item price.

The Avalara tax codes for the item price. Applicable only if you use AvaTax for Sales integration.

The TaxJar product code for the item price. Applicable only if you use TaxJar integration.

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.

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

Possible values:

• "consumed"
• "retail"
• "vendor_use"
• "wholesale"

Indicates the Avalara service type for the item price. Applicable only if you use the AvaTax for Communications integration.

Indicates the Avalara transaction type for the item price. Applicable only if you use the AvaTax for Communications integration.

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](advanced-features#metadata).

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

The trial period of the plan in trial_period_units. You can also set trial periods for addons; contact Support to enable that feature.

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.

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

The identifier for the item price. It is unique and immutable.

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

Parameters for tiers

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.

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.

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.

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.

The upper limit of a range of units for the tier

The lower limit of a range of units for the tier

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.

Parameters for tax_providers_fields

The value of the corresponding tax field.

Field id of the attribute which tax vendor has provided while getting onboarded with us.

Name of the tax provider currently supported.

The id of the item that the item price belongs to.

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.

The unit of time for trial_period. * month - A period of 1 calendar month. * day - A period of 24 hours.

Possible values:

• "month"
• "day"

Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.
Note: 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

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

An immutable unique identifier of a price variant.

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.

Possible values:

• "site_default"
• "cancel_subscription"
• "activate_subscription"

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.

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

Parameters for accounting_detail

This maps to the sku or product name in the accounting integration.

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.

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: <parent-department> : <sub-department-1>: <sub-department-2>.... For example: Production: Assembly.
• Intacct:If you've classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.

The identifier of the chart of accounts under which the item price falls in the accounting system.

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: <category-name>: <option>.... 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: <parent-location>:<sub-location-1>:<sub-location-2>.... 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 <parent-location> : <sub-location-1>: <sub-location-2>.... For example: NA:US:CA
• Intacct:If you've classified your products in Intacct under Dimensions, provide the value of the Dimension here.

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: <category-name>: <option>. 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: <parent class>:<sub-class-1>:<sub-class-2>...
• NetSuite:If you've categorized your products in NetSuite under Classes, provide the class name here. Use the following format: <parent class>: <sub-class-1>: <sub-class2>.... For example: Services: Plan.
• Intacct:If you've classified your products in Intacct under Locations, provide the name of the Location here.

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.

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

Possible values:

• "month"
• "day"
• "week"
• "year"

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.

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.

Possible values:

• "full_term"
• "site_default"
• "partial_term"

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.

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.

Possible values:

• "never"
• "subscription_billing_frequency"

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.

Possible values:

• "month"
• "day"
• "week"
• "year"