Organizations

Preview a seat decrease at the next renewal

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.

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

Path parameters

organizationIdstring required

ID of Organization

Request body

target_seatsinteger required

The seat total the admin wants from the next renewal on (not the number to remove)

current_seatsinteger

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_idstring

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

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

statusstring

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.

messagestring
change_idstring
request_idstring
requested_atstring
requested_by_emailstring
requested_by_user_idstring
billing_cycle'monthly' | 'yearly'
current_seatsinteger

Committed seats - the license count plus pending_added_seats

pending_added_seatsinteger

Seats bought on the current cycle that are not finalized yet

target_seatsinteger
seats_removedinteger
current_usersinteger

People in the People list (0 when it was not read)

users_to_removeinteger

People to remove before target_seats is allowed

free_usersinteger
minimum_seatsinteger

The lowest target accepted now - the People count, the free users, the plan minimum, 1

effective_datestring

The next renewal date, 20060102

blockersstring[]

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

Changes

No recorded changes to this operation across all 1 revision of this API.