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 RampJSON

Ramps attributes

required, string, max chars=50

A unique and immutable identifier for the ramp.

subscription_id

required, string, max chars=50

The ID of the subscription for which this ramp was created.

effective_from

required, timestamp(UTC) in seconds

Specifies the time when the changes to the subscription will be applied by executing the ramp.

status

required, enumerated string

The execution status of the ramp

scheduled

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

succeeded

The ramp completed successfully.

failed

The ramp did not complete because of an error.

draft

The ramp is moved to draft status when the associated subscription is updated. The reason for the draft status can be explained in the status_transition_reason

Note Ramps in draft state will not be executed.

created_at

required, 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, string

List of item prices removed from the subscription through this ramp.

coupons_to_remove

optional, string

List of coupons removed from the subscription through this ramp.

discounts_to_remove

optional, string

List of discounts removed from the subscription through this ramp.

deleted

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