# Create a price ramp > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). [Idempotency Supported](/docs/api/idempotency) Creates a price ramp for an [item price](/docs/api/item_prices). Use this operation to schedule how the item price changes across a subscription's billing cycles by defining an ordered set of `ramp_intervals`. Pass an overridden price for an interval using `price` (or `price_in_decimal` when [multi-decimal pricing](/docs/api/currencies) is enabled), or set `apply_catalog_price` to `true` to reuse the item price's catalog price for that interval. Chargebee merges adjacent `ramp_intervals` that have the same pricing before saving. Intervals are merged when they have the same `price`, or when consecutive intervals have `apply_catalog_price` set to `true`. Intervals with different prices, a mix of catalog and fixed pricing, or gaps in billing cycles aren't merged. The ramp must contain at least two intervals after merging. If the submitted intervals merge into a single interval, the request is rejected. ### Prerequisites & Constraints - [Price Ramps](https://www.chargebee.com/docs/billing/2.0/product-catalog/price-ramps) must be enabled for the site. Contact [Chargebee Support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable them. Until they are enabled, this operation returns `API_RESTRICTED`. - The `item_price_id` must not already be linked to a price ramp. An item price can have at most one price ramp. ## Sample Request #### Chargebee CLI ```bash chargebee price-ramp create \ -d item_price_id=basic-USD-Monthly \ -d 'ramp_intervals[starting_billing_cycle][0]=1' \ -d 'ramp_intervals[ending_billing_cycle][0]=1' \ -d 'ramp_intervals[price][0]=99' \ -d 'ramp_intervals[starting_billing_cycle][1]=2' \ -d 'ramp_intervals[ending_billing_cycle][1]=4' \ -d 'ramp_intervals[price][1]=499' \ -d 'ramp_intervals[starting_billing_cycle][2]=5' \ -d 'ramp_intervals[apply_catalog_price][2]=true' ``` #### cURL ```bash curl https://{site}.chargebee.com/api/v2/price_ramps \ -u {site_api_key}:\ -d item_price_id="basic-USD-Monthly" \ -d "ramp_intervals[starting_billing_cycle][0]"=1 \ -d "ramp_intervals[ending_billing_cycle][0]"=1 \ -d "ramp_intervals[price][0]"=99 \ -d "ramp_intervals[starting_billing_cycle][1]"=2 \ -d "ramp_intervals[ending_billing_cycle][1]"=4 \ -d "ramp_intervals[price][1]"=499 \ -d "ramp_intervals[starting_billing_cycle][2]"=5 \ -d "ramp_intervals[apply_catalog_price][2]"="true" ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = PriceRamp.Create() .ItemPriceId("basic-USD-Monthly") .RampIntervalStartingBillingCycle(0, 1) .RampIntervalEndingBillingCycle(0, 1) .RampIntervalPrice(0, 99) .RampIntervalStartingBillingCycle(1, 2) .RampIntervalEndingBillingCycle(1, 4) .RampIntervalPrice(1, 499) .RampIntervalStartingBillingCycle(2, 5) .RampIntervalApplyCatalogPrice(2, true) .Request(); PriceRamp priceRamp = result.PriceRamp; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" pricerampAction "github.com/chargebee/chargebee-go/v3/actions/priceramp" "github.com/chargebee/chargebee-go/v3/models/priceramp" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := pricerampAction.Create(&priceramp.CreateRequestParams{ RampIntervals : []*priceramp.CreateRampIntervalParams{ { StartingBillingCycle : chargebee.Int32(1), EndingBillingCycle : chargebee.Int32(1), Price : chargebee.Int64(99), }, { StartingBillingCycle : chargebee.Int32(2), EndingBillingCycle : chargebee.Int32(4), Price : chargebee.Int64(499), }, { StartingBillingCycle : chargebee.Int32(5), ApplyCatalogPrice : chargebee.Bool(true), }, }, ItemPriceId : "basic-USD-Monthly", }).Request() if err != nil { fmt.Println(err) } else { PriceRamp := res.PriceRamp } } ``` #### 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.PriceRampCreateRequest{ RampIntervals : []*chargebee.PriceRampCreateRampInterval{ { StartingBillingCycle : chargebee.Int32(1), EndingBillingCycle : chargebee.Int32(1), Price : chargebee.Int64(99), }, { StartingBillingCycle : chargebee.Int32(2), EndingBillingCycle : chargebee.Int32(4), Price : chargebee.Int64(499), }, { StartingBillingCycle : chargebee.Int32(5), ApplyCatalogPrice : chargebee.Bool(true), }, }, ItemPriceId : "basic-USD-Monthly", } res, err := client.PriceRamp.Create(req) if err != nil { fmt.Println(err) } else { PriceRamp := res.PriceRamp } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = PriceRamp.create() .itemPriceId("basic-USD-Monthly") .rampIntervalStartingBillingCycle(0, 1) .rampIntervalEndingBillingCycle(0, 1) .rampIntervalPrice(0, 99L) .rampIntervalStartingBillingCycle(1, 2) .rampIntervalEndingBillingCycle(1, 4) .rampIntervalPrice(1, 499L) .rampIntervalStartingBillingCycle(2, 5) .rampIntervalApplyCatalogPrice(2, true) .request(); PriceRamp priceRamp = result.priceRamp(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.priceRamp.PriceRamp; import com.chargebee.v4.models.priceRamp.params.PriceRampCreateParams; import com.chargebee.v4.models.priceRamp.responses.PriceRampCreateResponse; import java.util.List; public class PriceRampCreate { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); PriceRampCreateParams.RampIntervalsParams rampInterval0 = PriceRampCreateParams.RampIntervalsParams.builder() .startingBillingCycle(1) .endingBillingCycle(1) .price(99L) .build(); PriceRampCreateParams.RampIntervalsParams rampInterval1 = PriceRampCreateParams.RampIntervalsParams.builder() .startingBillingCycle(2) .endingBillingCycle(4) .price(499L) .build(); PriceRampCreateParams.RampIntervalsParams rampInterval2 = PriceRampCreateParams.RampIntervalsParams.builder() .startingBillingCycle(5) .applyCatalogPrice(true) .build(); List rampIntervalsList = List.of(rampInterval0, rampInterval1, rampInterval2); PriceRampCreateParams params = PriceRampCreateParams.builder() .itemPriceId("basic-USD-Monthly") .rampIntervals(rampIntervalsList) .build(); PriceRampCreateResponse response = client.priceRamps().create(params); PriceRamp priceRamp = response.getPriceRamp(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.priceRamp.create({ ramp_intervals: [ { starting_billing_cycle: 1, ending_billing_cycle: 1, price: 99 }, { starting_billing_cycle: 2, ending_billing_cycle: 4, price: 499 }, { starting_billing_cycle: 5, apply_catalog_price: true } ], item_price_id: "basic-USD-Monthly" }); console.log(result); const priceRamp = result.price_ramp; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->priceRamp()->create([ "ramp_intervals" => [ [ "starting_billing_cycle" => 1, "ending_billing_cycle" => 1, "price" => 99 ], [ "starting_billing_cycle" => 2, "ending_billing_cycle" => 4, "price" => 499 ], [ "starting_billing_cycle" => 5, "apply_catalog_price" => true ] ], "item_price_id" => "basic-USD-Monthly" ]); $priceRamp = $result->price_ramp; ``` #### Python ```python from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.PriceRamp.create( cb_client.PriceRamp.CreateParams( ramp_intervals=[ cb_client.PriceRamp.CreateRampIntervalParams( starting_billing_cycle=1, ending_billing_cycle=1, price=99 ), cb_client.PriceRamp.CreateRampIntervalParams( starting_billing_cycle=2, ending_billing_cycle=4, price=499 ), cb_client.PriceRamp.CreateRampIntervalParams( starting_billing_cycle=5, apply_catalog_price=True ) ], item_price_id="basic-USD-Monthly" ) ) price_ramp = response.price_ramp ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::PriceRamp.create({ :item_price_id => "basic-USD-Monthly", :ramp_intervals => [ { :starting_billing_cycle => 1, :ending_billing_cycle => 1, :price => 99 }, { :starting_billing_cycle => 2, :ending_billing_cycle => 4, :price => 499 }, { :starting_billing_cycle => 5, :apply_catalog_price => "true" } ] }) price_ramp = result.price_ramp ``` ## Sample Response ```json { "price_ramp": { "id": "3b930dda-1444-44f1-b79b-8de01fd9c139", "item_price_id": "basic-USD-Monthly", "status": "active", "object": "price_ramp", "ramp_intervals": [ { "starting_billing_cycle": 1, "ending_billing_cycle": 1, "price": 99 }, { "starting_billing_cycle": 2, "ending_billing_cycle": 4, "price": 499 }, { "starting_billing_cycle": 5, "apply_catalog_price": true, "price": 999 } ], "resource_version": 1594110587730, "created_at": 1594110587, "updated_at": 1594110587 } } ``` ## URL Format **POST** https://[site].chargebee.com/api/v2/price_ramps ## Input Parameters - `item_price_id` (required, string, max chars=100) The ID of the [item price](/docs/api/item_prices) for which the price ramp is created. The price defined by the ramp intervals overrides the catalog price of this item price for the applicable billing cycles. - `business_entity_id` (optional, string, max chars=50) The unique ID of the [business entity](/docs/api/business_entities) for this `price_ramp`. This is applicable only when multiple business entities have been created for the site. When provided, the operation will read or write data associated with the specified business entity. If not provided, the resource will be created at the site level, and the business\_entity\_id will not be included in the API response. **Note**: An alternative way of passing this parameter is by using a [custom HTTP header](/docs/api/advanced-features) or [query string parameter](/docs/api/advanced-features#mbe-alternative). - `ramp_intervals` (optional, array) The ordered list of intervals that make up the price ramp. Each interval defines the price that applies for a contiguous range of billing cycles. Intervals must be contiguous and ordered by `starting_billing_cycle`, with the first interval starting at billing cycle `1`. Adjacent intervals with the same pricing are merged before the ramp is saved. At least 2 intervals must remain after the merge. Up to 3 intervals. - `starting_billing_cycle` (required, integer) The billing cycle at which this interval begins. The first interval must start at billing cycle `1`, and each subsequent interval must begin at the billing cycle immediately after the previous interval's `ending_billing_cycle`. - `ending_billing_cycle` (optional, integer) The billing cycle at which this interval ends. Omit this for the final interval so that its price applies to all remaining billing cycles. - `apply_catalog_price` (optional, boolean) Set to `true` to apply the item price's catalog price for this interval instead of an overridden ramp price. When `true`, do not pass `price` or `price_in_decimal` for the interval. - `price` (optional, in cents) The price that applies for this interval, in the [minor unit of the currency](/docs/api/currencies). Do not pass this when `apply_catalog_price` is `true`. - `price_in_decimal` (optional, string, max chars=39) The price that applies for this interval, in the major (decimal) unit of the currency. Applicable only when [multi-decimal pricing](/docs/api/currencies) is enabled. Do not pass this when `apply_catalog_price` is `true`. ## Returns - `price_ramp` (Price ramp object)