---
title: "Lower the tier, cancel at the end of the period or switch to the spending cap right away; raising the tier, resuming a plan that is set to end or switching to top-ups from the card returns a confirmUrl for a person to confirm"
method: PATCH
path: "/v1/subscription"
---

# Lower the tier, cancel at the end of the period or switch to the spending cap right away; raising the tier, resuming a plan that is set to end or switching to top-ups from the card returns a confirmUrl for a person to confirm

`PATCH /v1/subscription`

## Request

- Base URL: `https://volai.cz`
- URL: `https://volai.cz/v1/subscription`
- Auth: HTTP bearer

Changes the plan without charging the card. These apply immediately, because they never raise what can be charged: lowering `tier` (it takes effect from the next period, `nextTier` shows it), `cancelAtPeriodEnd: true` (no further charge, the credit stays usable until `periodEnd`) and `exhaustionMode: "cap"` (also turns auto top-up off). Raising `tier`, `cancelAtPeriodEnd: false` on a plan that is set to end (resuming it) and `exhaustionMode: "topup"` do NOT apply: the call returns 409 `subscription_confirmation_required` and nothing in the request changes. The error body carries `confirmUrl`, a link to the portal page where a person signed in to the account confirms the change; the link is valid for 24 hours and works once. Send changes that need confirmation one per request. A request that changes nothing (resuming a plan that is not set to end, `topup` while top-ups already run) succeeds without a confirmation.

## Request body

- object
  - `tier` '490' | '990' | '1990': Tier to switch to from the next period (nextTier shows it); the current period and its credit stay as they are. A lower tier applies immediately; a higher one returns 409 subscription_confirmation_required with a confirmUrl for a person to confirm.
  - `cancelAtPeriodEnd` boolean: true cancels at the end of the period: no further charge and the credit stays usable until periodEnd. false resumes a plan that is set to end and returns 409 subscription_confirmation_required with a confirmUrl; it changes nothing when the plan is not set to end.
  - `exhaustionMode` 'topup' | 'cap': cap switches to the spending cap right away and turns auto top-up off. topup (buying credit with the saved card once the monthly credit is used up) returns 409 subscription_confirmation_required with a confirmUrl unless top-ups already run.

## Response `200`

Updated monthly plan

- object
  - `subscription` object, required
    - `tier` '490' | '990' | '1990', required: Tier that is paid for the current period.
    - `status` 'active' | 'past_due' | 'canceled', required: active: the current period is paid. past_due: the last renewal payment failed and retries continue (monthly credit is 0 until it is paid; pay by hand with POST /v1/subscription/pay). canceled: the plan has ended.
    - `periodStart` string, required: Start of the paid period as an ISO 8601 string in UTC. Unlike the *At fields elsewhere in the API, which are Unix milliseconds, this is a string.
    - `periodEnd` string, required: End of the paid period as an ISO 8601 string in UTC: when the saved card is charged for the next one, unless the plan is canceled.
    - `monthlyCreditHal` number, required: Monthly credit of the paid tier, in hellers.
    - `monthlyRemainingHal` number, required: What is left of the monthly credit in this period, in hellers. It is spent first and what remains expires at the end of the period.
    - `exhaustionMode` 'topup' | 'cap', required: What happens once the monthly credit is used up. topup: credit is bought with the saved card (the account's auto top-up). cap: nothing more is bought; outbound actions fail with subscription_cap_reached until the next renewal.
    - `cancelAtPeriodEnd` boolean, required: true when the plan is canceled and ends at periodEnd without another charge. Until then the monthly credit stays usable.
    - `nextTier` '490' | '990' | '1990', nullable, required: Tier that takes effect from the next period, or null when the tier does not change.
    - `card` object, required: The saved card that renewals are charged to. Only the brand and the last four digits are ever returned.
      - `brand` string, nullable, required: Card brand, for example visa, or null when unknown.
      - `last4` string, nullable, required: Last four digits of the saved card, or null when unknown.

## Other responses

- `400`: Error codes: validation (request), invalid_tier (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: subscription_missing (account).
- `409`: Error codes: subscription_canceled (account), subscription_confirmation_required (request).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `503`: Error codes: ledger_unavailable (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)