---
title: "Add or subtract prepaid credits for a team (audited, idempotent)"
method: POST
path: "/v1/admin/cockpit/teams/{tenant_id}/credit-adjustments"
tags: ["admin"]
---

# Add or subtract prepaid credits for a team (audited, idempotent)

`POST /v1/admin/cockpit/teams/{tenant_id}/credit-adjustments`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/admin/cockpit/teams/{tenant_id}/credit-adjustments`
- Auth: HTTP bearer

Moves credits through the existing ledger primitives only (atomic grant / clamped FOR-UPDATE drawdown, so a balance can never go negative), writes the money-trail row and the tenant audit entry in the SAME transaction, and claims the client-supplied idempotency key so a retried submit replays the stored outcome instead of moving credits twice. Requires a human reason. Admin only.

## Path parameters

- `tenant_id` string, uuid, required

## Request body

- CreditAdjustmentCreate: A staff credit grant/clawback. Direction + positive magnitude (fat-finger safe).
  - `direction` 'add' | 'subtract', required
  - `amount` union, required: Credits, 2 decimals max.
    - number
    - string
  - `reason` string, required
  - `idempotency_key` string, required: Client-generated once per submit; resending it replays the stored outcome instead of moving credits again.

## Response `201`

Successful Response

- AdminCreditAdjustmentRead: One applied (or replayed) adjustment, with both ledgers' outcome.
  - `id` string, uuid, required
  - `amount` string, required: Signed requested credits (positive = add).
  - `applied_credits` string, required: Signed credits actually moved on the COGS ledger.
  - `applied_retail_micro_usd` integer, required: Signed micro-USD moved on the legacy retail ledger.
  - `balance_after` string, required
  - `retail_balance_after_micro_usd` integer, required
  - `reason` string, required
  - `created_at` string, date-time, required
  - `created_by_email` string, nullable: Admin's email when the principal was a user.
  - `created_by_principal_type` string, nullable
  - `replayed` boolean: True when this response replays a previous idempotency claim.

## Other responses

- `401`: Unauthorized
- `403`: Permission denied (PERMISSION_DENIED) or email not verified (EMAIL_NOT_VERIFIED)
- `404`: Not found
- `409`: Conflict: inspect ``errors[0].type`` for the specific case (``idempotency_key_reused``)
- `422`: Validation error

---

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