---
title: "Preview a seat decrease at the next renewal"
method: POST
path: "/organizations/{organizationId}/seat-change/preview"
tags: ["Organizations"]
---

# Preview a seat decrease at the next renewal

`POST /organizations/{organizationId}/seat-change/preview`

## Request

- Base URL: `https://api.xfa.tech`
- URL: `https://api.xfa.tech/organizations/{organizationId}/seat-change/preview`
- Auth: HTTP bearer

Read-only evaluation of a self-service seat decrease (XFA-3787). target_seats is the seat total the admin wants from the next renewal date on. A refused decrease answers 200 with status blocked and the blockers; current_users, users_to_remove and minimum_seats say how far the People list allows the decrease.

## Path parameters

- `organizationId` string, required

## Request body

- SeatChangeRequest
  - `target_seats` integer, required: The seat total the admin wants from the next renewal on (not the number to remove)
  - `current_seats` integer: The committed seats the admin saw (current_seats of the preview). Required on confirm, where a different count answers 409; ignored by the preview.
  - `request_id` string: Optional idempotency key (or the Idempotency-Key header). If omitted, the API Gateway request id is forwarded to billing. The requester is always taken from the caller's token.

## Response `200`

The evaluated decrease; status blocked with blockers when it is refused

- SeatChangeResponse
  - `status` string: One of scheduled, applied, canceled, superseded (stored) or blocked (only reported by a preview or a refused confirmation). billing_seat_change events also use warning.
  - `message` string
  - `change_id` string
  - `request_id` string
  - `requested_at` string
  - `requested_by_email` string
  - `requested_by_user_id` string
  - `billing_cycle` 'monthly' | 'yearly'
  - `current_seats` integer: Committed seats - the license count plus pending_added_seats
  - `pending_added_seats` integer: Seats bought on the current cycle that are not finalized yet
  - `target_seats` integer
  - `seats_removed` integer
  - `current_users` integer: People in the People list (0 when it was not read)
  - `users_to_remove` integer: People to remove before target_seats is allowed
  - `free_users` integer
  - `minimum_seats` integer: The lowest target accepted now - the People count, the free users, the plan minimum, 1
  - `effective_date` string: The next renewal date, 20060102
  - `pricing` SeatChangePricing: Per billing cycle: billed seats (seats less free users) times the unit price of the current cycle, before discounts and VAT.
    - `currency` 'EUR' | 'USD' | 'GBP': Supported currencies
    - `unit_price` number, float
    - `recurring_amount_now` number, float
    - `recurring_amount_after` number, float
  - `blockers` string[]: Why the decrease is refused: not_paying_customer, not_fixed_seat_contract, subscription_not_started, increase_not_allowed_here, below_free_users, below_minimum_seats, users_above_target (with current_users and users_to_remove).

## Other responses

- `400`: Invalid request payload
- `403`: Not an administrator of the organization
- `500`: The People count or the settings could not be read

---

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