Settings
API Version
Product Catalog
Library

Ramps

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 GET

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

Model Class

Chargebee\Resources\Ramp\Ramp

Ramp attributes

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.

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.

Show all values[+]
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_update
Show attributes [+]
optional, list of items_to_update
Details about the item prices updated in the subscription through this ramp.
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.
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.

status_transition_reason
Show attributes [+]
optional, status_transition_reason
Detailed reason for the status transition of a ramp to draft and failed status.
id id
string, max chars=50
A unique and immutable identifier for the ramp.
description description
optional, string, max chars=250
A brief summary of the pricing changes applied with this ramp.
subscription_id subscription_id
string, max chars=50
The ID of the subscription for which this ramp was created.
effective_from effective_from
timestamp(UTC) in seconds
Specifies the time when the changes to the subscription will be applied by executing the ramp.
status 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.

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.

Show all values[+]
created_at created_at
timestamp(UTC) in seconds
Timestamp indicating when this resource was created.
resource_version 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 updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this resource was last updated.
items_to_remove items_to_remove
optional, list of string
List of item prices removed from the subscription through this ramp.
coupons_to_remove coupons_to_remove
optional, list of string
List of coupons removed from the subscription through this ramp.
discounts_to_remove discounts_to_remove
optional, list of string
List of discounts removed from the subscription through this ramp.
deleted 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.

Consent Fields for Ramp

Custom Fields for Ramp

Create a subscription ramp

Idempotency Supported
Batch

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.

Notes

Sample Codes 
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->createForSubscription("__test__8asukSOXdv6kOj",[
    "effective_from" => 1635054328,
    "description" => "First ramp",
      "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
    ]
  ]
]);
$ramp = $result->ramp;
copy
Click to Copy
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->createForSubscription("__test__8asukSOXdv6kOj",[
    "effective_from" => 1635054328,
    "description" => "First ramp",
      "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
    ]
  ]
]);
$ramp = $result->ramp;

Sample Result [ JSON ]

Show more...
{
    "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

Method

$chargebee->ramp->createForSubscription(<subscription_id>,[<param name> : <value>,<param name> : <value> ...])

Input Parameters

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.
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
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.
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.
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
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.
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.
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
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
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).
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[+]
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.
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.
apply_on
required, 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.
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[+]
duration_type
required, 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.
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[+]
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.
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[+]
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.

Returns

ramp ramp
always returned
Resource object representing ramp

Sample admin console URL

https://{site}.chargebee.com/admin-console/ramps/123x

Update a subscription ramp

Idempotency Supported
Batch

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

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

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

Notes

Sample Codes 
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->update("__test__rHsiT4rY2hC1A",[
    "effective_from" => 1635054328,
    "description" => "Updated description for first ramp",
      "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
    ]
  ]
]);
$ramp = $result->ramp;
copy
Click to Copy
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->update("__test__rHsiT4rY2hC1A",[
    "effective_from" => 1635054328,
    "description" => "Updated description for first ramp",
      "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
    ]
  ]
]);
$ramp = $result->ramp;

Sample Result [ JSON ]

Show more...
{
    "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

Method

$chargebee->ramp->update(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])

Input Parameters

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.
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
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.
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.
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
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.
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.
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
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
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).
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[+]
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.
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.
apply_on
required, 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.
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[+]
duration_type
required, 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.
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[+]
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.
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[+]
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.

Returns

ramp ramp
always returned
Resource object representing ramp

Sample admin console URL

https://{site}.chargebee.com/admin-console/ramps/123x

Retrieve a subscription ramp

Retrieves a specific subscription ramp.

Notes

Sample Codes 
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->retrieve("__test__rHsiT4rY2hC1A");
$ramp = $result->ramp;
copy
Click to Copy
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->retrieve("__test__rHsiT4rY2hC1A");
$ramp = $result->ramp;

Sample Result [ JSON ]

Show more...
{
    "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/{ramp-id}

Method

$chargebee->ramp->retrieve(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])

Returns

ramp ramp
always returned
Resource object representing ramp

Sample admin console URL

https://{site}.chargebee.com/admin-console/ramps/123x

Delete a subscription ramp

Idempotency Supported
Batch

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.

Notes

Sample Codes 
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->delete("__test__rHsiT4rY2hC1A");
$ramp = $result->ramp;
copy
Click to Copy
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->delete("__test__rHsiT4rY2hC1A");
$ramp = $result->ramp;

Sample Result [ JSON ]

Show more...
{
    "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

Method

$chargebee->ramp->delete(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])

Returns

ramp ramp
always returned
Resource object representing ramp

Sample admin console URL

https://{site}.chargebee.com/admin-console/ramps/123x

List subscription ramps

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.

Notes

Sample Codes 
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->all([
    "limit" => 12,
  "subscription_id" => [ "in" => ["__test__8asukSOXdv6kOj"] ]
]);
foreach($result->list as $entry){
  $ramp = $entry->ramp;
}
copy
Click to Copy
require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
  "site" => "{site}",
  "apiKey" => "{apiKey}",
]);

$result = $chargebee->ramp()->all([
    "limit" => 12,
  "subscription_id" => [ "in" => ["__test__8asukSOXdv6kOj"] ]
]);
foreach($result->list as $entry){
  $ramp = $entry->ramp;
}

Sample Result [ JSON ]

Show more...
{
    "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

Method

$chargebee->ramp->all([<param name> : <value>,<param name> : <value> ...])

Input Parameters

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[<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, 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 :
Supported operators : in, is

Example → "status[in] = "SCHEDULED"
in[<operator>]
optional, string filter
Possible values are :
Supported operators :

Example →
is[<operator>]
optional, enumerated string filter
Possible values are : scheduled, succeeded, failed, draft
Supported operators :

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

 Possible values are :
Supported operators : in, is

Example → "subscription_id[in] = "8gsnbYfsMLds"
in[<operator>]
optional, string filter
Possible values are :
Supported operators :

Example →
is[<operator>]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
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.
 Possible values are :
Supported operators : after, before, on, between

Example → "effective_from[after] = "1435054328"
after[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
before[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
on[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
between[<operator>]
optional, string filter
Possible values are :
Supported operators :

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

 Possible values are :
Supported operators : after, before, on, between

Example → "updated_at[after] = "1435052328"
after[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
before[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
on[<operator>]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
between[<operator>]
optional, string filter
Possible values are :
Supported operators :

Example →

Returns

ramp ramp
always returned
Resource object representing ramp
next_offset 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 admin console URL

https://{site}.chargebee.com/admin-console/ramps/123x