---
title: "Manually change an organisation's tier (admin)"
method: POST
path: "/admin/tiers/change"
tags: ["admin"]
---

# Manually change an organisation's tier (admin)

`POST /admin/tiers/change`

## Request

- Base URL: `https://api.qualityclouds.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.qualityclouds.ai/admin/tiers/change`
- Auth: one of:
  - HTTP bearer
  - OpenID Connect (`https://account.qualityclouds.com//realms/ai-production/.well-known/openid-configuration`)

Moves one organisation to a target tier with full entitlements (tier + quotas + gated tools), sets tier_source to 'manual', and is idempotent for a no-op change. Requires the Keycloak 'admins' group.

## Request body

- AdminTierChangeRequest: POST /admin/tiers/change — move one organisation to a target tier. ``organisation_id`` is the internal ``organisations.id`` UUID (the identity the Backoffice Customer 360 screen already holds), not the Keycloak org id. ``target_tier_code`` is validated against the ``tiers`` table server-side, so it is a plain string here (an unknown code yields a 422 listing valid tiers rather than a generic enum error).
  - `organisation_id` string, uuid, required: Internal organisations.id UUID of the org to change.
  - `target_tier_code` string, required: Tier code to move the organisation to (must exist in the tiers table).
  - `reason` string, nullable: Optional free-text reason recorded in the audit trail (QSA-1363).

## Response `200`

Successful Response

- AdminTierChangeResponse: Outcome of a manual tier change. ``changed`` is ``False`` for the idempotent no-op case (rule 9): the org was already on the requested tier, so nothing was persisted.
  - `organisation_id` string, uuid, required
  - `previous_tier_code` string, required
  - `tier_code` string, required
  - `tier_source` string, required
  - `changed` boolean, required
  - `message` string, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Validation Error

---

[API](https://skmtc.dev/qualityclouds/apis/qai-orchestrator-api.md) · [All operations](https://skmtc.dev/qualityclouds/apis/qai-orchestrator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qualityclouds/apis/qai-orchestrator-api/revisions/250c849925af?raw)