Subscriptions

Execute subscription plan change

Use when applying a plan change (e.g. upgrade or downgrade). Executes proration and generates invoice or credit as needed.

post/subscriptions/{id}/change/execute

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 took effect

is_scheduledboolean

is_scheduled indicates if the change was scheduled or executed immediately

metadataobject

metadata from the request

schedule_idstring

schedule_id is the ID of the created schedule (only if is_scheduled=true)

scheduled_atstring date-time

scheduled_at is when the change will execute (only if is_scheduled=true)

Changes

Changed in 7 of the 12 revisions of this API.23038

Jun 29, 2026cef2964c102c212See the full diff
- ●
  removed the optional property invoice/subscription/customer_timezone from the response with the 200 status
  response-optional-property-removed
- ●
  added the new VOIDED enum value to the invoice/payment_status response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property invoice/customer/integrations/items/metadata to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/customer/timezone to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/line_items/items/adjusted_entitlement_quantity to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/line_items/items/subscription_line_item_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/coupon_associations/items/coupon/coupon_code to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/coupon_associations/items/subscription_line_item to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/customer/integrations/items/metadata to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/customer/timezone to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/line_items/items/commitment_time_buckets to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/line_items/items/price/sequence to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/synced_price_sequence to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/timezone to the response with the 200 status
  response-optional-property-added
May 18, 2026f62d8a5fe7cf61See 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
- ○
  added the optional property invoice/issue_date to the response with the 200 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 18, 20260cb3425d6580196See the full diff
- ▲
  removed the enum value ONETIME of the request property billing_cadence
  request-property-enum-value-removed
- ●
  removed the optional property invoice/subscription/line_items/items/trial_period_days from the response with the 200 status
  response-optional-property-removed
- ●
  added the new ONETIME enum value to the invoice/line_items/items/commitment_info/duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the invoice/subscription/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the invoice/subscription/commitment_duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the invoice/subscription/line_items/items/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the invoice/subscription/line_items/items/commitment_duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the invoice/subscription/line_items/items/price/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new delegated_invoicing enum value to the invoice/subscription/subscription_type response property for the response status 200
  response-property-enum-value-added
- ●
  added the new grouped_invoicing enum value to the invoice/subscription/subscription_type 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
- ○
  added the optional property invoice/subscription/auto_invoice_threshold to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/line_items/items/addon_association_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription_customer_id to the response with the 200 status
  response-optional-property-added
- ○
  removed the ONETIME enum value from the invoice/subscription/billing_cadence response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the ONETIME enum value from the invoice/subscription/line_items/items/price/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
Apr 23, 202682f205e0f42922See the full diff
- ●
  removed the optional property invoice/subscription/line_items/items/price/trial_period from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property invoice/subscription/line_items/items/trial_period from the response with the 200 status
  response-optional-property-removed
- ○
  added the optional property invoice/subscription/line_items/items/price/trial_period_days to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/line_items/items/trial_period_days to the response with the 200 status
  response-optional-property-added
Apr 6, 20264ded3711f40111013See the full diff
- ▲
  the invoice/billing_period response's property type/format changed from string/date-time to string/ for status 200
  response-property-type-changed
- ●
  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 invoice/customer/parent_customer from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property invoice/customer/parent_customer_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property invoice/subscription/customer/parent_customer from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property invoice/subscription/customer/parent_customer_id from the response with the 200 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 invoice/subscription/subscription_type to the response with the 200 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
Apr 4, 2026d1860fe0ee6713See the full diff
- ●
  added the new SKIPPED enum value to the invoice/invoice_status response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property invoice/customer/integrations to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/last_computed_at to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property invoice/subscription/customer/integrations to the response with the 200 status
  response-optional-property-added
This revision also has 223 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Mar 20, 2026bc91c95fbb1a1See 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

Full history