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
        }
    ]
}

API Index URL

https://{site}.chargebee.com/api/v2/ramps

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

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

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

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

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

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

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

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

charge_on_event

Possible values are

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

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

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

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

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

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.

contract_term
Show attributes [+]

optional, contract_term
An object that specifies the contract term details.

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

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.

contract_term

optional, contract_term
An object that specifies the contract term details.

status_transition_reason

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

Try in API Explorer

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 Request

Try in API Explorer

Only for Java

copy full code

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

copy

Click to Copy

200:

STATUS

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

URL Format POST

https://{site}.chargebee.com/api/v2/subscriptions/{subscription-id}/create_ramp

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[[0..n]][0..n]

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[[0..n]][0..n]

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[[0..n]][0..n]

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.

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string, default=renew

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer

contract_term[renewal_billing_cycles]

optional, integer

items_to_add

Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices.
pass parameters as items_to_add[<param name>][<idx:0..n>]

items_to_add[item_price_id][0..n]

required, string, max chars=100

items_to_add[quantity][0..n]

optional, integer, min=1

items_to_add[quantity_in_decimal][0..n]

optional, string, max chars=33

items_to_add[unit_price][0..n]

optional, in cents, min=0

items_to_add[unit_price_in_decimal][0..n]

optional, string, max chars=39

items_to_add[billing_cycles][0..n]

optional, integer, min=0

items_to_add[service_period_days][0..n]

optional, integer, min=1, max=730

items_to_add[charge_on_event][0..n]

optional, enumerated string

Possible values are

items_to_add[charge_once][0..n]

optional, boolean

items_to_add[charge_on_option][0..n]

optional, enumerated string

Possible values are

items_to_update

Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
pass parameters as items_to_update[<param name>][<idx:0..n>]

items_to_update[item_price_id][0..n]

required, string, max chars=100

items_to_update[quantity][0..n]

optional, integer, min=1

items_to_update[quantity_in_decimal][0..n]

optional, string, max chars=33

items_to_update[unit_price][0..n]

optional, in cents, min=0

items_to_update[unit_price_in_decimal][0..n]

optional, string, max chars=39

items_to_update[billing_cycles][0..n]

optional, integer, min=0

items_to_update[service_period_days][0..n]

optional, integer, min=1, max=730

items_to_update[charge_on_event][0..n]

optional, enumerated string

Possible values are

items_to_update[charge_once][0..n]

optional, boolean

items_to_update[charge_on_option][0..n]

optional, enumerated string

Possible values are

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

optional, string, max chars=100

item_tiers[starting_unit][0..n]

optional, integer, min=1

item_tiers[ending_unit][0..n]

optional, integer

item_tiers[price][0..n]

optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39

item_tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

item_tiers[package_size][0..n]

optional, integer, min=1

coupons_to_add

Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices.
pass parameters as coupons_to_add[<param name>][<idx:0..n>]

coupons_to_add[coupon_id][0..n]

optional, string, max chars=100

coupons_to_add[apply_till][0..n]

optional, timestamp(UTC) in seconds

discounts_to_add

Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
pass parameters as discounts_to_add[<param name>][<idx:0..n>]

discounts_to_add[apply_on][0..n]

required, enumerated string

Possible values are

discounts_to_add[duration_type][0..n]

required, enumerated string, default=forever

Possible values are

