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

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.

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

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.

Tier attributes

starting_unit

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

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.

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.

Parent period attributes

period_unit

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.

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.

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

Sample Request

# create differential price for addon item price
curl  https://{site}.chargebee.com/api/v2/item_prices/day-pass-USD/differential_prices \
     -X POST  \
     -u {site_api_key}:\
     -d parent_item_id="basic" \
     -d price=100

copy

# create differential price for addon item price
curl  https://{site}.chargebee.com/api/v2/item_prices/day-pass-USD/differential_prices \
     -X POST  \
     -u {site_api_key}:\
     -d parent_item_id="basic" \
     -d price=100

# create differential price for charge item price
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"

# create differential price for addon item price with tiered pricing
# model
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

Sample Response [ JSON ]

{"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
}}

{"differential_price": {
    "created_at": 1594110587,
    "currency_code": "USD",
    "id": "c0f72963-52b2-4d76-84d2-7f021521958c",
    "item_price_id": "ssl-charge-USD",
    "object": "differential_price",
    "parent_item_id": "scale",
    "parent_periods": [
        {
            "period": [
                2,
                {..}
            ],
            "period_unit": "month"
        },
        {..}
    ],
    "price": 200,
    "resource_version": 1594110587825,
    "status": "active",
    "updated_at": 1594110587
}}

{"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
}}

URL Format POST

https://{site}.chargebee.com/api/v2/item_prices/{item_price_id}/differential_prices

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

parent_periods

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

parent_periods[period][0..n]

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.

tiers

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, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

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.

tiers[starting_unit_in_decimal][0..n]

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.

tiers[ending_unit_in_decimal][0..n]

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.

tiers[price_in_decimal][0..n]

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.

differential_price

always returned
Resource object representing differential_price

Retrieve a differential price using a differential_price_id and item_price_id.

Sample Request

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"

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"

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"

Sample Response [ JSON ]

{"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
}}

{"differential_price": {
    "created_at": 1594110588,
    "currency_code": "USD",
    "id": "c4518c7d-d077-43ed-9a43-89c6c5dafa61",
    "item_price_id": "additional-charge-daily-USD",
    "object": "differential_price",
    "parent_item_id": "scale",
    "parent_periods": [
        {
            "period": [
                6,
                {..}
            ],
            "period_unit": "month"
        },
        {..}
    ],
    "price": 500,
    "resource_version": 1594110588428,
    "status": "active",
    "updated_at": 1594110588
}}

URL Format GET

https://{site}.chargebee.com/api/v2/differential_prices/{differential_price_id}

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.

differential_price

always returned
Resource object representing differential_price

Update a differential price using a differential_price_id and item_price_id.

Sample Request

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

copy

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

# update a differential price for charge item
curl  https://{site}.chargebee.com/api/v2/differential_prices/38afc406-cae1-47ca-94aa-40098c4cc02b \
     -X POST  \
     -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"

Sample Response [ JSON ]

{"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
}}

{"differential_price": {
    "created_at": 1594110588,
    "currency_code": "USD",
    "id": "38afc406-cae1-47ca-94aa-40098c4cc02b",
    "item_price_id": "sample-charge-USD",
    "object": "differential_price",
    "parent_item_id": "basic",
    "parent_periods": [
        {
            "period": [
                2,
                {..}
            ],
            "period_unit": "month"
        },
        {..}
    ],
    "price": 350,
    "resource_version": 1594110588785,
    "status": "active",
    "updated_at": 1594110588
}}

URL Format POST

https://{site}.chargebee.com/api/v2/differential_prices/{differential_price_id}

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

parent_periods

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

parent_periods[period][0..n]

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.

tiers

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, integer, min=1
The lower limit of a range of units for the tier

tiers[ending_unit][0..n]

optional, integer
The upper limit of a range of units for the tier

tiers[price][0..n]

optional, in cents, 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.

tiers[starting_unit_in_decimal][0..n]

tiers[ending_unit_in_decimal][0..n]

tiers[price_in_decimal][0..n]

differential_price

always returned
Resource object representing differential_price

Delete a differential price using a differential_price_id and item_price_id.

Sample Request

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

copy

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

Sample Response [ JSON ]

{"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

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.

differential_price

always returned
Resource object representing differential_price

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

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "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

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[<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.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_price_id[is] = "day-pass-USD"

item_id[<operator>]

optional, string filter
Item Id of Addon / Charge item price for which differential pricing is applied to.
Supported operators : is, is_not, starts_with, in, not_in

Example → item_id[is] = "day-pass"

id[<operator>]

optional, string filter
A unique and immutable id for the differential price. It is auto-generated when the differential price is created.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "defcc4f1-f21f-47f4-8019-beddb9beab5f"

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.
Supported operators : is, is_not, starts_with, in, not_in

Example → parent_item_id[is] = "basic"

differential_price

always returned
Resource object representing differential_price

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

Differential pricing for addons

Differential pricing for charges

Mode A: One charge differential price per plan-item

Mode B: Multiple charge differential prices per plan item

Sample differential price [ JSON ]

API Index URL GET

Differential price attributes

Create a differential price¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Retrieve a differential price¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Returns

Update a differential price¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Delete a differential price¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List differential prices¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns