Settings
Configure SDK
Ramps
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
statusasscheduled. - 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_atparameter 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
Indicates if the ramp is marked as deleted. To retrieve deleted ramps, use the List subscription ramps
endpoint with include_deleted
set to true
.
Details about the item prices added to the subscription through this ramp.
Details about the item prices updated in the subscription through this ramp.
Details about the coupons added to the subscription through this ramp.
Details about the discounts added to the subscription through this ramp.
Note Allowed only when both of these conditions are met:
- Price overriding is enabled for the site.
pricing_modelof the item price is eithertiered,volume, orstairstep.
Overrides the item_tiers for specific item_prices of the subscription.
An object that specifies the contract term details.
Creates a ramp for a subscription.
Note
- Subscription status: You cannot create ramps for subscriptions in the
pausedorcancelledstatus. - 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
statusasscheduled. - 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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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_fromof 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_dateorcancelled_at.
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.
List of discounts removed from the subscription through this ramp.
Caution Ensure this list does not include discounts already removed by a previous ramp.
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.
pass parameters as items_to_add[<param name>][<idx:0..n>]
pass parameters as items_to_update[<param name>][<idx:0..n>]
pass parameters as item_tiers[<param name>][<idx:0..n>]
pass parameters as discounts_to_add[<param name>][<idx:0..n>]
Returns
Resource object representing ramp
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
succeededorfailedstatus. - Advance invoice: You cannot update ramps for subscriptions that have an advance invoice schedule.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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_fromof 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_dateorcancelled_at.
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.
List of discounts removed from the subscription through this ramp.
Caution Ensure this list does not include discounts already removed by a previous ramp.
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.
pass parameters as items_to_add[<param name>][<idx:0..n>]
pass parameters as items_to_update[<param name>][<idx:0..n>]
pass parameters as item_tiers[<param name>][<idx:0..n>]
pass parameters as discounts_to_add[<param name>][<idx:0..n>]
Returns
Resource object representing ramp
Retrieve a subscription ramp ¶
Retrieves a specific subscription ramp.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing ramp
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. |
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing ramp
List subscription ramps ¶
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.
Sample Response [ JSON ]
URL Format GET
Input Parameters
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.
Filter Params
For operator usages, see the Pagination and Filtering section.
Filter subscription ramps based on subscription_id
.
Caution
This filter is mandatory when filtering by status or effective_from.
Supported operators : is, in
Example → subscription_id[is] = "8gsnbYfsMLds"
Supported operators : in, is
Example → subscription_id[in] = "8gsnbYfsMLds"
Filter subscription ramps based on effective_from.
Caution
- The
subscription_idfilter must be passed when filtering byeffective_from. effective_fromfilter should not be passed wheninclude_deletedis set totrue.
Supported operators : after, before, on, between
Example → effective_from[after] = "1435054328"
Supported operators : after, before, on, between
Example → effective_from[after] = "1435054328"
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.
Supported operators : after, before, on, between
Example → updated_at[after] = "1435052328"
Supported operators : after, before, on, between
Example → updated_at[after] = "1435052328"
Returns
Resource object representing ramp
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`.