Settings
API Version
Product Catalog
Library

Differential prices

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

Model Class

 

      Differential price attributes
      
 
id
 

      string, max chars=100
 A unique and immutable ID for the differential price. It is auto-generated when the differential price is created. 
 
 
item_price_id
 

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

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

      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. 
 
 
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 is enabled. 
 
 
status
 

      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.
 
activeNew items can be created with the item family.deletedNo items allowed for the item family.
 
 Show all values[+]
 
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 when this differential price was last updated. 
 
 
created_at
 

      timestamp(UTC) in seconds
 Timestamp at which this differential price was created. 
 
 
modified_at
 

      timestamp(UTC) in seconds
 Timestamp at which this differential price was last modified. 
 
 
currency_code
 

      string, max chars=3
 The currency code (ISO 4217 format) of the plan 
 
 
business_entity_id
 

      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. 

 
 
Multiple Business Entities is in early access. Submit a request to enable this feature.  
  
 
 
 
deleted
 

      boolean
 Indicates whether the differential price has been deleted or not. 
 
 
 

      tiers
 Show attributes [+]
 
 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.
 
 
 

      parent_periods
 Show attributes [+]
 
 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.
 
 
 
 
id id
 

          string, max chars=100
 A unique and immutable ID for the differential price. It is auto-generated when the differential price is created. 
 
item_price_id item_price_id
 

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

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

          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. 
 
price_in_decimal 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 is enabled. 
 
status status
 

          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.
 
activeNew items can be created with the item family.deletedNo items allowed for the item family.
 
 Show all values[+]
resource_version 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 updated_at
 

          optional, timestamp(UTC) in seconds
 Timestamp when this differential price was last updated. 
 
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp at which this differential price was created. 
 
modified_at modified_at
 

          timestamp(UTC) in seconds
 Timestamp at which this differential price was last modified. 
 
currency_code currency_code
 

          string, max chars=3
 The currency code (ISO 4217 format) of the plan 
 
business_entity_id business_entity_id
 

          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. 

 
 
Multiple Business Entities is in early access. Submit a request to enable this feature.  
  
 
 
deleted deleted
 

          boolean
 Indicates whether the differential price has been deleted or not. 
 
tiers 
 

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

          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. 
 
 
 
Consent Fields for Differential price
 
 
Custom Fields for Differential price
 
 

      Create a differential price
      
 
Idempotency Supported
 
 
Create a differential price for addon item price, addon item price with tiered pricing, or charge item price.
  
Notes
 
 

      Sample Codes
    
 
 
curl  https://{site}.chargebee.com/api/v2/item_prices/day-pass-USD/differential_prices \
     -u {site_api_key}:\
     -d parent_item_id="basic" \
     -d price=100
curl  https://{site}.chargebee.com/api/v2/item_prices/ssl-charge-USD/differential_prices \
     -X POST  \
     -u {site_api_key}:\
     -d parent_item_id="scale" \
     -d price=200 \
     -d "parent_periods[period][0]"=[2] \
     -d "parent_periods[period_unit][0]"="MONTH" 
curl  https://{site}.chargebee.com/api/v2/item_prices/day-pass-USD-tier-weekly/differential_prices \
     -X POST  \
     -u {site_api_key}:\
     -d parent_item_id="basic" \
     -d "tiers[starting_unit][0]"=1 \
     -d "tiers[ending_unit][0]"=10 \
     -d "tiers[price][0]"=120 \
     -d "tiers[starting_unit][1]"=11 \
     -d "tiers[ending_unit][1]"=20 \
     -d "tiers[price][1]"=350 \
     -d "tiers[starting_unit][2]"=21 \
     -d "tiers[price][2]"=650 
 

      copy
      
Click to Copy
 
Create differential price for addon item price
 
curl  https://{site}.chargebee.com/api/v2/item_prices/day-pass-USD/differential_prices \
     -u {site_api_key}:\
     -d parent_item_id="basic" \
     -d price=100
 
 

    Sample Result [ 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
    
 
Method
 
 
Input Parameters
 
  
 
parent_item_id[]
 

      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. 
 
price[]
 

      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. 
 
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 is enabled. 
 
business_entity_id[]
 

      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.
 
 
 
Multiple Business Entities is in early access. Submit a request to enable this feature.  
  
. 
 
 
 
 
 
period_unit
 
required, 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.
 
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[+]
period
 
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. 
 
Note
 
For a charge-item price,
 
     
  • When parent_periods[period_unit] and parent_periods[period] values are passed, then the price is applied to a specific billing frequency of the plan-item.
    •  
  • When parent_periods[period_unit] and parent_periods[period] values are not passed, then the price is applied to all billing frequencies of the plan-item.
    •  
  • When parent_periods[period_unit] is passed (eg. month) and the parent_periods[period] value is not passed, then the price is applied to all parent_periods[period_unit] (eg. monthly) frequencies of the plan-item. Updating or deleting the price after creation will impact all of its related plan-item frequencies.
    •  
 
 
 
 
starting_unit
 
optional, 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
 
optional, 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. 
starting_unit_in_decimal
 
optional, string, max chars=33 
 The decimal representation of the 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. 
ending_unit_in_decimal
 
optional, string, max chars=33 
 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. 
price_in_decimal
 
optional, string, max chars=39 
 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. 
pricing_type
 
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).
 
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[+]
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. 
   
 
Returns
 
