Update Subscription

Use this endpoint to update your active subscription. In a single request you can switch to a new plan by providing a new price_id, apply a coupon_code for a discount, and optionally attach or update add-ons with specific quantities.

Before calling this endpoint, use the Get Subscription Proration Details endpoint to calculate and see the exact cost of the change before confirming. Use the Get Add-Ons endpoint to retrieve available add-on price_id values.

Common use cases:

• Plan upgrade — Switch from a Starter to a Basic plan mid-cycle by passing the new plan's price_id. The billing system handles proration automatically.
• Coupon code application — Pass a coupon_code alongside the new price_id to apply a discount to your updated subscription. Pass null if no coupon is being applied.
• Add-on attachment — Include an add_ons array to attach feature extensions like SMS credits to your subscription at the same time as a plan change, or independently.
• Add-on quantity update — Change the quantity of an existing add-on (e.g. increase your SMS credits from 10 to 20) by passing the same price_id with the updated quantity.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

• On success, you receive a 200 with a confirmation message. Both data and meta are null — the message alone confirms the update was applied.
• The add_ons field is optional — omit it entirely from the request body if only the plan is being changed.
• If your subscription ID is not found, a 422 is returned with data.fields.subscription_id containing the error detail.
• If authorization fails, a 401 is returned.