---
title: "Change the plan"
method: POST
path: "/gateway/subscriptions/{id}/plan-change"
tags: ["Subscriptions"]
---

# Change the plan

`POST /gateway/subscriptions/{id}/plan-change`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/subscriptions/{id}/plan-change`
- Auth: API key in header `x-api-key`

Apply a plan change quoted by the preview. Echo the preview's `prorationDate` so the amount charged matches the quote. An upgrade charges the prorated difference on the saved card now and the response carries the new per-cycle amount; a downgrade is scheduled for the current period end (`effectiveAt`) and charges nothing today. Idempotent on (subscription, target plan, prorationDate). Same plan, a non-active subscription, a different currency, or a different billing interval return `400`.

## Path parameters

- `id` string, uuid, required

## Request body

- PlanChangeRequest
  - `targetLinkId` string, uuid, required: The target product's payment-link id.
  - `prorationDate` integer, required: From the preview response.

## Response `200`

The applied change. Shape depends on `direction`.

- union
  - object
    - `direction` 'upgrade', required
    - `applied` true, required
    - `status` string, required: Subscription status after the change.
    - `unitAmountMinor` integer, required: New per-cycle amount.
    - `currency` string, required
  - object
    - `direction` 'downgrade', required
    - `applied` true, required
    - `effectiveAt` string, date-time, required: When the new plan starts: the current period end. Until then the subscription keeps its current plan and reports the change as `pendingPlanChange`.
    - `unitAmountMinor` integer, required: Per-cycle amount from `effectiveAt` on.
    - `currency` string, required
  - object
    - `direction` 'revert', required
    - `applied` true, required
    - `unitAmountMinor` integer, required: The current plan's per-cycle amount, unchanged.
    - `currency` string, required

## Other responses

- `400`: A required field is missing, out of range, or the wrong type. `ValidationPipe` also rejects any field not in the documented schema.
- `401`: Missing or invalid `x-api-key`.
- `403`: The key is valid but the resource belongs to a different organization.
- `404`: Resource not found (or not visible to your key; the two are not distinguished).

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)