The ramp resource or a subscription ramp represents a planned change to a subscription set to occur at a future date. By using this resource, you can define and schedule modifications to a subscription, such as updating pricing, altering the quantity, or transitioning to a different plan, without immediately applying them.
Note - Upcoming ramps limit: A subscription can have a maximum of 12 upcoming ramps at any given time, excluding deleted ramps. Upcoming ramps are ramps with
status as scheduled. - Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
- Update subscription for items limit:
changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.
Sample ramp [ JSON ]
{
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Schedule for first ramp",
"created_at": "1635054328",
"deleted": false,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly"
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
}
]
}
API Index URL GET
https://{site}.chargebee.com/api/v2/ramps
string, max chars=50 A unique and immutable identifier for the ramp.
optional, string, max chars=250 A brief summary of the pricing changes applied with this ramp.
string, max chars=50 The ID of the subscription for which this ramp was created.
timestamp(UTC) in seconds Specifies the time when the changes to the subscription will be applied by executing the ramp.
enumerated string The execution status of the ramp Possible values are
scheduledThe ramp has been created and scheduled for execution. Note Excluding deleted ramps, a subscription can have a maximum of 12 ramps in the scheduled status.
succeededThe ramp completed successfully.failedThe ramp did not complete because of an error.draftThe ramp is moved to draft status when the associated subscription is updated. The reason for the draft status can be explained in the status_transition_reason Note Ramps in draft state will not be executed.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this resource was created.
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.
optional, timestamp(UTC) in seconds Timestamp indicating when this resource was last updated.
optional, list of string List of item prices removed from the subscription through this ramp.
optional, list of string List of coupons removed from the subscription through this ramp.
optional, list of string List of discounts removed from the subscription through this ramp. optional, list of items_to_add Details about the item prices added to the subscription through this ramp.
string, max chars=100 The unique identifier of the item price.
enumerated string The type of item. There must be one and only one item of type plan in this list.
optional, integer, min=1 The quantity of the item purchased
optional, string, max chars=33 The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, in cents, min=0 The price/per unit price of the item. When not provided, the value set for the item price is used. This is only applicable when the pricing_model of the item price is flat_fee or per_unit. Also, it is only allowed when price overriding is enabled for the site. The value depends on the type of currency.
optional, string, max chars=39 The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, in cents, min=0 The total amount for the item as determined from unit_price, free_quantity, quantity and item_tiers as applicable. The value depends on the type of currency.
optional, string, max chars=39 The decimal representation of the total amount for the item, in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, integer, min=0 The quantity of the item price that is available for free. Only the quantity more than this will be charged for the subscription. This is the same as item_price.free_quantity.
optional, string, max chars=33 The free_quantity_in_decimal as set for the item price. Returned for quantity-based item prices when multi-decimal pricing is enabled.
optional, integer, min=1, max=730 The service period of the item in days from the day of charge.
optional, string, max chars=100 This field represents the number of quantities recorded against this subscription item in the current term optional, list of items_to_update Details about the item prices updated in the subscription through this ramp.
Items to update attributes
string, max chars=100 The unique identifier of the item price.
enumerated string The type of item. There must be one and only one item of type plan in this list.
optional, integer, min=1 The quantity of the item purchased
optional, string, max chars=33 The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, in cents, min=0 The price/per unit price of the item. When not provided, the value set for the item price is used. This is only applicable when the pricing_model of the item price is flat_fee or per_unit. Also, it is only allowed when price overriding is enabled for the site. The value depends on the type of currency.
optional, string, max chars=39 The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, in cents, min=0 The total amount for the item as determined from unit_price, free_quantity, quantity and item_tiers as applicable. The value depends on the type of currency.
optional, string, max chars=39 The decimal representation of the total amount for the item, in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, integer, min=0 The quantity of the item price that is available for free. Only the quantity more than this will be charged for the subscription. This is the same as item_price.free_quantity..
optional, string, max chars=33 The free_quantity_in_decimal as set for the item price. Returned for quantity-based item prices when multi-decimal pricing is enabled.
optional, integer, min=1, max=730 The service period of the item in days from the day of charge.
optional, string, max chars=100 This field represents the number of quantities recorded against this subscription item in the current term optional, list of coupons_to_add Details about the coupons added to the subscription through this ramp.
Coupons to add attributes
string, max chars=100 Unique ID of the coupon to be added.
optional, timestamp(UTC) in seconds The date till when the coupon can be applied. Applicable for limited_period coupons only. optional, list of discounts_to_add Details about the discounts added to the subscription through this ramp.
Discounts to add attributes
string, max chars=50 An immutable unique id for the discount. It is always auto-generated.
optional, string, max chars=100 The name of the discount as it should appear on customer-facing pages and documents such as invoices and hosted pages. This is auto-generated based on the type, amount, and currency_code of the discount. For example, it can be 10% off or 10$ off.
enumerated string, default=percentage The type of discount.
Possible value are: Possible values are
fixed_amountThe specified amount will be given as discount.percentageThe specified percentage will be given as discount.
Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
enumerated string, default=forever Specifies the time duration for which this discount is attached to the subscription. Possible values are
one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit. Show all values[+]
optional, integer, min=1 The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_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[+]
boolean The discount is included in MRR calculations for your site. This attribute is only applicable when duration_type is one_time and when the feature is enabled in Chargebee. Also, If the site-level setting is to exclude one-time discounts from MRR calculations, this value is always returned false.
enumerated string The amount on the invoice to which the discount is applied. Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
Show all values[+]
optional, string, max chars=100 The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
timestamp(UTC) in seconds Timestamp indicating when this discount is created. optional, list of item_tier Note Allowed only when both of these conditions are met:
- Price overriding is enabled for the site.
pricing_model of the item price is either tiered, volume, or stairstep.
Overrides the item_tiers for specific item_prices of the subscription.
string, max chars=100 The id of the item price to which this tier belongs.
integer, min=1 The lowest value in the quantity tier.
optional, integer The highest value in the quantity 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, string, max chars=33 The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
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.
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 item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
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, status_transition_reason Detailed reason for the status transition of a ramp to draft and failed status.
Status transition reason attributes
optional, string, max chars=100 Unique code of the status_transition_reason.
optional, string, max chars=250 A message to explain the status_transition_reason.
This is a list of the event types we currently support. We will continue
to add more events moving forward. All events follow a uniform pattern -
<resource>_<event_name>. The resources that will be
present in the event content are provided beneath each event type's
description.
Note: If consolidated invoicing is enabled, the
attributes invoice.subscription_id and
credit_note.subscription_id should not be used
(as it will not be present if the invoice / credit note has lines from
multiple subscriptions). Instead to know the related subscriptions,
their line_items' subscription_id attribute should be referred.
string, max chars=50 A unique and immutable identifier for the ramp.
optional, string, max chars=250 A brief summary of the pricing changes applied with this ramp.
string, max chars=50 The ID of the subscription for which this ramp was created.
timestamp(UTC) in seconds Specifies the time when the changes to the subscription will be applied by executing the ramp.
enumerated string The execution status of the ramp Possible values are
scheduledThe ramp has been created and scheduled for execution. Note Excluding deleted ramps, a subscription can have a maximum of 12 ramps in the scheduled status.
succeededThe ramp completed successfully.failedThe ramp did not complete because of an error.draftThe ramp is moved to draft status when the associated subscription is updated. The reason for the draft status can be explained in the status_transition_reason Note Ramps in draft state will not be executed.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this resource was created.
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.
optional, timestamp(UTC) in seconds Timestamp indicating when this resource was last updated.
optional, list of string List of item prices removed from the subscription through this ramp.
optional, list of string List of coupons removed from the subscription through this ramp.
optional, list of string List of discounts removed from the subscription through this ramp.
optional, list of items_to_add Details about the item prices added to the subscription through this ramp.
optional, list of items_to_update Details about the item prices updated in the subscription through this ramp.
optional, list of coupons_to_add Details about the coupons added to the subscription through this ramp.
optional, list of discounts_to_add Details about the discounts added to the subscription through this ramp.
optional, list of item_tier Note Allowed only when both of these conditions are met:
- Price overriding is enabled for the site.
pricing_model of the item price is either tiered, volume, or stairstep.
Overrides the item_tiers for specific item_prices of the subscription.
optional, status_transition_reason Detailed reason for the status transition of a ramp to draft and failed status. Creates a ramp for a subscription.
Note - Subscription status: You cannot create ramps for subscriptions in the
paused or cancelled status. - Advance invoice: You cannot create ramps for subscriptions that have an advance invoice schedule.
- Upcoming ramps limit: A subscription can have a maximum of 12 upcoming ramps at any given time, excluding deleted ramps. Upcoming ramps are ramps with
status as scheduled. - Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
- You cannot create a ramp for subscription, when ramps are in draft status.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"ramp": {
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Schedule for first ramp",
"created_at": "1635054328",
"deleted": false,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly",
{..}
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
},
{..}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
},
{..}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
},
{..}
]
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/create_ramp
required, timestamp(UTC) in seconds The time when this ramp takes effect. Caution - Ensure the time is within five years from the current time.
- Ensure there is a minimum 24-hour interval between
effective_from of two consecutive ramps. - If the subscription is scheduled to be paused or canceled in the future, ensure the time is not on or after
pause_date or cancelled_at.
optional, string, max chars=250 A brief summary of the pricing changes applied with this ramp. coupons_to_remove[[0..n]][0..n]
optional, list of string List of coupons removed from the subscription through this ramp. Caution Ensure this list does not include:
- Coupons being added through this ramp.
- Coupons already removed by a previous ramp.
discounts_to_remove[[0..n]][0..n]
optional, list of string List of discounts removed from the subscription through this ramp. Caution Ensure this list does not include discounts already removed by a previous ramp.
items_to_remove[[0..n]][0..n]
optional, list of string List of item prices removed from the subscription through this ramp. Caution Ensure this list does not include:
- Item prices being added or updated through this ramp.
- Item prices already removed by a previous ramp.
items_to_add[[0..n]][0..n]
optional, array Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices. items_to_update[[0..n]][0..n]
optional, array Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
optional, array Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices. coupons_to_add[[0..n]][0..n]
optional, array Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices. discounts_to_add[[0..n]][0..n]
optional, array Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices.
pass parameters as items_to_add[<param name>][<idx:0..n>]
items_to_add[item_price_id][0..n] required, string, max chars=100 items_to_add[quantity][0..n] items_to_add[quantity_in_decimal][0..n] optional, string, max chars=33 items_to_add[unit_price][0..n] optional, in cents, min=0 items_to_add[unit_price_in_decimal][0..n] optional, string, max chars=39 items_to_add[billing_cycles][0..n] items_to_add[service_period_days][0..n] optional, integer, min=1, max=730
Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
pass parameters as items_to_update[<param name>][<idx:0..n>]
items_to_update[item_price_id][0..n] required, string, max chars=100 items_to_update[quantity][0..n] items_to_update[quantity_in_decimal][0..n] optional, string, max chars=33 items_to_update[unit_price][0..n] optional, in cents, min=0 items_to_update[unit_price_in_decimal][0..n] optional, string, max chars=39 items_to_update[billing_cycles][0..n] items_to_update[service_period_days][0..n] optional, integer, min=1, max=730
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n] optional, string, max chars=100 item_tiers[starting_unit][0..n] item_tiers[ending_unit][0..n] optional, in cents, default=0, min=0 item_tiers[starting_unit_in_decimal][0..n] optional, string, max chars=33 item_tiers[ending_unit_in_decimal][0..n] optional, string, max chars=33 item_tiers[price_in_decimal][0..n] optional, string, max chars=39 item_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[+] item_tiers[package_size][0..n]
Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices.
pass parameters as coupons_to_add[<param name>][<idx:0..n>]
coupons_to_add[coupon_id][0..n] optional, string, max chars=100 coupons_to_add[apply_till][0..n] optional, timestamp(UTC) in seconds
Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
pass parameters as discounts_to_add[<param name>][<idx:0..n>]
discounts_to_add[apply_on][0..n] required, enumerated string Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
Show all values[+] discounts_to_add[duration_type][0..n] required, enumerated string, default=forever Possible values are
one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit. Show all values[+] discounts_to_add[percentage][0..n] optional, double, min=0.01, max=100.0 discounts_to_add[amount][0..n] optional, in cents, min=0 discounts_to_add[period][0..n] discounts_to_add[period_unit][0..n] optional, 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[+] discounts_to_add[included_in_mrr][0..n] discounts_to_add[item_price_id][0..n] optional, string, max chars=100
always returned required
Resource object representing ramp
Sample admin console URL
https://{site}.chargebee.com/admin-console/ramps/123x
Updates an existing subscription ramp by replacing its current attribute values with the new parameters provided. When using this API to modify a ramp, make sure to include all the ramp's attributes as you would do during creation of the ramp with the necessary values updated.
Example: step-by-step flow
The following steps explains how to update effective_from value of an existing ramp.
Step 1: Retrieve current ramp values
- Send a request to retrieve the current values of all parameters for the subscription ramp using Retrieve a subscription ramp API.
- Review the response to get the current values of the ramp's attributes. Note down all the parameters and their values.
Step 2: Update ramp with new values
- Prepare the request to update the ramp.
- Update the effective_from value in the noted down attributes of ramp from the previous step.
- Ensure all parameters, even those not being changed, are included in the request.
- Send the prepared request to Update subscription ramp API.
- Verify the response object to ensure a successful subscription ramp update. If it returns an error, repeat step 1 again.
Note - Ramp status: You cannot update a ramp in
succeeded or failed status. - Advance invoice: You cannot update ramps for subscriptions that have an advance invoice schedule.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"ramp": {
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Updated description for first ramp",
"created_at": "1635054328",
"deleted": false,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly",
{..}
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
},
{..}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
},
{..}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
},
{..}
]
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/ramps/{ramp-id}/update
required, timestamp(UTC) in seconds The time when this ramp takes effect. Caution - Ensure the time is within five years from the current time.
- Ensure there is a minimum 24-hour interval between
effective_from of two consecutive ramps. - If the subscription is scheduled to be paused or canceled in the future, ensure the time is not on or after
pause_date or cancelled_at.
optional, string, max chars=250 A brief summary of the pricing changes applied with this ramp. coupons_to_remove[[0..n]][0..n]
optional, list of string List of coupons removed from the subscription through this ramp. Caution Ensure this list does not include:
- Coupons being added through this ramp.
- Coupons already removed by a previous ramp.
discounts_to_remove[[0..n]][0..n]
optional, list of string List of discounts removed from the subscription through this ramp. Caution Ensure this list does not include discounts already removed by a previous ramp.
items_to_remove[[0..n]][0..n]
optional, list of string List of item prices removed from the subscription through this ramp. Caution Ensure this list does not include:
- Item prices being added or updated through this ramp.
- Item prices already removed by a previous ramp.
items_to_add[[0..n]][0..n]
optional, array Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices. items_to_update[[0..n]][0..n]
optional, array Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
optional, array Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices. coupons_to_add[[0..n]][0..n]
optional, array Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices. discounts_to_add[[0..n]][0..n]
optional, array Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices.
pass parameters as items_to_add[<param name>][<idx:0..n>]
items_to_add[item_price_id][0..n] required, string, max chars=100 items_to_add[quantity][0..n] items_to_add[quantity_in_decimal][0..n] optional, string, max chars=33 items_to_add[unit_price][0..n] optional, in cents, min=0 items_to_add[unit_price_in_decimal][0..n] optional, string, max chars=39 items_to_add[billing_cycles][0..n] items_to_add[service_period_days][0..n] optional, integer, min=1, max=730
Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
pass parameters as items_to_update[<param name>][<idx:0..n>]
items_to_update[item_price_id][0..n] required, string, max chars=100 items_to_update[quantity][0..n] items_to_update[quantity_in_decimal][0..n] optional, string, max chars=33 items_to_update[unit_price][0..n] optional, in cents, min=0 items_to_update[unit_price_in_decimal][0..n] optional, string, max chars=39 items_to_update[billing_cycles][0..n] items_to_update[service_period_days][0..n] optional, integer, min=1, max=730
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n] optional, string, max chars=100 item_tiers[starting_unit][0..n] item_tiers[ending_unit][0..n] optional, in cents, default=0, min=0 item_tiers[starting_unit_in_decimal][0..n] optional, string, max chars=33 item_tiers[ending_unit_in_decimal][0..n] optional, string, max chars=33 item_tiers[price_in_decimal][0..n] optional, string, max chars=39 item_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[+] item_tiers[package_size][0..n]
Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices.
pass parameters as coupons_to_add[<param name>][<idx:0..n>]
coupons_to_add[coupon_id][0..n] optional, string, max chars=100 coupons_to_add[apply_till][0..n] optional, timestamp(UTC) in seconds
Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
pass parameters as discounts_to_add[<param name>][<idx:0..n>]
discounts_to_add[apply_on][0..n] required, enumerated string Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
Show all values[+] discounts_to_add[duration_type][0..n] required, enumerated string, default=forever Possible values are
one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit. Show all values[+] discounts_to_add[percentage][0..n] optional, double, min=0.01, max=100.0 discounts_to_add[amount][0..n] optional, in cents, min=0 discounts_to_add[period][0..n] discounts_to_add[period_unit][0..n] optional, 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[+] discounts_to_add[included_in_mrr][0..n] discounts_to_add[item_price_id][0..n] optional, string, max chars=100
always returned required
Resource object representing ramp
Sample admin console URL
https://{site}.chargebee.com/admin-console/ramps/123x
Retrieves a specific subscription ramp.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"ramp": {
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Schedule for first ramp",
"created_at": "1635054328",
"deleted": false,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly",
{..}
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
},
{..}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
},
{..}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
},
{..}
]
}
}
URL Format
GET
https://{site}.chargebee.com/api/v2/ramps/{ramp-id}
always returned required
Resource object representing ramp
Sample admin console URL
https://{site}.chargebee.com/admin-console/ramps/123x
Deletes the specified subscription ramp. However, Chargebee only allows deleting a ramp if it does not conflict with future ramps on the subscription. The following checks are performed to ensure compatibility:
| Condition | Restriction |
The ramp contains items_to_add[] | The ramp cannot be deleted if any of the items in items_to_add[] are scheduled to be updated or removed in a subsequent ramp. |
The ramp contains coupons_to_add[] | The ramp cannot be deleted if any of the coupons in coupons_to_add[] are scheduled to be removed in a subsequent ramp. |
The ramp contains discounts_to_add[] | The ramp cannot be deleted if any of the discounts in discounts_to_add[] are scheduled to be removed in a subsequent ramp. |
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"ramp": {
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Schedule for first ramp",
"created_at": "1635054328",
"deleted": true,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly",
{..}
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
},
{..}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
},
{..}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
},
{..}
]
}
}
URL Format
POST
https://{site}.chargebee.com/api/v2/ramps/{ramp-id}/delete
always returned required
Resource object representing ramp
Sample admin console URL
https://{site}.chargebee.com/admin-console/ramps/123x
Lists the subscription ramps that match the criteria provided in the filter parameters.
Note By default, the ramps are returned sorted in descending order (latest first) by updated_at.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Response [ JSON ]
Show more...
{
"list": [
{
"ramp": {
"id": "__test__rHsiT4rY2hC1A",
"effective_from": "1635054328",
"subscription_id": "__test__8asukSOXdv6kOj",
"status": "scheduled",
"description": "Schedule for first ramp",
"created_at": "1635054328",
"deleted": false,
"updated_at": "1635054328",
"items_to_remove": [
"basicAddon1-USD-Monthly",
{..}
],
"items_to_add": [
{
"item_price_id": "basicAddon2-USD-Monthly",
"quantity": 2
},
{..}
],
"discounts_to_add": [
{
"duration_type": "one_time",
"apply_on": "invoice_amount",
"percentage": 5
},
{..}
],
"items_to_update": [
{
"item_price_id": "basicPlan-USD-Monthly",
"unit_price": 20000
},
{..}
]
}
},
{..}
]
}
URL Format
GET
https://{site}.chargebee.com/api/v2/ramps
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.
optional, boolean, default=false If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, string filter
Sorts based on the specified attribute.
Supported attributes : effective_from, updated_at
Supported sort-orders : asc, desc
Example → sort_by[asc] = "effective_from"
This will sort the result based on the 'effective_from'
attribute in ascending(earliest first) order.
optional, enumerated string filter Filter subscription ramps based on status. Caution - The
subscription_id filter must be passed when filtering by status. status filter should not be passed when include_deleted is set to true.
Possible values are : scheduled, succeeded, failed, draft Supported operators : is, in
Example → status[is] = "SCHEDULED" Filter subscription ramps based on status. Caution - The
subscription_id filter must be passed when filtering by status. status filter should not be passed when include_deleted is set to true.
pass parameters as status[<param name>][<operator>] optional, enumerated string filter
Possible values are : scheduled, succeeded, failed, draft
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
subscription_id[<operator>] subscription_id[<operator>] required, string filter Filter subscription ramps based on subscription_id. Caution This filter is mandatory when filtering by status or effective_from.
Possible values are : Supported operators : is, in
Example → subscription_id[is] = "8gsnbYfsMLds" Filter subscription ramps based on subscription_id. Caution This filter is mandatory when filtering by status or effective_from.
pass parameters as subscription_id[<param name>][<operator>] subscription_id[is][operator] subscription_id[is][operator] optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
subscription_id[in][operator] subscription_id[in][operator] optional, string filter
Possible values are :
Supported operators :
Example →
effective_from[<operator>] effective_from[<operator>] optional, timestamp(UTC) in seconds filter Filter subscription ramps based on effective_from. Caution - The
subscription_id filter must be passed when filtering by effective_from. effective_from filter should not be passed when include_deleted is set to true.
Possible values are : Supported operators : after, before, on, between
Example → effective_from[after] = "1435054328" Filter subscription ramps based on effective_from. Caution - The
subscription_id filter must be passed when filtering by effective_from. effective_from filter should not be passed when include_deleted is set to true.
pass parameters as effective_from[<param name>][<operator>] effective_from[after][operator] effective_from[after][operator] optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
effective_from[before][operator] effective_from[before][operator] optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
effective_from[on][operator] effective_from[on][operator] optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
effective_from[between][operator] effective_from[between][operator] optional, string filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter Filter subscription ramps based on updated_at. Tip Specify sort_by = updated_at (whether asc oor desc) for a faster response when using this filter.
Possible values are : Supported operators : after, before, on, between
Example → updated_at[after] = "1435052328" Filter subscription ramps based on updated_at. Tip Specify sort_by = updated_at (whether asc oor desc) for a faster response when using this filter.
pass parameters as updated_at[<param name>][<operator>] updated_at[after][operator] updated_at[after][operator] optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
updated_at[before][operator] updated_at[before][operator] optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
updated_at[between][operator] updated_at[between][operator] optional, string filter
Possible values are :
Supported operators :
Example →
always returned required
Resource object representing ramp
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/ramps/123x
Settings
Configure SDK
