Ramps

API Version

Product Catalog

Library

The ramp resource or a subscription ramp represents a planned change to a subscription set to occur at a future date. By using this resource, you can define and schedule modifications to a subscription, such as updating pricing, altering the 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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

Sample ramp [ JSON ]

{
    "id": "__test__rHsiT4rY2hC1A",
    "effective_from": "1635054328",
    "subscription_id": "__test__8asukSOXdv6kOj",
    "status": "scheduled",
    "description": "Schedule 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
        }
    ]
}

Model Class

id

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

string, max chars=50
The ID of the subscription for which this ramp was created.

effective_from

timestamp(UTC) in seconds
Specifies the time when the changes to the subscription will be applied by executing the ramp.

status

enumerated string
The execution status of the ramp

Possible values are

scheduledThe 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.

succeededThe ramp completed successfully.failedThe ramp did not complete because of an error.draftThe 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

Note

Ramps in draft state will not be executed.

created_at

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, list of string
List of item prices removed from the subscription through this ramp.

coupons_to_remove

optional, list of string
List of coupons removed from the subscription through this ramp.

discounts_to_remove

optional, list of string
List of discounts removed from the subscription through this ramp.

deleted

boolean
Indicates if the ramp is marked as deleted. To retrieve deleted ramps, use the List subscription ramps endpoint with include_deleted set to true.

items_to_add
Show attributes [+]

optional, list of items_to_add
Details about the item prices added to the subscription through this ramp.

Items to add attributes

item_price_id

string, max chars=100
The unique identifier of the item price.

item_type

enumerated string
The type of item. There must be one and only one item of type plan in this list.

Possible values are

planPlanaddonAddonchargeCharge

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 is enabled.

unit_price

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.

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 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.

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 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.

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 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 for the plan-item price is used.

For addon-item prices:
If addon billing cycles 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 is used. Further, if that value is not provided, then the value set for the addon-item price 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

items_to_update
Show attributes [+]

optional, list of items_to_update
Details about the item prices updated in the subscription through this ramp.

Items to update attributes

item_price_id

string, max chars=100
The unique identifier of the item price.

item_type

enumerated string
The type of item. There must be one and only one item of type plan in this list.

Possible values are

planPlanaddonAddonchargeCharge

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 is enabled.

unit_price

unit_price_in_decimal

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.

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 is enabled.

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 is enabled.

billing_cycles

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

coupons_to_add
Show attributes [+]

optional, list of coupons_to_add
Details about the coupons added to the subscription through this ramp.

discounts_to_add
Show attributes [+]

optional, list of discounts_to_add
Details about the discounts added to the subscription through this ramp.

Discounts to add attributes

id

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 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.

type

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.

percentage

optional, double, min=0.01, max=100.0
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 depends on the kind of currency.

duration_type

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.

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 values are

dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.

included_in_mrr

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.

apply_on

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.

item_price_id

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.

created_at

timestamp(UTC) in seconds
Timestamp indicating when this discount is created.

item_tiers
Show attributes [+]

optional, list of item_tier

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.

Overrides the item_tiers for specific item_prices of the subscription.

Item tier attributes

item_price_id

string, max chars=100
The id of the item price to which this tier belongs.

starting_unit

integer, min=1
The lowest value in the quantity tier.

ending_unit

optional, integer
The highest value in the quantity tier.

price

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 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.

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 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 is enabled.

pricing_type

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).

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

integer, min=0
Not used.

status_transition_reason
Show attributes [+]

optional, status_transition_reason
Detailed reason for the status transition of a ramp to draft and failed status.

id

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

string, max chars=50
The ID of the subscription for which this ramp was created.

effective_from

timestamp(UTC) in seconds
Specifies the time when the changes to the subscription will be applied by executing the ramp.

status

enumerated string
The execution status of the ramp

Possible values are

scheduledThe 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.

Note

Ramps in draft state will not be executed.

created_at

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, list of string
List of item prices removed from the subscription through this ramp.

coupons_to_remove

optional, list of string
List of coupons removed from the subscription through this ramp.

discounts_to_remove

optional, list of string
List of discounts removed from the subscription through this ramp.

deleted

boolean
Indicates if the ramp is marked as deleted. To retrieve deleted ramps, use the List subscription ramps endpoint with include_deleted set to true.

items_to_add

optional, list of items_to_add
Details about the item prices added to the subscription through this ramp.

items_to_update

optional, list of items_to_update
Details about the item prices updated in the subscription through this ramp.

coupons_to_add

optional, list of coupons_to_add
Details about the coupons added to the subscription through this ramp.

discounts_to_add

optional, list of discounts_to_add
Details about the discounts added to the subscription through this ramp.

item_tiers

optional, list of item_tier

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.

Overrides the item_tiers for specific item_prices of the subscription.

status_transition_reason

optional, status_transition_reason
Detailed reason for the status transition of a ramp to draft and failed status.

Creates a ramp for a subscription.

Note

Subscription status: You cannot create ramps for subscriptions in the paused or cancelled status.
Advance invoice: You cannot create ramps for subscriptions that have an advance invoice schedule.
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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
You cannot create a ramp for subscription, when ramps are in draft status.

