Create A Differential Price

The device from which the customer has made the request

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

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.

The IP address of the customer where the request originated

skip all actions to be done on the events

One ofall-disabled

skip only emails

One ofall-disabled

skip only webhooks

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

The id of the plan-item, in relation to which, the differential pricing for the addon or charge is defined. For example, this would be the id of the *Standard* or *Enterprise* plans-items mentioned in the [examples above](/docs/api/differential_prices) .

<p class="mb-2">The differential price. If the pricing model of the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_id</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> , or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> , pass <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiers</code> instead of this.</p>

<p class="mb-2">The price of the item when the pricing_model is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">flat_fee</code>. When the pricing model is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">per_unit</code> , 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 <a href="/docs/api/currencies" target="_blank">multi-decimal pricing</a> is enabled.</p>

<p class="mb-2">The unique ID of the <a href="/docs/api/business_entities">business entity</a> for this <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">differential_price</code>. 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.</p> <p class="mb-2"><strong class="font-semibold">Note</strong>: An alternative way of passing this parameter is by using a <a href="/docs/api/advanced-features">custom HTTP header</a> or <a href="/docs/api/advanced-features#mbe-alternative">query string parameter</a>.</p> <span featureId="cb-mbe" isMicro="true"></span>

Parameters for parent_periods

<p class="mb-2">The billing period of the plan in <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_unit</code> s. For example, a 6 month plan has <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period</code> as 6 and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_unit</code> as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">month</code>.</p> <div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note</strong> For a <a href="/docs/api/item_prices">charge-item price</a>,</p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">When <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period_unit]</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period]</code> values are <strong class="font-semibold">passed</strong>, then the <a href="/docs/api/differential_prices/create-a-differential-price#price">price</a> is applied to a <strong class="font-semibold">specific</strong> billing frequency of the plan-item.</li> <li class="text-base leading-relaxed">When <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period_unit]</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period]</code> values are <strong class="font-semibold">not passed</strong>, then the <a href="/docs/api/differential_prices/create-a-differential-price#price">price</a> is applied to <strong class="font-semibold">all</strong> billing frequencies of the plan-item.</li> <li class="text-base leading-relaxed">When parent_periods[period_unit] is <strong class="font-semibold">passed</strong> (eg. month) and the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period]</code> value is <strong class="font-semibold">not passed</strong>, then the price is applied to all <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">parent_periods[period_unit]</code> (eg. monthly) frequencies of the plan-item. Updating or deleting the <a href="/docs/api/differential_prices/create-a-differential-price#price">price</a> after creation will impact all of its related plan-item frequencies.</li> </ul></div>

Parameters for tiers

The lower limit of a range of units for the tier

The upper limit of a range of units for the tier

<p class="mb-2">The per-unit price for the tier when the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> ; the total cost for the item price when the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code>. The value is in the <a href="/docs/api/currencies">minor unit of the currency</a> .</p>

<p class="mb-2">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 <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">ending_unit_in_decimal</code> of the next lower tier. Returned only when the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> and <a href="/docs/api/currencies" target="_blank">multi-decimal pricing</a> is enabled.</p>

<p class="mb-2">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 <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">starting_unit_in_decimal</code> of the next higher tier. Returned only when the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> and <a href="/docs/api/currencies" target="_blank">multi-decimal pricing</a> is enabled.</p>

<p class="mb-2">The decimal representation of the per-unit price for the tier when the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code>. When the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> , 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 <a href="/docs/api/currencies" target="_blank">multi-decimal pricing</a> is enabled.</p>

<p class="mb-2">Package size for the tier when pricing type is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">package</code>. 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.</p>

Differential pricing helps implement a pricing strategy for addons and charges based on the plans they're purchased with. A differential price a specific price for an addon- or charge-[item price](/docs/api/item_prices) when purchased along with a particular plan. Differential pricing for addons ------------------------------- Consider an addon called 24x7 Customer Support provided with a cloud storage service. You can configure differential prices for each of the addon-item prices based on the plan they are purchased with, as follows: |---|-----------------------------------------------------|-----------------------------------------------|-----------------------------------------------------| | | **Addon item price** | **Price when applied to *Standard*** **Plan** | **Price when applied to** ***Enterprise*** **Plan** | | 1 | 24x7 Customer Support, USD, Monthly, Flat fee, $100 | $90 | $150 | | 2 | 24x7 Customer Support, USD, Yearly, Flat fee, $1000 | $900 | $1500 | Differential pricing for charges -------------------------------- Consider a charge, called Setup fee, for installing and configuring a cloud-based project management platform. There are two modes in which you can set up differential pricing for a charge: #### Mode A: One charge differential price per plan-item This mode is used to specify one differential price for the charge-item price per [plan-item](/docs/api/items) it is applied to. |-------------------------------|---------------------------------------------------|-----------------------------------------------------| | **Charge-item price** | **Price when applied to** ***Standard*** **plan** | **Price when applied to** ***Enterprise*** **plan** | | Setup fee, USD, Flat fee $500 | $400 | $700 | #### Mode B: Multiple charge differential prices per plan item This mode is used to specify multiple differential prices for the charge per plan-item, based on the plan period. |-------------------------------|-------------------------------------------------------------|-----------------------------------------------------------| | **Charge-item price** | **Price when applied to** ***Standard*** **plan, 6 months** | **Price when applied to** ***Standard*** **plan, yearly** | | Setup fee, USD, Flat fee $500 | $400 | $300 | In the above example, even if the "6 month" or "yearly" plan-item prices do not exist, the differential prices for the charge can still be created. They take effect whenever the plan-item prices are eventually created and used in subscriptions.

A unique and immutable ID for the differential price. It is auto-generated when the differential price is created.

<p class="mb-2">The ID of the item price (<code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">addon</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">charge</code> ) whose price should change according to the plan-item it is applied to.</p>

The ID of the plan-item, in relation to which, the differential pricing for the addon or charge is defined. For example, this would be the id of the *Standard* or *Enterprise* plans-items mentioned in the [examples above](/docs/api/differential_prices) .

<p class="mb-2">The differential price. If the pricing model of the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_id</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> , or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> , pass <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiers</code> instead of this.</p>

<p class="mb-2">The price of the item when the pricing_model is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">flat_fee</code>. When the pricing model is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">per_unit</code> , 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 <a href="/docs/api/currencies" target="_blank">multi-decimal pricing</a> is enabled.</p>

The item family state. \* active - New items can be created with the item family. \* deleted - No items allowed for the item family.

One ofactivedeleted

<p class="mb-2">Version number of this resource. The <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">resource_version</code> 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.</p>

Timestamp when this differential price was last updated.

Timestamp at which this differential price was created.

Timestamp at which this differential price was last modified.

The currency code (ISO 4217 format) of the plan

The unique ID of the [business entity](/docs/api/getting-started) of this subscription. 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.

Indicates whether the differential price has been deleted or not.

<p class="mb-2">List of quantity-based pricing tiers for the differential price. Applicable only for <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">tiered</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">volume</code> , and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">stairstep</code> <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">pricing_model</code> s. The tiers are exactly the same as those set for the item price. Only the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">price</code> attribute for the various tiers can be overridden for the differential price.</p>

<p class="mb-2">When <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_id</code> is a charge-item, you can specify the plan period for which the price applies. Although an array, currently you can specify only one period. In other words, only index <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">0</code> is allowed. Create another differential price to specify another period. Is permitted only when <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_id</code> is a charge-item.</p>