POST /ramps/{ramp-id}/update

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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`ramp-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`items_to_remove[]`	Array	No	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.
`coupons_to_add`	Object	No	Details about the added to the subscription through this ramp.
`coupons_to_add.coupon_id[]`	Array	No	Unique ID of the coupon to be added. Caution Ensure this list does not include coupons being removed through this ramp. Coupon codes are not supported.
`coupons_to_add.apply_till[]`	Array	No	The date till when the coupon can be applied. Applicable for `limited_period` coupons only.
`description`	String	No	A brief summary of the pricing changes applied with this ramp.
`discounts_to_remove[]`	Array	No	List of removed from the subscription through this ramp. Caution Ensure this list does not include discounts already removed by a previous ramp.
`item_tiers`	Object	No	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. Replaces the existing item_tiers for specific `item_price`s within the subscription. You must provide the complete tier set for any `item_price`, even if you’re changing the price for only one tier.
`item_tiers.starting_unit_in_decimal[]`	Array	No	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.
`item_tiers.price_in_decimal[]`	Array	No	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.
`item_tiers.package_size[]`	Array	No	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.
`item_tiers.price[]`	Array	No	The overridden price of the tier. The value depends on the type of currency.
`item_tiers.ending_unit[]`	Array	No	The highest value in the quantity tier.
`item_tiers.item_price_id[]`	Array	No	The identifier of the `item_price` for which the tier price is being overridden. Caution The identifier must correspond to an `item_price` listed in either `items_to_add` or `items_to_update`.
`item_tiers.pricing_type[]`	Array	No
`item_tiers.starting_unit[]`	Array	No	The lowest value in the quantity tier.
`item_tiers.ending_unit_in_decimal[]`	Array	No	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.
`items_to_update`	Object	No	Details about the [item prices](item_prices) updated in the subscription through this ramp.
`items_to_update.charge_on_event[]`	Array	No
`items_to_update.unit_price[]`	Array	No	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.
`items_to_update.charge_once[]`	Array	No	Indicates if the charge-item is to be charged only once or each time the `charge_on_event` occurs. This parameter only applies to charge-items.
`items_to_update.charge_on_option[]`	Array	No
`items_to_update.unit_price_in_decimal[]`	Array	No	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.
`items_to_update.item_price_id[]`	Array	Yes	The unique identifier of the item price. Caution Ensure this list: Does not include any item price added or removed through this ramp. Does not include any item price removed by a previous ramp. Includes only item prices currently in the subscription or added by a previous ramp.
`items_to_update.quantity[]`	Array	No	The quantity of the item purchased
`items_to_update.quantity_in_decimal[]`	Array	No	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.
`items_to_update.service_period_days[]`	Array	No	The service period of the item in days from the day of charge.
`items_to_update.billing_cycles[]`	Array	No	For the plan-item price: the value determines the number of billing cycles the subscription runs before canceling automatically. If not provided, then the value set for the plan-item price is used.For addon-item prices: If addon billing cycles are enabled then this is the number of subscription billing cycles for which the addon is included. If not provided, then the value set under attached addons is used. Further, if that value is not provided, then the value set for the addon-item price is used.
`effective_from`	Integer	Yes	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`.
`coupons_to_remove[]`	Array	No	List of 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_add`	Object	No	Details about the [discounts](/docs/api/discounts?prod_cat_ver=2) added to the subscription through this ramp.
`discounts_to_add.apply_on[]`	Array	Yes
`discounts_to_add.included_in_mrr[]`	Array	No	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`.
`discounts_to_add.period_unit[]`	Array	No
`discounts_to_add.percentage[]`	Array	No	The percentage of the original amount that should be deducted from it.
`discounts_to_add.period[]`	Array	No	The duration of time for which the discount is attached to the subscription, in `period_units`. Applicable only when `duration_type` is `limited_period`.
`discounts_to_add.amount[]`	Array	No	The value of the discount. The format of this value depends on the kind of currency.
`discounts_to_add.duration_type[]`	Array	Yes
`discounts_to_add.item_price_id[]`	Array	No	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`.
`contract_term`	Object	No	An object that specifies the contract term details.
`contract_term.renewal_billing_cycles`	Integer	No	Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as `billing_cycles` or a custom value depending on the site configuration .
`contract_term.action_at_term_end`	String	No	Action to be taken when the contract term completes. evergreen - Contract term completes and the subscription renews. renew - Used when you want to renew the contract term. Does the following: Contract term completes and a new contract term is started for the number of billing cycles specified in `renewal_billing_cycles`. The `action_at_term_end` for the new contract term is set to `renew`. renew_once - Used when you want to renew the contract term just once. Does the following: Contract term completes and a new contract term is started for the number of billing cycles specified in `renewal_billing_cycles`. The `action_at_term_end` for the new contract term is set to `cancel`. cancel - Contract term completes and subscription is canceled. Valid values: `"renew_once"` `"evergreen"` `"cancel"` `"renew"` Default value: "renew"
`contract_term.cancellation_cutoff_period`	Integer	No	The number of days before `contract_end`, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
`items_to_add`	Object	No	Details about the [item prices](/docs/api/item_prices?prod_cat_ver=2) added to the subscription through this ramp.
`items_to_add.charge_on_event[]`	Array	No
`items_to_add.unit_price[]`	Array	No	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.
`items_to_add.charge_once[]`	Array	No	Indicates if the charge-item is to be charged only once or each time the `charge_on_event` occurs. This parameter only applies to charge-items.
`items_to_add.charge_on_option[]`	Array	No
`items_to_add.unit_price_in_decimal[]`	Array	No	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.
`items_to_add.item_price_id[]`	Array	Yes	The unique identifier of the item price. Caution Ensure this list does not include: Item prices updated or removed through this ramp. Item prices already in the subscription or added by a previous ramp. The ramp should not change the billing period of the subscription if an upcoming ramp already exists after `effective_from` time.
`items_to_add.quantity[]`	Array	No	The quantity of the item purchased
`items_to_add.quantity_in_decimal[]`	Array	No	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.
`items_to_add.service_period_days[]`	Array	No	The service period of the item in days from the day of charge.
`items_to_add.billing_cycles[]`	Array	No	For the plan-item price: the value determines the number of billing cycles the subscription runs before canceling automatically. If not provided, then the value set for the plan-item price is used.For addon-item prices: If addon billing cycles are enabled then this is the number of subscription billing cycles for which the addon is included. If not provided, then the value set under attached addons is used. Further, if that value is not provided, then the value set for the addon-item price is used.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.