Sample Codes

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/create_ramp \
     -X POST  \
     -u {site_api_key}:\
     -d effective_from=1635054328 \
     -d description="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

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/subscriptions/__test__8asukSOXdv6kOj/create_ramp \
     -X POST  \
     -u {site_api_key}:\
     -d effective_from=1635054328 \
     -d description="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

Sample Result [ JSON ]

{
    "ramp": {
        "id": "__test__rHsiT4rY2hC1A",
        "effective_from": "1635054328",
        "subscription_id": "__test__8asukSOXdv6kOj",
        "status": "scheduled",
        "description": "Schedule 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
            },
            {..}
        ]
    }
}

Method

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 or cancelled_at.

description[]

optional, string, max chars=250
A brief summary of the pricing changes applied with this ramp.

coupons_to_remove[]

optional, list of string
List of 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, list of string
List of 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, list of string
List of 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.

items_to_add

Details about the <a href="/docs/api/item_prices?prod_cat_ver=2">item prices</a> 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 of the subscription if an upcoming ramp already exists after effective_from time.

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 is enabled.

unit_price

unit_price_in_decimal

billing_cycles

service_period_days

optional, integer, min=1, max=730
The service period of the item in days from the day of charge.

items_to_update

Details about the <a href="item_prices">item prices</a> 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, 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 is enabled.

unit_price

unit_price_in_decimal

billing_cycles

service_period_days

optional, integer, min=1, max=730
The service period of the item in days from the day of charge.

item_tiers

<div class="alert alert-warning"> <strong>Note</strong> <p>Allowed only when both of these conditions are met:</p> <ul> <li>Price overriding is enabled for the site.</li> <li>pricing_model of the item price is either tiered, volume, or stairstep.</li> </ul> </div> <p>Replaces the existing item_tiers for specific <code>item_price</code>s within the subscription. You must provide the complete tier set for any <code>item_price</code>, even if you’re changing the price for only one tier.</p>

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, min=1
The lowest value in the quantity tier.

ending_unit

optional, integer
The highest value in the quantity tier.

price

optional, in cents, default=0, min=0
The overridden price of the tier. The value depends on the type of currency.

starting_unit_in_decimal

ending_unit_in_decimal

price_in_decimal

pricing_type

optional, enumerated string
Pricing type for the tier.

Possible values are

package_size

coupons_to_add

Details about the <a href="coupons">coupons</a> 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 are not supported.

apply_till

optional, timestamp(UTC) in seconds
The date till when the coupon can be applied. Applicable for limited_period coupons only.

discounts_to_add

Details about the <a href="/docs/api/discounts?prod_cat_ver=2">discounts</a> added to the subscription through this ramp.

apply_on

required, enumerated string
The amount on the invoice to which the discount is applied.

Possible values are

duration_type

required, enumerated string, default=forever
Specifies the time duration for which this discount is attached to the subscription.

Possible values are

percentage

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.

amount

optional, in cents, min=0
The value of the discount. depends on the kind of currency.

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 values are

dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA 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 in Chargebee. Also, If the site-level setting 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 in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.

ramp

always returned

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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

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

Send a request to retrieve the current values of all parameters for the subscription ramp using Retrieve a subscription ramp API.
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

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.
Send the prepared request to Update 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.
Advance invoice: You cannot update ramps for subscriptions that have an advance invoice schedule.

Sample Codes

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

copy

Click to Copy

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

Sample Result [ 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
            },
            {..}
        ]
    }
}

Method

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 or cancelled_at.

description[]

optional, string, max chars=250
A brief summary of the pricing changes applied with this ramp.

coupons_to_remove[]

optional, list of string
List of 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, list of string
List of 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, list of string
List of 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.

items_to_add

Details about the <a href="/docs/api/item_prices?prod_cat_ver=2">item prices</a> 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 of the subscription if an upcoming ramp already exists after effective_from time.

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 is enabled.

unit_price

unit_price_in_decimal

billing_cycles

service_period_days

optional, integer, min=1, max=730
The service period of the item in days from the day of charge.

items_to_update

Details about the <a href="item_prices">item prices</a> 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, 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 is enabled.

unit_price

unit_price_in_decimal

billing_cycles

service_period_days

optional, integer, min=1, max=730
The service period of the item in days from the day of charge.

item_tiers

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, min=1
The lowest value in the quantity tier.

ending_unit

optional, integer
The highest value in the quantity tier.

price

optional, in cents, default=0, min=0
The overridden price of the tier. The value depends on the type of currency.

starting_unit_in_decimal

ending_unit_in_decimal

price_in_decimal

pricing_type

optional, enumerated string
Pricing type for the tier.

Possible values are

package_size

coupons_to_add

Details about the <a href="coupons">coupons</a> 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 are not supported.

apply_till

optional, timestamp(UTC) in seconds
The date till when the coupon can be applied. Applicable for limited_period coupons only.

discounts_to_add

Details about the <a href="/docs/api/discounts?prod_cat_ver=2">discounts</a> added to the subscription through this ramp.

apply_on

