---
title: "Record metered usage against a billing account"
method: POST
path: "/api/v1/usage_events"
tags: ["Money"]
---

# Record metered usage against a billing account

`POST /api/v1/usage_events`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/usage_events`
- Auth: one of:
  - API key in header `api-key`
  - OAuth 2 (authorization code, authorization URL `https://saltapp.ai/oauth2/authorize`, token URL `https://saltapp.ai/api/oauth2/token`, scopes: `money`)

Seller-called; amount is computed server-side from the product's price. The overdraft check runs inside a row lock (with_lock) -- the balance IS the spend cap. Only credit in the currency the product is priced in counts; credit in another currency does not pay for it. Supports an Idempotency-Key header.

## Request body

- object
  - `product_id` string, required
  - `chat_id` string, required
  - `payer_id` string: Required in a group chat.
  - `qty` string
  - `description` string

## Response `200`

OK.

- object
  - `ok` boolean
  - `entry_id` string
  - `balance` string: Balance in the product's currency.
  - `chain` string
  - `testnet` boolean
  - `currency` string

## Other responses

- `401`: Missing or invalid credentials.
- `403`: You can't bill this user. (blocked)
- `422`: insufficient_credits (the error field literally holds this code) / no active metered product / qty must be a positive number.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)