---
title: "Preview a plan change"
method: GET
path: "/gateway/subscriptions/{id}/plan-change/preview"
tags: ["Subscriptions"]
---

# Preview a plan change

`GET /gateway/subscriptions/{id}/plan-change/preview`

## Request

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

Quote moving a subscription to another plan. Read-only: nothing is charged or scheduled. The target must be a different subscription product in the same currency and billing interval, and the subscription must be `active` or `trialing`. An upgrade (higher price) is charged now, prorated; a downgrade switches at the current period end with nothing due today. Pass the returned `prorationDate` to the apply call so the charge matches this quote.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `targetLinkId` string, uuid, required

## Response `200`

The quote. Money fields are integer minor units.

- PlanChangePreview: Read-only quote for moving a subscription to another plan. Money is integer minor units.
  - `direction` 'upgrade' | 'downgrade' | 'revert', required: `upgrade` when the new plan costs more per cycle; `downgrade` otherwise; `revert` when the target is the current plan while a downgrade is pending (cancels it, nothing due).
  - `currency` string, required
  - `dueTodayMinor` integer, required: Charged now. Always 0 for a downgrade.
  - `dueTodayVatMinor` integer, required
  - `effectiveAt` string, date-time, required: Upgrade: now. Downgrade: the current period end.
  - `nextInvoiceMinor` integer, required: The next regular cycle invoice on the new plan.
  - `nextInvoiceVatMinor` integer, required
  - `nextInvoiceAt` string, date-time, required
  - `prorationDate` integer, required: Unix seconds. Echo it in the apply request so the charge matches this quote.

## 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)