required, enumerated string
The amount on the invoice to which the discount is applied.

Possible values are

duration_type

required, enumerated string, default=forever
Specifies the time duration for which this discount is attached to the subscription.

Possible values are

percentage

optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.

amount

optional, in cents, min=0
The value of the discount. The format of this value depends on the kind of currency.

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 values are

dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.

included_in_mrr

item_price_id

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.

ramp

always returned

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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

Retrieves a specific subscription ramp.

Sample Codes

curl  https://{site}.chargebee.com/api/v2/ramps/__test__rHsiT4rY2hC1A \
     -u {site_api_key}:

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/ramps/__test__rHsiT4rY2hC1A \
     -u {site_api_key}:

Sample Result [ JSON ]

{
    "ramp": {
        "id": "__test__rHsiT4rY2hC1A",
        "effective_from": "1635054328",
        "subscription_id": "__test__8asukSOXdv6kOj",
        "status": "scheduled",
        "description": "Schedule 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
            },
            {..}
        ]
    }
}

Method

ramp

always returned

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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

Deletes the specified subscription ramp. However, Chargebee only allows deleting a ramp if it does not conflict with future ramps on the subscription. The following checks are performed to ensure compatibility:

Condition	Restriction
The ramp contains `items_to_add[]`	The ramp cannot be deleted if any of the items in `items_to_add[]` are scheduled to be updated or removed in a subsequent ramp.
The ramp contains `coupons_to_add[]`	The ramp cannot be deleted if any of the coupons in `coupons_to_add[]` are scheduled to be removed in a subsequent ramp.
The ramp contains `discounts_to_add[]`	The ramp cannot be deleted if any of the discounts in `discounts_to_add[]` are scheduled to be removed in a subsequent ramp.

Sample Codes

curl  https://{site}.chargebee.com/api/v2/ramps/__test__rHsiT4rY2hC1A/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/ramps/__test__rHsiT4rY2hC1A/delete \
     -X POST  \
     -u {site_api_key}:

Sample Result [ JSON ]

{
    "ramp": {
        "id": "__test__rHsiT4rY2hC1A",
        "effective_from": "1635054328",
        "subscription_id": "__test__8asukSOXdv6kOj",
        "status": "scheduled",
        "description": "Schedule for first ramp",
        "created_at": "1635054328",
        "deleted": true,
        "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
            },
            {..}
        ]
    }
}

Method

ramp

always returned

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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

Lists the subscription ramps that match the criteria provided in the filter parameters.

Note

By default, the ramps are returned sorted in descending order (latest first) by updated_at.

Sample Codes

curl  https://{site}.chargebee.com/api/v2/ramps \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=12 \
     --data-urlencode "subscription_id[in]"=["__test__8asukSOXdv6kOj"]

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/ramps \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=12 \
     --data-urlencode "subscription_id[in]"=["__test__8asukSOXdv6kOj"]

Sample Result [ JSON ]

{
    "list": [
        {
            "ramp": {
                "id": "__test__rHsiT4rY2hC1A",
                "effective_from": "1635054328",
                "subscription_id": "__test__8asukSOXdv6kOj",
                "status": "scheduled",
                "description": "Schedule 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
                    },
                    {..}
                ]
            }
        },
        {..}
    ]
}

Method

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

include_deleted[]

optional, boolean, default=false

Specifies whether to include deleted resources in the response. Deleted resources are those with the deleted attribute set to true.

Caution

status or effective_from filters must not be passed when include_deleted is set to true.

sort_by

optional, string filter
Sorts based on the specified attribute.
Supported attributes : effective_from, updated_at
Supported sort-orders :

Example →
This will sort the result based on the 'effective_from' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

status

optional, string filter
Filter subscription ramps based on status.

Caution

The subscription_id filter must be passed when filtering by status.
status filter should not be passed when include_deleted is set to true.

Supported operators :

Example → SCHEDULED

subscription_id

required, string filter
Filter subscription ramps based on subscription_id.

Caution

This filter is mandatory when filtering by status or effective_from.

Supported operators :

Example → 8gsnbYfsMLds

effective_from

optional, timestamp(UTC) in seconds filter
Filter subscription ramps based on effective_from.

Caution

The subscription_id filter must be passed when filtering by effective_from.
effective_from filter should not be passed when include_deleted is set to true.

Supported operators :

Example → 1435054328

updated_at

optional, timestamp(UTC) in seconds filter
Filter subscription ramps based on updated_at.

Tip

Specify sort_by = updated_at (whether asc oor desc) for a faster response when using this filter.

Supported operators :

Example → 1435052328

ramp

always returned

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.
Total ramps limit: A subscription can have a maximum of 100 ramps at any given time, excluding deleted ramps.
Update subscription for items limit: changes_scheduled_at parameter cannot be set to a future date when the ramps feature is enabled.

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample ramp [ JSON ]

API Index URL GET

Model Class

Ramp attributes

Consent Fields for Ramp

Custom Fields for Ramp

Create a subscription ramp ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a subscription ramp ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a subscription ramp ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete a subscription ramp ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List subscription ramps ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL