# Ramps > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). A `ramp` resource, or subscription ramp, represents a planned change to a [`subscription`](/docs/api/subscriptions) that occurs at a future date. Use this resource to define and schedule subscription modifications, such as updating pricing, altering 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`](/docs/api/ramps/ramp-object#status). - **Total ramps limit**: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps. #### Auto-draft conditions[](#auto-draft-conditions) When you create or update a ramp, Chargebee automatically moves any existing ramps scheduled after that ramp to `draft` status if either of the following conditions is met: - The new or updated ramp changes the subscription [term end date](subscriptions#subscription_current_term_end). - The new or updated ramp changes the subscription billing frequency. That is, either of the following [attributes](subscriptions#subscription_items) is changed: - `subscription_items[i].billing_period` - `subscription_items[i].billing_period_unit` - where `i` is the index where `subscription_items[i].item_type` is `plan`. - The new or updated ramp introduces an [addon](item_prices#item_price_item_type) that is not [applicable](attached_items) to the plan in one or more of the subsequent ramps. ## Sample Ramp ```json { "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 }, {..} ] } ``` ## Ramps attributes ## Input Parameters - `id` (required, string, max chars=50) A unique and immutable identifier for the ramp. - `description` (optional, string, max chars=250) A brief summary of the pricing changes applied with this ramp. - `subscription_id` (required, string, max chars=50) The ID of the subscription for which this ramp was created. - `effective_from` (required, timestamp(UTC) in seconds) Specifies the time when the changes to the subscription will be applied by executing the ramp. - `status` (required, enumerated string) The execution status of the ramp Possible enum values: - `scheduled` The 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`. - `succeeded` The ramp completed successfully. - `failed` The ramp did not complete because of an error. - `draft` The 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](/docs/api/ramps/ramp-object#status_transition_reason) **Note** Ramps in draft state will not be executed. - `created_at` (required, timestamp(UTC) in seconds) Timestamp indicating when this resource was created. - `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. - `updated_at` (optional, timestamp(UTC) in seconds) Timestamp indicating when this resource was last updated. - `items_to_remove` (optional, string, max chars=100) List of [item prices](/docs/api/item_prices) removed from the subscription through this ramp. - `coupons_to_remove` (optional, string, max chars=100) List of [coupons](/docs/api/coupons) removed from the subscription through this ramp. - `discounts_to_remove` (optional, string, max chars=100) List of [discounts](/docs/api/discounts) removed from the subscription through this ramp. - `deleted` (required, boolean) Indicates if the ramp is marked as deleted. To retrieve deleted ramps, use the [List subscription ramps](/docs/api/ramps/list-ramps) endpoint with `[include_deleted](/docs/api/ramps/list-ramps)` set to `true` . - `items_to_add` (optional, list of items_to_add) Details about the [item prices](/docs/api/item_prices) added to the subscription through this ramp. - `item_price_id` (required, string, max chars=100) The unique identifier of the item price. - `item_type` (required, enumerated string) The type of item. There must be one and only one item of type `plan` in this list. Possible enum values: - `plan` Plan - `addon` Addon - `charge` Charge - `quantity` (optional, integer, min=1) The quantity of the item purchased - `quantity_in_decimal` (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](/docs/api/currencies) is enabled. - `unit_price` (optional, in cents, min=0) The price/per unit price of the item. When not provided, [the value set](/docs/api/item_prices/item-price-object) 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](https://www.chargebee.com/docs/price-override.html) is enabled for the site. The value depends on the [type of currency](/docs/api/currencies) . - `unit_price_in_decimal` (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](/docs/api/currencies) is enabled. - `amount` (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](/docs/api/currencies) . - `amount_in_decimal` (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](/docs/api/currencies) is enabled. - `free_quantity` (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](/docs/api/item_prices/item_price-object#free_quantity)` . - `free_quantity_in_decimal` (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](/docs/api/currencies) is enabled. - `billing_cycles` (optional, integer, min=0) 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](/docs/api/item_prices/item-price-object) for the plan-item price is used. For addon-item prices: If [addon billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html) 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](/docs/api/attached_items/attached-item-object) is used. Further, if that value is not provided, then [the value set for the addon-item price](/docs/api/item_prices/item-price-object) is used. - `service_period_days` (optional, integer, min=1, max=730) The service period of the item in days from the day of charge. - `metered_quantity` (optional, string, max chars=100) This field represents the number of quantities recorded against this subscription item in the current term - `charge_once` (optional, boolean) 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. - `charge_on_option` (optional, enumerated string) Indicates when the charge-item is to be charged. This parameter only applies to charge-items. Possible enum values: - `immediately` The item is charged immediately on being added to the subscription. - `on_event` The item is charged at the occurrence of the event specified as `charge_on_event` . - `charge_on_event` (optional, enumerated string) When `charge_on_option` option is set to `on_event` , this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items. Possible enum values: - `subscription_trial_start` the time when the trial period of the subscription begins. - `plan_activation` same as subscription activation, but also includes the case when the plan-item of the subscription is changed. - `subscription_activation` the moment a subscription enters an `active` or `non-renewing` state. Also includes reactivations of canceled subscriptions. - `contract_termination` when a contract term is [terminated](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option) . - `items_to_update` (optional, list of items_to_update) Details about the [item prices](/docs/api/item_prices) updated in the subscription through this ramp. - `item_price_id` (required, string, max chars=100) The unique identifier of the item price. - `item_type` (required, enumerated string) The type of item. There must be one and only one item of type `plan` in this list. Possible enum values: - `plan` Plan - `addon` Addon - `charge` Charge - `quantity` (optional, integer, min=1) The quantity of the item purchased - `quantity_in_decimal` (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](/docs/api/getting-started) is enabled. - `unit_price` (optional, in cents, min=0) The price/per unit price of the item. When not provided, [the value set](/docs/api/item_prices/item-price-object) 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](https://www.chargebee.com/docs/price-override.html) is enabled for the site. The value depends on the [type of currency](/docs/api/currencies) . - `unit_price_in_decimal` (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](/docs/api/getting-started) is enabled. - `amount` (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](/docs/api/currencies) . - `amount_in_decimal` (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](/docs/api/getting-started) is enabled. - `free_quantity` (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](/docs/api/item_prices/item_price-object#free_quantity)` .. - `free_quantity_in_decimal` (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](/docs/api/getting-started) is enabled. - `billing_cycles` (optional, integer, min=0) 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](/docs/api/item_prices/item-price-object) for the plan-item price is used. For addon-item prices: If [addon billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html) 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](/docs/api/attached_items/attached-item-object) is used. Further, if that value is not provided, then [the value set for the addon-item price](/docs/api/item_prices/item-price-object) is used. - `service_period_days` (optional, integer, min=1, max=730) The service period of the item in days from the day of charge. - `metered_quantity` (optional, string, max chars=100) This field represents the number of quantities recorded against this subscription item in the current term - `charge_once` (optional, boolean) 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. - `charge_on_option` (optional, enumerated string) Indicates when the charge-item is to be charged. This parameter only applies to charge-items. Possible enum values: - `immediately` The item is charged immediately on being added to the subscription. - `on_event` The item is charged at the occurrence of the event specified as `charge_on_event` . - `charge_on_event` (optional, enumerated string) When `charge_on_option` option is set to `on_event` , this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items. Possible enum values: - `subscription_trial_start` the time when the trial period of the subscription begins. - `plan_activation` same as subscription activation, but also includes the case when the plan-item of the subscription is changed. - `subscription_activation` the moment a subscription enters an `active` or `non-renewing` state. Also includes reactivations of canceled subscriptions. - `contract_termination` when a contract term is [terminated](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option) . - `coupons_to_add` (optional, list of coupons_to_add) Details about the [coupons](/docs/api/coupons) added to the subscription through this ramp. - `coupon_id` (required, string, max chars=100) Unique ID of the coupon to be added. - `apply_till` (optional, timestamp(UTC) in seconds) The date till when the coupon can be applied. Applicable for `limited_period` [coupons](/docs/api/coupons) only. - `discounts_to_add` (optional, list of discounts_to_add) Details about the [discounts](/docs/api/discounts) added to the subscription through this ramp. - `id` (required, string, max chars=50) An immutable unique id for the discount. It is always auto-generated. - `invoice_name` (optional, string, max chars=100) The name of the discount as it should appear on customer-facing pages and documents such as [invoices](/docs/api/invoices) and [hosted pages](/docs/api/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` . - `type` (required, enumerated string, default=percentage) The type of discount. Possible value are: Possible enum values: - `fixed_amount` The specified amount will be given as discount. - `percentage` The specified percentage will be given as discount. - `offer_quantity` A specified number of units of the item price are offered for free. The number of free units is specified in `discounts_to_add.quantity`. **Constraints** - `discounts_to_add.apply_on` must be `specific_item_price`. - `discounts_to_add.item_price_id` must belong to an item price with [`pricing_model`](/docs/api/item_prices#pricing_model) `per_unit`. - `percentage` (optional, double, min=0.01, max=100) The percentage of the original amount that should be deducted from it. Only applicable when `discount.type` is percentage. - `amount` (optional, in cents, min=0) The value of the discount. [The format of this value](/docs/api/currencies) depends on the kind of currency. - `quantity` (optional, integer, min=1) Specifies the number of free units provided for the item, without affecting the total quantity sold. **Constraints** - `discounts_to_add.type` must be `offer_quantity`. - `discounts_to_add.apply_on` must be `specific_item_price`. - `discounts_to_add.item_price_id` must belong to an item price with [`pricing_model`](/docs/api/item_prices#pricing_model) `per_unit`. - `duration_type` (required, enumerated string, default=forever) Specifies the time duration for which this discount is attached to the subscription. Possible enum values: - `one_time` The discount stays attached to the subscription till it is applied on an invoice **once**. It is removed after that from the subscription. - `forever` The discount is attached to the subscription and applied on the invoices till it is [explicitly removed](/docs/api/subscriptions/update-subscription-for-items#discounts_operation_type) . - `limited_period` The 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` . - `period` (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`. - `period_unit` (optional, enumerated string) The unit of time for `period`. Applicable only when `duration_type` is `limited_period`. Possible enum values: - `day` A period of 24 hours. - `week` A period of 7 days. - `month` A period of 1 calendar month. - `year` A period of 1 calendar year. - `included_in_mrr` (required, 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](https://www.chargebee.com/docs/reporting.html#dashboards_flexible-mrr-calculation) in Chargebee. Also, If the [site-level setting](https://www.chargebee.com/docs/reporting.html#chart_flexible-mrr-calculation) is to exclude one-time discounts from MRR calculations, this value is always returned `false`. - `apply_on` (required, enumerated string) The amount on the invoice to which the discount is applied. Possible enum values: - `invoice_amount` The discount is applied to the invoice `sub_total` . - `specific_item_price` The discount is applied to the `invoice.line_item.amount` that corresponds to the item price specified by `item_price_id` . - `item_price_id` (optional, string, max chars=100) The [id of the item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) in the subscription to which the discount is to be applied. Relevant only when `apply_on` = `specific_item_price`. - `created_at` (required, timestamp(UTC) in seconds) Timestamp indicating when this discount is created. - `item_tiers` (optional, list of item_tier) **Note** Allowed only when both of these conditions are met: - [Price overriding](https://www.chargebee.com/docs/2.0/price-override.html) is enabled for the site. - `pricing_model` of the item price is either `tiered`, `volume`, or `stairstep`. Overrides the `[item_tiers](/docs/api/subscriptions/subscription-object#item_tiers)` for specific `item_prices` of the subscription. - `item_price_id` (required, string, max chars=100) The id of the item price to which this tier belongs. - `starting_unit` (required, integer, min=1) The lowest value in the quantity tier. - `ending_unit` (optional, integer) The highest value in the quantity tier. - `price` (required, 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 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](/docs/api/currencies) 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](/docs/api/currencies) 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 item. The value is in major units of the currency. Returned when the plan is quantity-based and [multi-decimal pricing](/docs/api/currencies) is enabled. - `pricing_type` (optional, enumerated string) Pricing type for the tier. Possible enum values: - `per_unit` Indicates 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_fee` Indicates 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. - `package` Indicates 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). - `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. - `index` (required, integer, min=0) Not used. - `contract_term` (optional, contract_term) An object that specifies the contract term details. - `cancellation_cutoff_period` (optional, integer) The number of days before `[contract_end](/docs/api/contract_terms/contract_term-object#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. - `renewal_billing_cycles` (optional, integer) Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as `[billing_cycles](/docs/api/contract_terms/contract_term-object#billing_cycle)` or a custom value depending on the [site configuration](https://www.chargebee.com/docs/billing/2.0/subscriptions/contract-terms#configuring-contract-terms) . - `action_at_term_end` (required, enumerated string, default=renew) Action to be taken when the contract term completes. Possible enum values: - `renew` - 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`. - `evergreen` Contract term completes and the subscription renews. - `cancel` Contract term completes and subscription is canceled. - `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`. - `status_transition_reason` (optional, status_transition_reason) Detailed reason for the status transition of a ramp to `[draft](/docs/api/ramps/ramp-object#status)` and `[failed](/docs/api/ramps/ramp-object#status)` status. - `code` (optional, string, max chars=100) Unique code of the `status_transition_reason` . - `message` (optional, string, max chars=250) A message to explain the `status_transition_reason` . - `entitlement_overrides_to_add` (optional, list of entitlement_overrides_to_add) - `entity_id` (required, string, max chars=100) - `entity_type` (required, enumerated string) Possible enum values: - `plan_price` - `addon_price` - `charge` - `feature_id` (required, string, max chars=50) - `value` (optional, string, max chars=50) - `is_enabled` (required, boolean, default=true) - `entitlement_overrides_to_update` (optional, list of entitlement_overrides_to_update) - `entity_id` (required, string, max chars=100) - `entity_type` (required, enumerated string) Possible enum values: - `plan_price` - `addon_price` - `charge` - `feature_id` (required, string, max chars=50) - `value` (optional, string, max chars=50) - `is_enabled` (required, boolean, default=true) - `entitlement_overrides_to_remove` (optional, list of entitlement_overrides_to_remove) - `entity_id` (required, string, max chars=100) - `entity_type` (required, enumerated string) Possible enum values: - `plan_price` - `addon_price` - `charge` - `feature_id` (required, string, max chars=50)