When a quote is created, it generates the quoted_ramps resource. This captures most of the details of the ramps that would eventually be created once the quote is invoiced. This resource is returned along with the quote for most of the associated operations.
Sample quoted ramp [ JSON ]
{
"line_items": [
{
"item_price_id": "p1-USD-Monthly",
"item_type": "plan",
"quantity": 1,
"unit_price": 1000,
"amount_per_billing_cycle": 1000,
"net_amount_per_billing_cycle": 800,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1749148200,
"end_date": 1751740199,
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "p1-USD-Monthly",
"item_type": "plan",
"quantity": 1,
"unit_price": 1000,
"amount_per_billing_cycle": 1000,
"net_amount_per_billing_cycle": 950,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1751740200,
"end_date": 1754418599,
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "p1-USD-Monthly",
"item_type": "plan",
"quantity": 1,
"unit_price": 1000,
"amount_per_billing_cycle": 1000,
"net_amount_per_billing_cycle": 1000,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1754418600,
"end_date": 1843842599,
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "a1-USD-Monthly",
"item_type": "addon",
"quantity": 1,
"unit_price": 1000,
"amount_per_billing_cycle": 1000,
"net_amount_per_billing_cycle": 800,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1749148200,
"end_date": 1751740199,
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "tiered-USD-Monthly",
"item_type": "addon",
"quantity": 50,
"unit_price": 5750,
"amount_per_billing_cycle": 287500,
"net_amount_per_billing_cycle": 273125,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1751740200,
"end_date": 1754418599,
"ramp_tier_id": "tiered-USD-Monthly-1",
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "a1-USD-Monthly",
"item_type": "addon",
"quantity": 10,
"unit_price": 1000,
"amount_per_billing_cycle": 10000,
"net_amount_per_billing_cycle": 10000,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1754418600,
"end_date": 1843842599,
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
},
{
"item_price_id": "tiered-USD-Monthly",
"item_type": "addon",
"quantity": 1,
"unit_price": 5000,
"amount_per_billing_cycle": 5000,
"net_amount_per_billing_cycle": 5000,
"item_level_discount_per_billing_cycle": 0,
"start_date": 1754418600,
"end_date": 1843842599,
"ramp_tier_id": "tiered-USD-Monthly-2",
"billing_period": 1,
"billing_period_unit": "month",
"object": "subscription_item"
}
],
"item_tiers": [
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 1,
"price": 5000,
"ramp_tier_id": "tiered-USD-Monthly-1",
"ending_unit": 25
},
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 26,
"price": 6500,
"ramp_tier_id": "tiered-USD-Monthly-1",
"ending_unit": 100
},
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 101,
"price": 7500,
"ramp_tier_id": "tiered-USD-Monthly-1"
},
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 1,
"price": 5000,
"ramp_tier_id": "tiered-USD-Monthly-2",
"ending_unit": 25
},
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 26,
"price": 6000,
"ramp_tier_id": "tiered-USD-Monthly-2",
"ending_unit": 100
},
{
"item_price_id": "tiered-USD-Monthly",
"starting_unit": 101,
"price": 7000,
"ramp_tier_id": "tiered-USD-Monthly-2"
}
],
"discounts": [
{
"type": "percentage",
"duration_type": "one_time",
"apply_on": "invoice_amount",
"included_in_mrr": false,
"percentage": 20,
"entity_type": "document_level_discount",
"start_date": 1749148200,
"end_date": 1751740199
},
{
"type": "percentage",
"duration_type": "one_time",
"apply_on": "invoice_amount",
"included_in_mrr": false,
"percentage": 5,
"entity_type": "document_level_discount",
"start_date": 1751740200,
"end_date": 1754418599
}
]
}
API Index URL GET
https://{site}.chargebee.com/api/v2/quoted_ramps
optional, list of line_item
Provides details of the individual line items in the subscription. If the subscription includes ramps, this array contains line items from all ramps.
string, max chars=100 The unique identifier of the item price.
enumerated string The type of item. There must be one and only one item of type plan in this list.
optional, integer, min=1 The quantity of the item purchased
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 is enabled.
optional, in cents, min=0 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.
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 is enabled.
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.
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 is enabled.
optional, integer, min=1 The interval between consecutive billing cycles for the subscription item. The interval is measured in the units defined by billing_period_unit.
optional, enumerated string The unit of measurement used to define the billing_period for the subscription item. Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
Show all values[+]
optional, integer, min=0 The free_quantity of the plan-item as specified for the item price.
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 is enabled.
optional, integer, min=1, max=730 The service period of the item in days from the day of charge.
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 values are
subscription_creationthe time of creation of the subscription.subscription_trial_startthe time when the trial period of the subscription begins.plan_activationsame as subscription activation, but also includes the case when the plan-item of the subscription is changed.subscription_activationthe moment a subscription enters an active or non-renewing state. Also includes reactivations of canceled subscriptions.
Show all values[+]
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.
optional, enumerated string Indicates when the charge-item is to be charged. This parameter only applies to charge-items. Possible values are
immediatelyThe item is charged immediately on being added to the subscription.on_eventThe item is charged at the occurrence of the event specified as charge_on_event.
Show all values[+]
optional, timestamp(UTC) in seconds Specifies the start date for the item price in the subscription. The period of the item price, determined by the start_date and end_date, specifies the ramp it belongs to.
optional, timestamp(UTC) in seconds Specifies the end date for the item price in the subscription. The period of the item price, determined by the start_date and end_date, specifies the ramp it belongs to.
optional, string, max chars=105 The index or identifier of the ramp to which the item price belongs. This index is used to map item_tier[i] values to the correct ramp, as the target item_price of an item_tier may be part of multiple ramps.
discount_per_billing_cycle
optional, in cents, min=0 Specifies the discount amount applied to a line item per billing cycle. This includes both item-level and invoice-level discounts.
Example: Consider a monthly quote that includes a plan, an addon, a $50 discount on the plan, and an additional $100 invoice-level discount. In this case, discount_per_billing_cycle for the plan would be ($50 + $100 ÷ 2) = $100.
discount_per_billing_cycle_in_decimal
optional, string, max chars=39 Specifies the discount amount applied to a line item per billing cycle, in decimal format. The value is expressed in the major currency units. This attribute is available only when Multi-Decimal Pricing is enabled.
See also:discount_per_billing_cycle.
item_level_discount_per_billing_cycle
optional, in cents, min=0 Specifies the item-level discount amount applied to a line item per billing cycle. This does not include invoice-level discounts.
Example: Consider a monthly quote that includes a plan, an addon, a $50 discount on the plan, and an additional $100 invoice-level discount. In this case, item_level_discount_per_billing_cycle for the plan would be $50.
item_level_discount_per_billing_cycle_in_decimal
optional, string, max chars=39 Specifies the item-level discount amount applied to a line item per billing cycle, in decimal format. The value is expressed in the major currency units. This attribute is available only when Multi-Decimal Pricing is enabled.
See also:item_level_discount_per_billing_cycle.
optional, in cents, min=0 Specifies the amount for this line item before discounts.
Example:Consider a monthly quote that includes a $500 plan, an addon, a $50 discount on the plan, and an additional $100 invoice-level discount. In this case, amount_per_billing_cycle for the plan would be $500.
amount_per_billing_cycle_in_decimal
optional, string, max chars=39 Specifies the amount for this line item before discounts, in decimal format. The value is expressed in the major currency units. This attribute is available only when Multi-Decimal Pricing is enabled.
See also:amount_per_billing_cycle.
net_amount_per_billing_cycle
optional, in cents, min=0 Specifies the amount for this line item after discounts.
Example: Consider a monthly quote that includes a $500 plan, an addon, a $50 discount on the plan, and an additional $100 invoice-level discount. In this case, net_amount_per_billing_cycle for the plan would be ($500 - ($50 + $100 ÷ 2)) = $400.
net_amount_per_billing_cycle_in_decimal
optional, string, max chars=39 Specifies the amount for this line item after discounts, in decimal format. The value is expressed in the major currency units. This attribute is available only when Multi-Decimal Pricing is enabled.
See also:net_amount_per_billing_cycle.
optional, list of discount
List of discounts for this quoted subscription.
string, max chars=50 An immutable unique id for the discount. It is always auto-generated.
optional, string, max chars=100 The name of the discount as it should appear on customer-facing pages and documents such as invoices and 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.
enumerated string, default=percentage The type of discount.
Possible value are: Possible values are
fixed_amountThe specified amount will be given as discount.percentageThe specified percentage will be given as discount.
Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it.
enumerated string, default=forever Specifies the time duration for which this discount is attached to the subscription. Possible values are
one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is explicitly removed.limited_periodThe 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. Show all values[+]
enumerated string The type of deduction and the amount it applies to.
Possible values are
item_level_couponThe deduction comes from a coupon applied to a specific line item. The coupon id is available in the entity_id attribute.
document_level_couponThe deduction comes from a coupon applied at the invoice level. The coupon id is available in the entity_id attribute.
item_level_discountThe deduction comes from a discount applied to a specific line item. The discount id is available in the entity_id attribute.
document_level_discountThe deduction comes from a discount applied at the invoice level. The discount id is available in the entity_id attribute.
Show all values[+]
optional, string, max chars=100 When the deduction results from a coupon or a discount, this attribute contains the id of that coupon or discount.
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.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_period. Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
Show all values[+]
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 in Chargebee. Also, If the site-level setting is to exclude one-time discounts from MRR calculations, this value is always returned false.
enumerated string The amount on the invoice to which the discount is applied. Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
Show all values[+]
optional, string, max chars=100 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.
timestamp(UTC) in seconds Timestamp indicating when this discount is created.
optional, timestamp(UTC) in seconds
optional, timestamp(UTC) in seconds Specifies the start date for the discount. The period of the discount, as specified by the start_date and end_date determines the ramp(s) it will be part of.
optional, timestamp(UTC) in seconds Specifies the end date for the discount. The period of the discount, as specified by the start_date and end_date determines the ramp(s) it will be part of.
optional, list of item_tier
List of item tier.
string, max chars=100 The id of the item price to which this tier belongs.
integer, min=1 The lowest value in the quantity tier.
optional, integer The highest value in the quantity tier.
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.
optional, string, max chars=33 The decimal representation of the 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.
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 is enabled.
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 is enabled.
optional, string, max chars=105 The index or identifier of the ramp to which this tier information belongs. This is a value from the line_items[i].ramp_tier_id. Since an item price can be part of multiple subscriptions ramps, this group ID specifies the ramp to which this tier information belongs.
optional, enumerated string Pricing type for the tier. Possible values are
per_unitIndicates 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_feeIndicates 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.packageIndicates 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).
Show all values[+]
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. optional, list of coupon_applicability_mapping
Coupon applicability mapping attributes
optional, string, max chars=50 applicable_item_price_ids
optional, string, max chars=100
This is a list of the event types we currently support. We will continue
to add more events moving forward. All events follow a uniform pattern -
<resource>_<event_name>. The resources that will be
present in the event content are provided beneath each event type's
description.
Note: If consolidated invoicing is enabled, the
attributes invoice.subscription_id and
credit_note.subscription_id should not be used
(as it will not be present if the invoice / credit note has lines from
multiple subscriptions). Instead to know the related subscriptions,
their line_items' subscription_id attribute should be referred.
optional, list of line_item Provides details of the individual line items in the subscription. If the subscription includes ramps, this array contains line items from all ramps.
optional, list of discount List of discounts for this quoted subscription.
optional, list of item_tier List of item tier.
optional, list of coupon_applicability_mapping 
Settings
Configure SDK
