<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Moves a Wix-billed workspace to another plan. Take new_product_id from wix_product_id in List plans. Only the workspace owner can change the plan.

<Warning>An upgrade takes effect now and charges the workspace's saved payment method right away, with no confirmation step. Check the amount first with Preview Wix plan change.</Warning>

• Upgrade (a bigger plan): the response has invoice_id. A declined card returns 402 with detail.error_type set to payment_failed, and an unpaid invoice on the plan returns 402 with past_due.
• Downgrade (a smaller plan): takes effect at the end of the billing period, and nothing is charged now. The response has is_downgrade set to true. A downgrade keeps the billing period, and only one change can be scheduled at a time. Undo it with Cancel scheduled plan change.

You can switch from monthly to yearly billing, but not from yearly to monthly. A downgrade also turns a plan that's set to end back to renewing.

To retry an upgrade safely, send an Idempotency-Key header and repeat it on the retry: Wix then charges the order once. Without the header, each request is a new charge attempt, so check Get billing info before you retry.

This works only for workspaces billed through Wix. For a Stripe-billed workspace, use Change plan. Wix billing is still rolling out, so this can return 404 for your account.

The base rate limit is 10 requests per hour per user. See Rate limits for the multiplier your plan gets.

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

{
  "new_product_id": "5f0c7a2e-3b91-4d6a-9e0f-2c8b1d4a7e63",
  "period_unit": "MONTH"
}

{
  "success": true,
  "is_downgrade": true,
  "invoice_id": "2025-0001234"
}