---
title: "Switch the caller's existing subscription to a different paid plan."
method: POST
path: "/v1/billing/change-plan"
tags: ["Billing"]
---

# Switch the caller's existing subscription to a different paid plan.

`POST /v1/billing/change-plan`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/billing/change-plan`
- Auth: HTTP bearer

Requires `manage` scope. Refuses if the account has no active subscription (`no_subscription`, 409 — use `/v1/billing/checkout` to start one instead). `plan_id` must name a real, paid, currently-purchasable plan different from the account's current one (`bad_request`, 400, for an unknown, free, unpurchasable, or already-active plan_id). Upgrades swap the subscription's price immediately with no proration charge, billed in full next cycle (`effective: "immediately"`). Downgrades are scheduled for the next renewal so the caller keeps what they already paid for until the period ends (`effective: "at_period_end"`).

## Request body

- BillingChangePlanRequest
  - `plan_id` string, required: The paid plan id to switch to. Must differ from the account's current plan.

## Response `200`

Plan change applied or scheduled.

- object
  - `ok` true, required
  - `effective` 'immediately' | 'at_period_end', required

## Other responses

- `400`: Malformed request.
- `403`: Token lacks the required scope.
- `409`: `no_subscription` — no active subscription; checkout first.

---

[API](https://skmtc.dev/inboxy/apis/inboxy-api.md) · [All operations](https://skmtc.dev/inboxy/apis/inboxy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inboxy/apis/inboxy-api/revisions/25155a8dec0f?raw)