Subscriptions

Preview subscription plan change

Use when showing a customer the cost of a plan change before they confirm (e.g. upgrade/downgrade preview with proration).

post/subscriptions/{id}/change/preview

Path parameters

idstring required

Subscription ID

Request body

billing_cadence'RECURRING' required

billing_cycle'anniversary' | 'calendar' required

billing_period_countinteger

billing_period_count is the billing period count for the new subscription

change_at'immediate' | 'end_of_period'

metadataobject

metadata contains additional key-value pairs for storing extra information

proration_behavior'create_prorations' | 'none' required

target_plan_idstring required

target_plan_id is the ID of the new plan to change to (required)

Response

change_type'upgrade' | 'downgrade' | 'lateral'

effective_datestring date-time

effective_date is when the change would take effect

metadataobject

metadata from the request

subscription_idstring

subscription_id is the ID of the subscription being changed

warningsstring[]

warnings contains any warnings about the change

Changes

Changed in 7 of the 149 revisions of this API.231925

Jul 15, 2026f8ecf435d25d3See the full diff
- ●
  added the new not_implemented enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new not_implemented enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new not_implemented enum value to the response property for the response status
  response-property-enum-value-added
Jul 9, 2026646d6658479b2See the full diff
- ○
  the request property default value 1 was removed
  request-property-default-value-removed
- ○
  the response's property default value 1 was removed for the status
  response-property-default-value-removed
Jul 9, 20267d57386313c7536See the full diff
- ▲
  request property was restricted to a list of enum values
  request-property-became-enum
- ▲
  request property was restricted to a list of enum values
  request-property-became-enum
- ▲
  the request property type changed from no type to string
  request-property-type-changed
- ▲
  the request property type changed from no type to string
  request-property-type-changed
- ▲
  the response's property type changed from no type to string for status
  response-property-type-changed
- ●
  added the new downgrade enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new lateral enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new upgrade enum value to the response property for the response status
  response-property-enum-value-added
- ○
  the request property default value 1 was added
  request-property-default-value-added
- ○
  added the new create_prorations enum value to the request property
  request-property-enum-value-added
- ○
  added the new end_of_period enum value to the request property
  request-property-enum-value-added
- ○
  added the new immediate enum value to the request property
  request-property-enum-value-added
- ○
  added the new none enum value to the request property
  request-property-enum-value-added
- ○
  the response's property default value 1 was added for the status
  response-property-default-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 9, 20264b1a811c4179173See the full diff
- ▲
  removed the enum value create_prorations of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value end_of_period of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value immediate of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value none of the request property
  request-property-enum-value-removed
- ▲
  the request property type changed from string to no type
  request-property-type-changed
- ▲
  the request property type changed from string to no type
  request-property-type-changed
- ▲
  the response's property type changed from string to no type for status
  response-property-type-changed
- ▲
  the response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the /// response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the /// response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ▲
  the / response's property format changed from date-time to no format for status
  response-property-type-changed
- ○
  removed the downgrade enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the lateral enum value from the response property for the response status
  response-property-enum-value-removed
- ○
  removed the upgrade enum value from the response property for the response status
  response-property-enum-value-removed
This revision also has 121 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 18, 20268ec2edea6b206See the full diff
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  added the new too_many_requests enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new too_many_requests enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new too_many_requests enum value to the response property for the response status
  response-property-enum-value-added
Apr 10, 20265856ed2fbdd6112See the full diff
- ▲
  removed the enum value ONETIME of the request property
  request-property-enum-value-removed
- ●
  added the new ONETIME enum value to the / response property for the response status
  response-property-enum-value-added
- ○
  added the new ONETIME enum value to the request property
  request-property-enum-value-added
- ○
  removed the ONETIME enum value from the / response property for the response status
  response-property-enum-value-removed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 6, 202695af41a12111612See the full diff
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history