Price ramp resource lets you define a stepped pricing schedule on an item price in the Product Catalog. Each ramp is an ordered list of ramp_intervals that set the price for contiguous ranges of billing cycles, so new subscriptions inherit introductory or stepped pricing without custom per-subscription logic.
Here's an example to show how you can use ramp pricing:
A media streaming company offers a Basic monthly plan with a catalog price of $9.99. To grow acquisitions, they configure a price ramp so new subscribers start on an introductory price, then step up to full price.
| Plan | Currency | Frequency | Catalog price |
| Basic | USD | Monthly | $9.99 |
| Billing cycles | Price charged | Price type |
| Month 1 | $0.99 | Introductory ramp price |
| Months 2–4 | $4.99 | Introductory ramp price |
| Month 5 onwards | $9.99 | Catalog price |
Every new subscription on this Basic USD Monthly item price inherits the ramp automatically. In this example the final interval uses the catalog price, so the subscriber stays on $9.99 from month 5 onward. The catalog price continues only when that final interval sets apply_catalog_price to true. A final interval that sets price and omits ending_billing_cycle keeps that fixed price for the remaining billing cycles.
An interval that uses the item price's catalog price returns apply_catalog_price as true. The resolved price for every interval is always available in price (in the minor unit of the currency) and, when multi-decimal pricing is enabled, in price_in_decimal.
When a price ramp is linked to an item price, the price_ramp_id is exposed on the corresponding item price object.
See also: For a more detailed understanding of Price Ramps, including how to configure and manage them, as well as their impact on other features, follow these resources:
Sample Price rampJSON
Price Ramp attributes
The ID of the item price whose price changes according to this ramp. An item price can be linked to at most one price ramp.
The current status of the price ramp.
The price ramp is active and its ramp intervals apply to the linked item price.
The price ramp has been archived and no longer applies to the linked item price.
The price ramp has been deleted and its link to the item price has been removed.
The unique ID of the
business entity
of this price_ramp.
This is applicable only when multiple business entities have been created for the site. The value of this attribute indicates that the resource is specific to the given business entity.