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.
status
as scheduled
.changes_scheduled_at
parameter cannot be set to a future date when the ramps feature is enabled.{
"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
}
]
}
Chargebee\Resources\Ramp\Ramp
Excluding deleted ramps, a subscription can have a maximum of 12 ramps in the scheduled
status
.
draft
status when the associated subscription is updated. The reason for the draft status can be explained in the status_transition_reason Ramps in draft state will not be executed.
include_deleted
set to true
. Allowed only when both of these conditions are met:
pricing_model
of the item price is either tiered
, volume
, or stairstep
.Overrides the item_tiers
for specific item_prices
of the subscription.
Creates a ramp for a subscription.
paused
or cancelled
status
.status
as scheduled
.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;
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;
$chargebee->ramp->createForSubscription(<subscription_id>,[<param name> : <value>,<param name> : <value> ...])
effective_from
of two consecutive ramps.pause_date
or cancelled_at
.Ensure this list does not include:
Ensure this list does not include discounts already removed by a previous ramp.
Ensure this list does not include:
effective_from
time.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. Ensure this list:
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. item_price
for which the tier price is being overridden. The identifier must correspond to an item_price
listed in either items_to_add
or items_to_update
.
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. 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. 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
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).limited_period
coupons only. 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
.period
and period_unit
.period_units
. Applicable only when duration_type
is limited_period
. period
. Applicable only when duration_type
is limited_period
. 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
= specific_item_price
. 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
Step 2: Update ramp with new values
succeeded
or failed
status
.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;
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;
$chargebee->ramp->update(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])
effective_from
of two consecutive ramps.pause_date
or cancelled_at
.Ensure this list does not include:
Ensure this list does not include discounts already removed by a previous ramp.
Ensure this list does not include:
effective_from
time.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. Ensure this list:
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. item_price
for which the tier price is being overridden. The identifier must correspond to an item_price
listed in either items_to_add
or items_to_update
.
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. 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. 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
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).limited_period
coupons only. 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
.period
and period_unit
.period_units
. Applicable only when duration_type
is limited_period
. period
. Applicable only when duration_type
is limited_period
. 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
= specific_item_price
. 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;
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;
$chargebee->ramp->retrieve(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])
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. |
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;
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;
$chargebee->ramp->delete(<ramp_id>,[<param name> : <value>,<param name> : <value> ...])
Lists the subscription ramps that match the criteria provided in the filter parameters.
By default, the ramps are returned sorted in descending order (latest first) by updated_at
.
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; }
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; }
$chargebee->ramp->all([<param name> : <value>,<param name> : <value> ...])
Specifies whether to include deleted resources in the response. Deleted resources are those with the deleted
attribute set to true
.
status
or effective_from
filters must not be passed when include_deleted
is set to true
.
status
.subscription_id
filter must be passed when filtering by status
.status
filter should not be passed when include_deleted
is set to true
.effective_from
. 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
.updated_at
.Specify sort_by
= updated_at
(whether asc
oor desc
) for a faster response when using this filter.