---
title: "Quote a plan change before submitting it"
method: POST
path: "/api/v1/billing/plan-change/preview"
tags: ["billing"]
---

# Quote a plan change before submitting it

`POST /api/v1/billing/plan-change/preview`

## Request

- Base URL: `https://api.cadencz.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cadencz.com/api/v1/billing/plan-change/preview`
- Auth: HTTP bearer

Returns Dodo's own quote for switching to `tier`. Every plan change is effective immediately: an upgrade charges the prorated difference on Dodo's hosted payment page, a downgrade charges nothing and leaves the unused value as credit toward future renewals. This is what the confirmation dialog shows before the customer commits to anything.

## Request body

- PlanChangePreviewRequest
  - `tier` string, required
  - `billing_period` 'monthly' | 'yearly'

## Response `200`

Successful Response

- PlanChangePreviewRead: Dodo's own quote for a switch, shown before the customer authorises it. Amounts are provider minor units in `currency`. When `needs_resume` is set there are no amounts to show: Dodo will not quote a subscription that is on its way out, so the switch resumes it first and the figures then come from Dodo's own payment page.
  - `tier` string, required
  - `tier_name` string, required
  - `billing_period` 'monthly' | 'yearly', required
  - `effective_at` 'immediately' | 'next_billing_date', required
  - `charges_today` boolean, required
  - `immediate_total_minor` integer, required
  - `currency` string, required
  - `tax_minor` integer, required
  - `customer_credits_minor` integer, required
  - `recurring_pre_tax_minor` integer, nullable, required
  - `recurring_currency` string, nullable, required
  - `next_billing_date` string, nullable, required
  - `needs_resume` boolean
  - `resumes_current_plan` boolean
  - `needs_fresh_checkout` boolean
  - `needs_payment_fix` boolean

## Other responses

- `400`: The request payload is invalid.
- `401`: Missing or invalid Supabase bearer token.
- `409`: The requested state transition is not allowed.
- `422`: Validation Error
- `502`: The upstream provider rejected the request.
- `503`: Required infrastructure or provider config is unavailable.

---

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