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 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 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.
Sample differential price [ JSON ]
{
"created_at": 1594110587,
"currency_code": "USD",
"id": "1b53489f-d5b7-45e3-a010-b11ca19cbc27",
"item_price_id": "day-pass-USD",
"object": "differential_price",
"parent_item_id": "basic",
"price": 100,
"resource_version": 1594110587730,
"status": "active",
"updated_at": 1594110587
}
API Index URL GET
https://{site}.chargebee.com/api/v2/differential_prices
string, max chars=100 A unique and immutable ID for the differential price. It is auto-generated when the differential price is created.
string, max chars=100 The ID of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
string, max chars=100 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.
optional, in cents, min=0 The differential price. If the pricing model of the item_price_id is tiered, volume, or stairstep, pass tiers instead of this.
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.
optional, enumerated string The item family state. Possible values are
activeNew items can be created with the item family.deletedNo items allowed for the item family.
Show all values[+]
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.
optional, timestamp(UTC) in seconds Timestamp when this differential price was last updated.
timestamp(UTC) in seconds Timestamp at which this differential price was created.
timestamp(UTC) in seconds Timestamp at which this differential price was last modified.
string, max chars=3 The currency code (ISO 4217 format) of the plan
optional, string, max chars=50 The unique ID of the
business entity 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.
boolean Indicates whether the differential price has been deleted or not. optional, list of tier
List of quantity-based pricing tiers for the differential price. Applicable only for tiered, volume, and stairstep pricing_model s. The tiers are exactly the same as those set for the item price. Only the price attribute for the various tiers can be overridden for the differential price.
integer, min=1 The lower limit of a range of units for the tier
optional, integer The upper limit of a range of units for the tier
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.
optional, enumerated string Pricing type for the tier. Possible values are
per_unitIndicates 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_feeIndicates 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.packageIndicates 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).
Show all values[+]
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. optional, list of parent_period
When item_price_id 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 0 is allowed. Create another differential price to specify another period. Is permitted only when item_price_id is a charge-item.
enumerated string The unit of time for period. Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
Show all values[+]
optional, jsonarray The billing period of the plan in period_units. For example, a 6 month plan has period as 6 and period_unit as month.
string, max chars=100 A unique and immutable ID for the differential price. It is auto-generated when the differential price is created.
string, max chars=100 The ID of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
string, max chars=100 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.
optional, in cents, min=0 The differential price. If the pricing model of the item_price_id is tiered, volume, or stairstep, pass tiers instead of this.
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.
optional, enumerated string The item family state. Possible values are
activeNew items can be created with the item family.deletedNo items allowed for the item family.
Show all values[+]
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.
optional, timestamp(UTC) in seconds Timestamp when this differential price was last updated.
timestamp(UTC) in seconds Timestamp at which this differential price was created.
timestamp(UTC) in seconds Timestamp at which this differential price was last modified.
string, max chars=3 The currency code (ISO 4217 format) of the plan
optional, string, max chars=50 The unique ID of the
business entity 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.
boolean Indicates whether the differential price has been deleted or not.
optional, list of tier List of quantity-based pricing tiers for the differential price. Applicable only for tiered, volume, and stairstep pricing_model s. The tiers are exactly the same as those set for the item price. Only the price attribute for the various tiers can be overridden for the differential price.
optional, list of parent_period When item_price_id 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 0 is allowed. Create another differential price to specify another period. Is permitted only when item_price_id is a charge-item. Create a differential price for addon item price, addon item price with tiered pricing, or charge item price.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Create differential price for addon item price
Create differential price for addon item price
Create differential price for charge item price
Create differential price for addon item price with tiered pricing model
Sample Response [ JSON ]
Show more...
{
"differential_price": {
"created_at": 1594110587,
"currency_code": "USD",
"id": "1b53489f-d5b7-45e3-a010-b11ca19cbc27",
"item_price_id": "day-pass-USD",
"object": "differential_price",
"parent_item_id": "basic",
"price": 100,
"resource_version": 1594110587730,
"status": "active",
"updated_at": 1594110587
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/item_prices/{item-price-id}/differential_prices
required, string, max chars=100 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.
optional, in cents, min=0 The differential price. If the pricing model of the item_price_id is tiered, volume, or stairstep, pass tiers instead of this.
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.
optional, string, max chars=50 The unique ID of the business entity for this differential_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 using a custom HTTP header or query string parameter.
. parent_periods[[0..n]][0..n]
optional, array Parameters for parent_periods. Multiple parent_periods can be passed by specifying unique indices.
optional, array Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
Parameters for parent_periods. Multiple parent_periods can be passed by specifying unique indices.
pass parameters as parent_periods[<param name>][<idx:0..n>]
parent_periods[period_unit][0..n] required, enumerated string Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
Show all values[+] parent_periods[period][0..n]
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tiers[starting_unit][0..n] optional, in cents, default=0, min=0 tiers[starting_unit_in_decimal][0..n] optional, string, max chars=33 tiers[ending_unit_in_decimal][0..n] optional, string, max chars=33 tiers[price_in_decimal][0..n] optional, string, max chars=39 tiers[pricing_type][0..n] optional, enumerated string Possible values are
per_unitIndicates 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_feeIndicates 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.packageIndicates 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).
Show all values[+] tiers[package_size][0..n]
always returned required
Resource object representing differential_price
Sample admin console URL
https://{site}.chargebee.com/admin-console/differential_prices/123x
Retrieve a differential price using a differential_price_id and item_price_id.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"differential_price": {
"created_at": 1594110588,
"currency_code": "USD",
"id": "9d6e5ac7-5c3a-4b63-a148-c182d51ed122",
"item_price_id": "sample-addon-weekly-usd",
"object": "differential_price",
"parent_item_id": "basic",
"price": 100,
"resource_version": 1594110588325,
"status": "active",
"updated_at": 1594110588
}
}
URL Format
GET
https://{site}.chargebee.com/api/v2/differential_prices/{differential-price-id}
required, string, max chars=100 The id of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
always returned required
Resource object representing differential_price
Sample admin console URL
https://{site}.chargebee.com/admin-console/differential_prices/123x
Update a differential price using a differential_price_id and item_price_id.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Update a differential price for charge item
Sample Response [ JSON ]
Show more...
{
"differential_price": {
"created_at": 1594110588,
"currency_code": "USD",
"id": "304e773d-2538-4dd8-89d8-d9b478724e21",
"item_price_id": "additional-user-addon-USD",
"object": "differential_price",
"parent_item_id": "scale",
"price": 350,
"resource_version": 1594110588618,
"status": "active",
"updated_at": 1594110588
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/differential_prices/{differential-price-id}
required, string, max chars=100 The id of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
optional, in cents, min=0 The differential price. If the pricing model of the item_price_id is tiered, volume, or stairstep, pass tiers instead of this.
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. parent_periods[[0..n]][0..n]
optional, array Parameters for parent_periods. Multiple parent_periods can be passed by specifying unique indices.
optional, array Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
Parameters for parent_periods. Multiple parent_periods can be passed by specifying unique indices.
pass parameters as parent_periods[<param name>][<idx:0..n>]
parent_periods[period_unit][0..n] required, enumerated string Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
Show all values[+] parent_periods[period][0..n]
Parameters for tiers. Multiple tiers can be passed by specifying unique indices.
pass parameters as tiers[<param name>][<idx:0..n>]
tiers[starting_unit][0..n] optional, in cents, default=0, min=0 tiers[starting_unit_in_decimal][0..n] optional, string, max chars=33 tiers[ending_unit_in_decimal][0..n] optional, string, max chars=33 tiers[price_in_decimal][0..n] optional, string, max chars=39 tiers[pricing_type][0..n] optional, enumerated string Possible values are
per_unitIndicates 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_feeIndicates 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.packageIndicates 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).
Show all values[+] tiers[package_size][0..n]
always returned required
Resource object representing differential_price
Sample admin console URL
https://{site}.chargebee.com/admin-console/differential_prices/123x
Delete a differential price using a differential_price_id and item_price_id.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"differential_price": {
"created_at": 1594110588,
"currency_code": "USD",
"id": "0680411c-33c0-4252-a9a8-e34a3b976711",
"item_price_id": "sample-addon-USD",
"object": "differential_price",
"parent_item_id": "basic",
"price": 100,
"resource_version": 1594110588167,
"status": "deleted",
"updated_at": 1594110588
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/differential_prices/{differential-price-id}/delete
required, string, max chars=100 The id of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
always returned required
Resource object representing differential_price
Sample admin console URL
https://{site}.chargebee.com/admin-console/differential_prices/123x
Returns a list of differential prices satisfying all the conditions specified in the filter parameters below. The list is sorted by the date of creation in descending order (latest first).
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"list": [
{
"differential_price": {
"created_at": 1594110588,
"currency_code": "USD",
"id": "e1340212-f684-4555-a0e2-a698c0081b1a",
"item_price_id": "day-pass-USD-tier-weekly",
"object": "differential_price",
"parent_item_id": "basic",
"resource_version": 1594110588073,
"status": "active",
"tiers": [
{
"ending_unit": 10,
"price": 120,
"starting_unit": 1
},
{..}
],
"updated_at": 1594110588
}
},
{..}
],
"next_offset": "1"
}
URL Format
GET
https://{site}.chargebee.com/api/v2/differential_prices
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
optional, string, max chars=1000 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
item_price_id[<operator>] item_price_id[<operator>] optional, string filter
The id of the item price (addon or charge) whose price should change according to the plan-item it is applied to. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in
Example → item_price_id[is] = "day-pass-USD"
The id of the item price (addon or charge) whose price should change according to the plan-item it is applied to.
pass parameters as item_price_id[<param name>][<operator>]
item_price_id[is][operator] item_price_id[is][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
item_price_id[is_not][operator] item_price_id[is_not][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
item_price_id[starts_with][operator] item_price_id[starts_with][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
item_price_id[in][operator] item_price_id[in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
item_price_id[not_in][operator] item_price_id[not_in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Item Id of Addon / Charge item price for which differential pricing is applied to. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in
Example → item_id[is] = "day-pass"
Item Id of Addon / Charge item price for which differential pricing is applied to.
pass parameters as item_id[<param name>][<operator>]
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
item_id[is_not][operator] item_id[is_not][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
item_id[starts_with][operator] item_id[starts_with][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
item_id[not_in][operator] item_id[not_in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
A unique and immutable id for the differential price. It is auto-generated when the differential price is created. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "defcc4f1-f21f-47f4-8019-beddb9beab5f"
A unique and immutable id for the differential price. It is auto-generated when the differential price is created.
pass parameters as id[<param name>][<operator>]
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
id[starts_with][operator] id[starts_with][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
parent_item_id[<operator>] parent_item_id[<operator>] optional, string filter 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. Possible values are : Supported operators : is, is_not, starts_with, in, not_in
Example → parent_item_id[is] = "basic" 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. pass parameters as parent_item_id[<param name>][<operator>] parent_item_id[is][operator] parent_item_id[is][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
parent_item_id[is_not][operator] parent_item_id[is_not][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
parent_item_id[starts_with][operator] parent_item_id[starts_with][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
parent_item_id[in][operator] parent_item_id[in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
parent_item_id[not_in][operator] parent_item_id[not_in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
always returned required
Resource object representing differential_price
always returned optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/differential_prices/123x
Settings
Configure SDK
