# Update a subscription ramp > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). [Idempotency Supported](/docs/api/idempotency) Batch 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** 1. Send a request to retrieve the current values of all parameters for the subscription ramp using [Retrieve a subscription ramp](/docs/api/ramps/retrieve-a-ramp) API. 2. 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** 1. 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. 2. Send the prepared request to [Update subscription ramp](/docs/api/ramps/update-a-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](/docs/api/ramps/ramp-object#status)`. - **Advance invoice**: You cannot update ramps for subscriptions that have an [advance invoice schedule](/docs/api/advance_invoice_schedules). ## Sample Request #### cURL ```bash curl https://{site}.chargebee.com/api/v2/ramps/__test__rHsiT4rY2hC1A/update \ -X POST \ -u {site_api_key}:\ -d effective_from=1635054328 \ -d description="Updated description for first ramp" \ -d "items_to_remove[0]"="basicAddon1-USD-Monthly" \ -d "items_to_add[item_price_id][0]"="basicAddon2-USD-Monthly" \ -d "items_to_add[quantity][0]"=2 \ -d "discounts_to_add[duration_type][0]"="ONE_TIME" \ -d "discounts_to_add[apply_on][0]"="INVOICE_AMOUNT" \ -d "discounts_to_add[percentage][0]"=5 \ -d "items_to_update[item_price_id][0]"="basicPlan-USD-Monthly" \ -d "items_to_update[unit_price][0]"=20000 ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; using ChargeBee.Models.Enums; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = Ramp.Update("__test__rHsiT4rY2hC1A") .EffectiveFrom(1635054328) .Description("Updated description for first ramp") .ItemsToRemove(new List{"basicAddon1-USD-Monthly"}) .ItemsToAddItemPriceId(0, "basicAddon2-USD-Monthly") .ItemsToAddQuantity(0, 2) .DiscountsToAddDurationType(0, DurationTypeEnum.OneTime) .DiscountsToAddApplyOn(0, ApplyOnEnum.InvoiceAmount) .DiscountsToAddPercentage(0, 5) .ItemsToUpdateItemPriceId(0, "basicPlan-USD-Monthly") .ItemsToUpdateUnitPrice(0, 20000) .Request(); Ramp ramp = result.Ramp; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" rampAction "github.com/chargebee/chargebee-go/v3/actions/ramp" "github.com/chargebee/chargebee-go/v3/models/ramp" enum "github.com/chargebee/chargebee-go/v3/enum" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := rampAction.Update("__test__rHsiT4rY2hC1A", &ramp.UpdateRequestParams{ ItemsToAdd : []*ramp.UpdateItemsToAddParams{ { ItemPriceId : "basicAddon2-USD-Monthly", Quantity : chargebee.Int32(2), }, }, DiscountsToAdd : []*ramp.UpdateDiscountsToAddParams{ { DurationType : enum.DurationTypeOneTime, ApplyOn : enum.ApplyOnInvoiceAmount, Percentage : chargebee.Float64(5), }, }, ItemsToUpdate : []*ramp.UpdateItemsToUpdateParams{ { ItemPriceId : "basicPlan-USD-Monthly", UnitPrice : chargebee.Int64(20000), }, }, EffectiveFrom : chargebee.Int64(1635054328), Description : "Updated description for first ramp", ItemsToRemove : []string{"basicAddon1-USD-Monthly"}, }).Request() if err != nil { fmt.Println(err) } else { Ramp := res.Ramp } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.RampUpdateRequest{ ItemsToAdd : []*chargebee.RampUpdateItemsToAdd{ { ItemPriceId : "basicAddon2-USD-Monthly", Quantity : chargebee.Int32(2), }, }, DiscountsToAdd : []*chargebee.RampUpdateDiscountsToAdd{ { DurationType : chargebee.DurationTypeOneTime, ApplyOn : chargebee.ApplyOnInvoiceAmount, Percentage : chargebee.Float64(5), }, }, ItemsToUpdate : []*chargebee.RampUpdateItemsToUpdate{ { ItemPriceId : "basicPlan-USD-Monthly", UnitPrice : chargebee.Int64(20000), }, }, EffectiveFrom : chargebee.Int64(1635054328), Description : "Updated description for first ramp", ItemsToRemove : []string{"basicAddon1-USD-Monthly"}, } res, err := client.Ramp.Update("__test__rHsiT4rY2hC1A", req) if err != nil { fmt.Println(err) } else { Ramp := res.Ramp } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; import java.sql.Timestamp; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = Ramp.update("__test__rHsiT4rY2hC1A") .effectiveFrom(new Timestamp(1635054328L * 1000)) .description("Updated description for first ramp") .itemsToRemove("basicAddon1-USD-Monthly") .itemsToAddItemPriceId(0, "basicAddon2-USD-Monthly") .itemsToAddQuantity(0, 2) .discountsToAddDurationType(0, DurationType.ONE_TIME) .discountsToAddApplyOn(0, ApplyOn.INVOICE_AMOUNT) .discountsToAddPercentage(0, 5.0) .itemsToUpdateItemPriceId(0, "basicPlan-USD-Monthly") .itemsToUpdateUnitPrice(0, 20000L) .request(); Ramp ramp = result.ramp(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.ramp.Ramp; import com.chargebee.v4.models.ramp.params.RampUpdateParams; import com.chargebee.v4.models.ramp.responses.RampUpdateResponse; import java.sql.Timestamp; import java.util.List; public class RampUpdate { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); RampUpdateParams.ItemsToAddParams itemsToAdd0 = RampUpdateParams.ItemsToAddParams.builder() .itemPriceId("basicAddon2-USD-Monthly") .quantity(2) .build(); List itemsToAddList = List.of(itemsToAdd0); RampUpdateParams.DiscountsToAddParams discountsToAdd0 = RampUpdateParams.DiscountsToAddParams.builder() .durationType(RampUpdateParams.DiscountsToAddParams.DurationType.ONE_TIME) .applyOn(RampUpdateParams.DiscountsToAddParams.ApplyOn.INVOICE_AMOUNT) .percentage(5.0) .build(); List discountsToAddList = List.of(discountsToAdd0); RampUpdateParams.ItemsToUpdateParams itemsToUpdate0 = RampUpdateParams.ItemsToUpdateParams.builder() .itemPriceId("basicPlan-USD-Monthly") .unitPrice(20000L) .build(); List itemsToUpdateList = List.of(itemsToUpdate0); RampUpdateParams params = RampUpdateParams.builder() .effectiveFrom(new Timestamp(1635054328L * 1000)) .description("Updated description for first ramp") .itemsToRemove(List.of("basicAddon1-USD-Monthly")) .itemsToAdd(itemsToAddList) .discountsToAdd(discountsToAddList) .itemsToUpdate(itemsToUpdateList) .build(); RampUpdateResponse response = client .ramps() .update("__test__rHsiT4rY2hC1A", params); Ramp ramp = response.getRamp(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.ramp.update("__test__rHsiT4rY2hC1A", { 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 } ], effective_from: 1635054328, description: "Updated description for first ramp", items_to_remove: ["basicAddon1-USD-Monthly"] }); console.log(result); const ramp = result.ramp; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->ramp()->update("__test__rHsiT4rY2hC1A", [ "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 ] ], "effective_from" => 1635054328, "description" => "Updated description for first ramp", "items_to_remove" => ["basicAddon1-USD-Monthly"] ]); $ramp = $result->ramp; ``` #### Python ```python import chargebee from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.Ramp.update("__test__rHsiT4rY2hC1A", cb_client.Ramp.UpdateParams( items_to_add=[ cb_client.Ramp.UpdateItemsToAddParams( item_price_id="basicAddon2-USD-Monthly", quantity=2 ) ], discounts_to_add=[ cb_client.Ramp.UpdateDiscountsToAddParams( duration_type=chargebee.DurationType.ONE_TIME, apply_on=chargebee.ApplyOn.INVOICE_AMOUNT, percentage=5 ) ], items_to_update=[ cb_client.Ramp.UpdateItemsToUpdateParams( item_price_id="basicPlan-USD-Monthly", unit_price=20000 ) ], effective_from=1635054328, description="Updated description for first ramp", items_to_remove=["basicAddon1-USD-Monthly"] ) ) ramp = response.ramp ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::Ramp.update("__test__rHsiT4rY2hC1A",{ :effective_from => 1635054328, :description => "Updated description for first ramp", :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 } ] }) ramp = result.ramp ``` ## Sample Response ```json { "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 ## Input Parameters - `effective_from` (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](/docs/api/subscriptions/subscription-object#pause_date)` or `[cancelled_at](/docs/api/subscriptions/subscription-object#cancelled_at)`. - `description` (optional, string, max chars=250) A brief summary of the pricing changes applied with this ramp. - `coupons_to_remove` (optional, string, max chars=100) List of [coupons](/docs/api/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` (optional, string, max chars=100) List of [discounts](/docs/api/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` (optional, string, max chars=100) List of [item prices](/docs/api/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. - `contract_term` (optional, enumerated string) An object that specifies the contract term details. - `action_at_term_end` (optional, enumerated string, default=renew) Action to be taken when the contract term completes. Possible enum values: - `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`. - `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`. - `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) . - `items_to_add` (optional, array) 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. **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](/docs/api/item_prices/item_price-object#period) of the subscription if an upcoming ramp already exists after `[effective_from](/docs/api/ramps/create-a-ramp#effective_from)` time. - `quantity` (optional, integer) 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) 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. - `billing_cycles` (optional, integer) 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) The service period of the item in days from the day of charge. - `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) . - `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` . - `items_to_update` (optional, array) 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. **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. - `quantity` (optional, integer) 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) 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. - `billing_cycles` (optional, integer) 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) The service period of the item in days from the day of charge. - `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) . - `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` . - `item_tiers` (optional, array) **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_price_id` (optional, string, max chars=100) 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`. - `starting_unit` (optional, integer) The lowest value in the quantity tier. - `ending_unit` (optional, integer) The highest value in the quantity tier. - `price` (optional, in cents) The overridden price of the tier. The value depends on the [type of currency](/docs/api/currencies) . - `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) 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. - `coupons_to_add` (optional, array) Details about the [coupons](/docs/api/coupons) added to the subscription through this ramp. - `coupon_id` (optional, string, max chars=100) Unique ID of the coupon to be added. **Caution** - Ensure this list does not include coupons being removed through this ramp. - [Coupon codes](/docs/api/coupon_codes) are not supported. - `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, array) Details about the [discounts](/docs/api/discounts) added to the subscription through this ramp. - `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` . - `duration_type` (required, enumerated string) 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` . - `percentage` (optional, double) The percentage of the original amount that should be deducted from it. - `amount` (optional, in cents) The value of the discount. [The format of this value](/docs/api/currencies) depends on the kind of currency. - `quantity` (optional, integer) Specifies the number of free units provided for the item, without affecting the total quantity sold. When `discounts_to_add.quantity` is provided, the [`discounts_to_add.type`](/docs/api/ramps/ramp-object#discounts_to_add_type) is automatically set to `offer_quantity`. **Constraints** - `discounts_to_add[item_price_id]` must belong to an item price with [`pricing_model`](/docs/api/item_prices#pricing_model) `per_unit`. - `discounts_to_add[apply_on]` must be `specific_item_price`. - `period` (optional, integer) 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` (optional, 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`. - `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`. ## Returns - `ramp` (Ramp object) Resource object representing ramp