differential_price  differential_price
 

      always returned 
 
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 
  
 
  

 

 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/differential_prices/123x
    

      Retrieve a differential price
      
  
 
Retrieve a differential price using a differential_price_id and item_price_id.
  
Notes
 
 

      Sample Codes
    
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/9d6e5ac7-5c3a-4b63-a148-c182d51ed122 \
     -u {site_api_key}:\
     -d item_price_id="sample-addon-weekly-usd"
curl  https://{site}.chargebee.com/api/v2/differential_prices/c4518c7d-d077-43ed-9a43-89c6c5dafa61 \
     -u {site_api_key}:\
     -d item_price_id="additional-charge-daily-USD"
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/9d6e5ac7-5c3a-4b63-a148-c182d51ed122 \
     -u {site_api_key}:\
     -d item_price_id="sample-addon-weekly-usd"
 
 

    Sample Result [ 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}
    
 
Method
 
 
Input Parameters
 
item_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. 
   
 
    
 
Returns
 
differential_price  differential_price
 

      always returned 
 
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 
  
 
  

 

 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/differential_prices/123x
    

      Update a differential price
      
 
Idempotency Supported
 
 
Update a differential price using a differential_price_id and item_price_id.
  
Notes
 
 

      Sample Codes
    
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/304e773d-2538-4dd8-89d8-d9b478724e21 \
     -u {site_api_key}:\
     -d item_price_id="additional-user-addon-USD" \
     -d price=350
curl  https://{site}.chargebee.com/api/v2/differential_prices/38afc406-cae1-47ca-94aa-40098c4cc02b \
     -u {site_api_key}:\
     -d item_price_id="sample-charge-USD" \
     -d price=350 \
     -d "parent_periods[period][0]"=[2] \
     -d "parent_periods[period_unit][0]"="MONTH" 
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/304e773d-2538-4dd8-89d8-d9b478724e21 \
     -u {site_api_key}:\
     -d item_price_id="additional-user-addon-USD" \
     -d price=350
 
 

    Sample Result [ 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}
    
 
Method
 
 
Input Parameters
 
  
 
item_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. 
 
price[]
 

      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. 
 
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 is enabled. 
 
 
 
 
 
period_unit
 
required, 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.
 
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[+]
period
 
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. 
 
Note
 
For a charge-item price,
 
     
  • When parent_periods[period_unit] and parent_periods[period] values are passed, then the price is applied to a specific billing frequency of the plan-item.
    •  
  • When parent_periods[period_unit] and parent_periods[period] values are not passed, then the price is applied to all billing frequencies of the plan-item.
    •  
  • When parent_periods[period_unit] is passed (eg. month) and the parent_periods[period] value is not passed, then the price is applied to all parent_periods[period_unit] (eg. monthly) frequencies of the plan-item. Updating or deleting the price after creation will impact all of its related plan-item frequencies.
    •  
 
 
 
 
starting_unit
 
optional, 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
 
optional, 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. 
starting_unit_in_decimal
 
optional, string, max chars=33 
 The decimal representation of the 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. 
ending_unit_in_decimal
 
optional, string, max chars=33 
 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. 
price_in_decimal
 
optional, string, max chars=39 
 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. 
pricing_type
 
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).
 
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[+]
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. 
   
 
Returns
 
differential_price  differential_price
 

      always returned 
 
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 
  
 
  

 

 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/differential_prices/123x
    

      Delete a differential price
      
 
Idempotency Supported
 
 
Delete a differential price using a differential_price_id and item_price_id.
  
Notes
 
 

      Sample Codes
    
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/0680411c-33c0-4252-a9a8-e34a3b976711/delete \
     -u {site_api_key}:\
     -d item_price_id="sample-addon-USD"
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices/0680411c-33c0-4252-a9a8-e34a3b976711/delete \
     -u {site_api_key}:\
     -d item_price_id="sample-addon-USD"
 
 

    Sample Result [ 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
    
 
Method
 
 
Input Parameters
 
  
 
item_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. 
 
 
    
 
Returns
 
differential_price  differential_price
 

      always returned 
 
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 
  
 
  

 

 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/differential_prices/123x
    

      List differential prices
      
  
 
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).
  
Notes
 
 

      Sample Codes
    
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/differential_prices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
 
 

    Sample Result [ 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
    
 
Method
 
 
Input Parameters
 
limit[]
 

      optional, integer, default=10, min=1, max=100 
 The number of resources to be returned. 
offset[]
 

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

          For operator usages, see the
          Pagination and Filtering
          section.
        
 
item_price_id
  
 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 : 
    

Example → day-pass-USD
 
 
 
is
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
is_not
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
starts_with
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
not_in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
item_id
  
 optional, string filter
 Item Id of Addon / Charge item price for which differential pricing is applied to. Possible values are :  
Supported operators : 
    

Example → day-pass
 
 
 
is
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
is_not
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
starts_with
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
not_in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
id
  
 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 : 
    

Example → defcc4f1-f21f-47f4-8019-beddb9beab5f
 
 
 
is
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
is_not
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
starts_with
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
not_in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
parent_item_id
  
 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 : 
    

Example → basic
 
 
 
is
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
is_not
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
starts_with
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
not_in
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
Returns
 
differential_price  differential_price
 

      always returned 
 
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 
  
 
  

 

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