---
title: "Grant a user credit"
method: POST
path: "/v1/admin/users/{user_id}/credits"
tags: ["Admin"]
---

# Grant a user credit

`POST /v1/admin/users/{user_id}/credits`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/admin/users/{user_id}/credits`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Writes one line to the account's credit ledger and answers with the balance it produced. Needs the `admin` role.
The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by writing a **negative** `amount_usd`, which leaves the wrong line on the record beside the one that compensates for it.
`kind` is required. Money received and credit given away report differently — one is revenue, the other customer-acquisition cost — so the line says which it is rather than defaulting to one of them.
The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.

## Path parameters

- `user_id` string, required

## Request body

- CreditGrant
  - `kind` 'purchased' | 'granted' | 'earned', required: What this line is. `purchased` for money that arrived, `granted` for credit naturali gave away — the two report differently, so it is required rather than defaulted. `earned` writes a withdrawal or a dispute against marketplace earnings and requires `reason`; a negative one is refused while the account's balance is negative. `included` is not accepted here: a plan's monthly allowance is the billing cycle's to write.
  - `amount_usd` number, required: US dollars to grant, rounded to the cent. Negative corrects an earlier grant; zero is refused, because a grant of nothing records no intent.
  - `reason` string, nullable: Why, for the record. Required for `earned`.

## Response `201`

The line that was written, and the balance after it.

- CreditGrantResult
  - `entry` CreditEntry, required
    - `id` string, required: Public ledger-line ID (cre_ prefix).
    - `kind` 'included' | 'purchased' | 'granted' | 'usage' | 'earned' | 'fee', required: Where the credit came from, which is also its accounting line. `included` is a plan's monthly allowance and does not carry past the cycle; `purchased` is a top-up and never expires; `granted` is credit naturali gave away. `usage` is managed model spend, debited from the meter — always negative. `fee` is what a consumer paid a marketplace publisher (negative); `earned` is the publisher's share of funded fees, and the only withdrawable kind.
    - `amount_usd` number, required: US dollars, signed: positive added credit, negative corrected an earlier line.
    - `reason` string, nullable, required: Why it was granted, as the operator wrote it.
    - `project_id` string, nullable, required: The project whose metered usage produced this line, for a `usage` debit. Null for every other kind: a grant, a top-up and an allowance are to the account rather than to one of its projects.
    - `counterparty_project_id` string, nullable, required: The other side of a marketplace line: the publisher project on a `fee`, the consumer project on an `earned`. Null for every other line.
    - `granted_by_user_id` string, nullable, required: The operator who authorized it. Null for credit no person granted — a plan's included allowance, or a payer's own top-up.
    - `created_at` string, date-time, required
  - `credit_balance_usd` number, required: The balance after the line was written.

## Other responses

- `400`: The request was malformed or failed validation.
- `401`: Missing or invalid credentials.
- `403`: The caller does not hold the `admin` role.
- `404`: No such user.
- `409`: `balance_negative`: a negative `earned` line while the account's balance is negative. `granted_exceeded`: a negative `granted` line larger than the account's granted credit.

---

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