---
title: "Manual credit adjustment (admin only)"
method: POST
path: "/v1/admin/tenants/{tenant_id}/adjust-credits"
---

# Manual credit adjustment (admin only)

`POST /v1/admin/tenants/{tenant_id}/adjust-credits`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/admin/tenants/{tenant_id}/adjust-credits`
- Auth: none declared

Manually grant (positive) or claw back (negative) credits.

Callers should always send ``Idempotency-Key``. Without it, a request that
commits here but whose response is lost — an 8-second client read timeout
is enough — cannot be told apart from one that never arrived, and a retry
grants twice. Two layers use the key: the shared HTTP idempotency cache
(concurrent retries get 409, completed ones replay byte-for-byte) and a
guard stored on the grant or ledger row itself, which shares the balance
change's transaction and outlives the cache's TTL.

## Path parameters

- `tenant_id` string, required

## Headers

- `Idempotency-Key` string, nullable: Makes a retry after a lost response safe. Reuse the same key for the same adjustment; a repeat replays the original response (or, after the 24h cache, returns it with credited=false) instead of moving credits twice.
- `X-API-KEY` string, nullable

## Request body

- AdminCreditAdjustRequest: A credit movement with no money attached. ``kind`` says what it is — see ``ControlPlaneStore.adjust_credits``: - ``comp`` (credits > 0): free credits — welcome, goodwill. - ``revocation`` (credits < 0): take back credits we issued. - ``correction`` (either sign): fix a metering error; reported as consumption, under "Metering correction". Omitted, positive means ``comp`` and negative is the pre-taxonomy clawback (an ``admin_adjustment`` burn, excluded from reports). Invoice and Paddle sales belong on ``/v1/billing/credits``, refunds on ``/v1/billing/refunds``.
  - `credits` integer, required: Signed; never zero. Sign must fit the kind.
  - `reason` string
  - `promote_to_paid` boolean
  - `kind` 'comp' | 'revocation' | 'correction', nullable

## Response `200`

Successful Response

- AdminCreditAdjustResponse: Result of ``POST /v1/admin/tenants/{tenant_id}/adjust-credits``. Comps and revocations are grants and return ``grant_id``; corrections and unclassified clawbacks are ledger rows and return ``ledger_id``. The other is ``None``. ``kind`` echoes what was applied, including the default. A retry with the same ``Idempotency-Key`` either replays the original response byte-for-byte (header ``Idempotent-Replayed: true``) or, once that cache has expired, returns ``credited=False``: nothing moved, and the body describes the original adjustment. Both are success.
  - `tenant_id` string, required
  - `credits_adjusted` integer, required
  - `new_balance_credits` integer, required
  - `new_plan_type` string, required
  - `reason` string, required
  - `ledger_id` integer, nullable
  - `grant_id` integer, nullable
  - `credited` boolean
  - `kind` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)