discounts_to_add[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts_to_add[amount][0..n]

optional, in cents, min=0

discounts_to_add[period][0..n]

optional, integer, min=1

discounts_to_add[period_unit][0..n]

optional, enumerated string

Possible values are

discounts_to_add[included_in_mrr][0..n]

optional, boolean

discounts_to_add[item_price_id][0..n]

optional, string, max chars=100

ramp

always returned
Resource object representing ramp

Try in API Explorer

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 Request

Try in API Explorer

Only for Java

copy full code

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

copy

Click to Copy

200:

STATUS

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

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[[0..n]][0..n]

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[[0..n]][0..n]

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[[0..n]][0..n]

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.

contract_term

Parameters for contract_term
pass parameters as contract_term[<param name>]

contract_term[action_at_term_end]

optional, enumerated string, default=renew

Possible values are

contract_term[cancellation_cutoff_period]

optional, integer

contract_term[renewal_billing_cycles]

optional, integer

items_to_add

Parameters for items_to_add. Multiple items_to_add can be passed by specifying unique indices.
pass parameters as items_to_add[<param name>][<idx:0..n>]

items_to_add[item_price_id][0..n]

required, string, max chars=100

items_to_add[quantity][0..n]

optional, integer, min=1

items_to_add[quantity_in_decimal][0..n]

optional, string, max chars=33

items_to_add[unit_price][0..n]

optional, in cents, min=0

items_to_add[unit_price_in_decimal][0..n]

optional, string, max chars=39

items_to_add[billing_cycles][0..n]

optional, integer, min=0

items_to_add[service_period_days][0..n]

optional, integer, min=1, max=730

items_to_add[charge_on_event][0..n]

optional, enumerated string

Possible values are

items_to_add[charge_once][0..n]

optional, boolean

items_to_add[charge_on_option][0..n]

optional, enumerated string

Possible values are

items_to_update

Parameters for items_to_update. Multiple items_to_update can be passed by specifying unique indices.
pass parameters as items_to_update[<param name>][<idx:0..n>]

items_to_update[item_price_id][0..n]

required, string, max chars=100

items_to_update[quantity][0..n]

optional, integer, min=1

items_to_update[quantity_in_decimal][0..n]

optional, string, max chars=33

items_to_update[unit_price][0..n]

optional, in cents, min=0

items_to_update[unit_price_in_decimal][0..n]

optional, string, max chars=39

items_to_update[billing_cycles][0..n]

optional, integer, min=0

items_to_update[service_period_days][0..n]

optional, integer, min=1, max=730

items_to_update[charge_on_event][0..n]

optional, enumerated string

Possible values are

items_to_update[charge_once][0..n]

optional, boolean

items_to_update[charge_on_option][0..n]

optional, enumerated string

Possible values are

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

optional, string, max chars=100

item_tiers[starting_unit][0..n]

optional, integer, min=1

item_tiers[ending_unit][0..n]

optional, integer

item_tiers[price][0..n]

optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

optional, string, max chars=39

item_tiers[pricing_type][0..n]

optional, enumerated string

Possible values are

item_tiers[package_size][0..n]

optional, integer, min=1

coupons_to_add

Parameters for coupons_to_add. Multiple coupons_to_add can be passed by specifying unique indices.
pass parameters as coupons_to_add[<param name>][<idx:0..n>]

coupons_to_add[coupon_id][0..n]

optional, string, max chars=100

coupons_to_add[apply_till][0..n]

optional, timestamp(UTC) in seconds

discounts_to_add

Parameters for discounts_to_add. Multiple discounts_to_add can be passed by specifying unique indices.
pass parameters as discounts_to_add[<param name>][<idx:0..n>]

discounts_to_add[apply_on][0..n]

required, enumerated string

Possible values are

discounts_to_add[duration_type][0..n]

required, enumerated string, default=forever

Possible values are

discounts_to_add[percentage][0..n]

optional, double, min=0.01, max=100.0

discounts_to_add[amount][0..n]

optional, in cents, min=0

discounts_to_add[period][0..n]

optional, integer, min=1

discounts_to_add[period_unit][0..n]

optional, enumerated string

Possible values are

discounts_to_add[included_in_mrr][0..n]

optional, boolean

discounts_to_add[item_price_id][0..n]

optional, string, max chars=100

ramp

always returned
Resource object representing ramp

Try in API Explorer

Retrieves a specific subscription ramp.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

Sample Response [ 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
            },
            {..}
        ],
        "contract_term": {
            "cancellation_cutoff_period": 7,
            "renewal_billing_cycles": 12,
            "action_at_term_end": "renew"
        }
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/ramps/{ramp-id}

ramp

always returned
Resource object representing ramp

Try in API Explorer

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 Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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

copy

Click to Copy

200:

STATUS

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

URL Format POST

https://{site}.chargebee.com/api/v2/ramps/{ramp-id}/delete

ramp

always returned
Resource object representing ramp

Try in API Explorer

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 Request

Try in API Explorer

Only for Java

copy full code

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"]

copy

Click to Copy

200:

STATUS

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

URL Format GET

https://{site}.chargebee.com/api/v2/ramps

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
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.

sort_by[<sort-order>]

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

Example → sort_by[asc] = "effective_from"
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[<operator>]

optional, enumerated 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.

Possible values are : scheduled, succeeded, failed, draft
Supported operators : is, in

Example → status[is] = "SCHEDULED"

subscription_id[<operator>]

required, string filter
Filter subscription ramps based on subscription_id.

Caution

This filter is mandatory when filtering by status or effective_from.

Supported operators : is, in

Example → subscription_id[is] = "8gsnbYfsMLds"

effective_from[<operator>]

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 : after, before, on, between

Example → effective_from[after] = "1435054328"

updated_at[<operator>]

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 : after, before, on, between

Example → updated_at[after] = "1435052328"

ramp

always returned
Resource object representing ramp

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

Model Class

Ramp attributes

Consent Fields for Ramp

Custom Fields for Ramp

Create a subscription ramp ¶

Sample Response [ 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 ¶

Sample Response [ 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 ¶

Sample Response [ 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 ¶

Sample Response [ 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 ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL