---
title: "Preview subscription plan change"
method: POST
path: "/subscriptions/{id}/change/preview"
tags: ["Subscriptions"]
---

# Preview subscription plan change

`POST /subscriptions/{id}/change/preview`

Use when showing a customer the cost of a plan change before they confirm (e.g. upgrade/downgrade preview with proration).

## Path parameters

- `id` string, required

## Request body

- SubscriptionChangeRequest — Request object for changing a subscription plan (upgrade/downgrade)
  - `billing_cadence` 'RECURRING', required
  - `billing_cycle` 'anniversary' | 'calendar', required
  - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'ONETIME', required
  - `billing_period_count` integer — billing_period_count is the billing period count for the new subscription
  - `change_at` 'immediate' | 'end_of_period'
  - `metadata` object — metadata contains additional key-value pairs for storing extra information
  - `proration_behavior` 'create_prorations' | 'none', required
  - `target_plan_id` string, required — target_plan_id is the ID of the new plan to change to (required)

## Response `200`

OK

- SubscriptionChangePreviewResponse — Response showing the financial impact of a subscription plan change
  - `change_type` 'upgrade' | 'downgrade' | 'lateral'
  - `current_plan` PlanSummary
    - `description` string — description of the plan
    - `id` string — id of the plan
    - `lookup_key` string — lookup_key of the plan
    - `name` string — name of the plan
  - `effective_date` string, date-time — effective_date is when the change would take effect
  - `metadata` object — metadata from the request
  - `new_billing_cycle` BillingCycleInfo
    - `billing_anchor` string, date-time — billing_anchor is the new billing anchor
    - `billing_cadence` 'RECURRING'
    - `billing_period` 'MONTHLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY' | 'QUARTERLY' | 'HALF_YEARLY' | 'ONETIME'
    - `billing_period_count` integer — billing_period_count is the billing period count
    - `period_end` string, date-time — period_end is the end of the new billing period
    - `period_start` string, date-time — period_start is the start of the new billing period
  - `next_invoice_preview` InvoicePreview
    - `currency` string — currency is the currency for all amounts
    - `due_date` string, date-time — due_date is when the invoice would be due
    - `line_items` InvoiceLineItemPreview[] — line_items contains preview of line items
      - `amount` string — amount for this line item
      - `description` string — description of the line item
      - `is_proration` boolean — is_proration indicates if this line item is a proration
      - `period_end` string, date-time — period_end for this line item (if applicable)
      - `period_start` string, date-time — period_start for this line item (if applicable)
      - `quantity` string — quantity for this line item
      - `unit_price` string — unit_price for this line item
    - `subtotal` string — subtotal is the subtotal amount before taxes
    - `tax_amount` string — tax_amount is the total tax amount
    - `total` string — total is the total amount including taxes
  - `proration_details` ProrationDetails
    - `charge_amount` string — charge_amount is the charge amount for the new subscription
    - `charge_description` string — charge_description describes what the charge is for
    - `credit_amount` string — credit_amount is the credit amount from the old subscription
    - `credit_description` string — credit_description describes what the credit is for
    - `currency` string — currency is the currency for all amounts
    - `current_period_end` string, date-time — current_period_end is the end of the current billing period
    - `current_period_start` string, date-time — current_period_start is the start of the current billing period
    - `days_remaining` integer — days_remaining is the number of days remaining in the current period
    - `days_used` integer — days_used is the number of days used in the current period
    - `net_amount` string — net_amount is the net amount (charge - credit)
    - `proration_date` string, date-time — proration_date is the date used for proration calculations
  - `subscription_id` string — subscription_id is the ID of the subscription being changed
  - `target_plan` PlanSummary
    - `description` string — description of the plan
    - `id` string — id of the plan
    - `lookup_key` string — lookup_key of the plan
    - `name` string — name of the plan
  - `warnings` string[] — warnings contains any warnings about the change

## Other responses

- `400` — Invalid request
- `404` — Resource not found
- `500` — Server error

---

[API](https://skmtc.net/flexprice/apis/flexprice-api.md) · [All operations](https://skmtc.net/flexprice/apis/flexprice-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flexprice/flexprice-api/versions/f0601ed97bd3/schema)