Sign in
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'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'ONETIME' 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

OK

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 4 of the 12 revisions of this API.11315

  • f62d8a5fe7cf6See the full diff
    • ●

      removed the optional property details from the response with the 400 status

      response-optional-property-removed

    • ●

      removed the optional property details from the response with the 404 status

      response-optional-property-removed

    • ●

      removed the optional property details from the response with the 500 status

      response-optional-property-removed

    • ●

      added the new too_many_requests enum value to the code response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new too_many_requests enum value to the code response property for the response status 404

      response-property-enum-value-added

    • ●

      added the new too_many_requests enum value to the code response property for the response status 500

      response-property-enum-value-added

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 0cb3425d6580112See the full diff
    • ▲

      removed the enum value ONETIME of the request property billing_cadence

      request-property-enum-value-removed

    • ●

      added the new ONETIME enum value to the new_billing_cycle/billing_period response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new ONETIME enum value to the request property billing_period

      request-property-enum-value-added

    • ○

      removed the ONETIME enum value from the new_billing_cycle/billing_cadence response property for the response status 200

      response-property-enum-value-removed

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4ded3711f401612See the full diff
    • ●

      removed the optional property error from the response with the 400 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 404 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 500 status

      response-optional-property-removed

    • ●

      removed the optional property success from the response with the 400 status

      response-optional-property-removed

    • ●

      removed the optional property success from the response with the 404 status

      response-optional-property-removed

    • ●

      removed the optional property success from the response with the 500 status

      response-optional-property-removed

    • ○

      added the optional property code to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property code to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property code to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property details to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property details to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property details to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property http_status_code to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property http_status_code to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property http_status_code to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property message to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property message to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property message to the response with the 500 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

  • bc91c95fbb1a1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog