---
title: "Change the plan"
method: PUT
path: "/v1/users/me/plan"
tags: ["Users"]
---

# Change the plan

`PUT /v1/users/me/plan`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/users/me/plan`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Choose `free`, `pro` or `business`.

An upgrade is charged for the price difference over the rest of the month, then takes effect; the month's statement nets that payment out. The saved card is charged at once, in its currency. With no saved card, or when the card needs authentication or is declined, nothing is charged and the answer carries a `checkout_url`: a hosted page that charges the upgrade and saves the card. The plan changes once it is paid; one left unpaid lapses at `expires_at`.

A downgrade takes effect when the month ends, and `next_plan` names it until then. A contract plan is changed by asking us.

## Request body

- UserPlanChangeRequest
  - `plan` 'free' | 'pro' | 'business', required

## Response `200`

The plan in effect and the one coming.

- UserPlanChange
  - `plan` 'free' | 'pro' | 'business' | 'enterprise', required: The plan in effect.
  - `next_plan` 'free' | 'pro' | 'business' | 'enterprise', required: The plan from next month.
  - `charged_usd` number, required: What the saved card was charged now; 0 when nothing was.
  - `checkout_url` string, uri, nullable, required: The hosted page the upgrade waits on, which charges it and saves the card; `null` when nothing waits.
  - `expires_at` string, date-time, nullable, required: When an unpaid `checkout_url` lapses.

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Missing or invalid credentials.
- `409`: A paid plan with nothing to charge now and no saved card for its statement (`payment_method_required`), or a contract plan (`plan_by_contract`).
- `502`: The payment provider could not be reached (`payment_provider_error`).
- `503`: Card payments are not available on this deployment (`payments_not_configured`), or the exchange rate for a card charged in reais could not be read (`exchange_rate_unavailable`); the plan is unchanged.

---

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