![](https://rewalto.com/brand/neo/assets/sample-hero-light.svg)![](https://rewalto.com/brand/neo/assets/sample-hero-dark.svg)

DEVELOPER DOCS / CONTRACT 0.101.0

# Balances, usage and receipts

Read credit balances, expiry, usage history and delivery receipts.

Get started with your AI agent.Copy agent prompt

Search API documentation

Search all ten API documentation guides

[Documentation overview](https://rewalto.com/developers/docs)[Make your first request](https://rewalto.com/developers/docs/quickstart)[Authentication and organisations](https://rewalto.com/developers/docs/authentication)[Create and manage API keys](https://rewalto.com/developers/docs/api-keys)[Read commerce data](https://rewalto.com/developers/docs/data)[Balances, usage and receipts](https://rewalto.com/developers/docs/credits)[Review and approve a quote](https://rewalto.com/developers/docs/quotes)[Refunds by receipt](https://rewalto.com/developers/docs/refunds)[Errors and safe retries](https://rewalto.com/developers/docs/errors)[Use the TypeScript client](https://rewalto.com/developers/docs/client)[API, CLI and MCP (preview)](https://rewalto.com/developers/docs/cli-mcp)[Discover the data catalogue](https://rewalto.com/developers/docs/catalogue)[Check held data and request a missing type](https://rewalto.com/developers/docs/intake)[Dataset snapshots and exports](https://rewalto.com/developers/docs/dataset-purchases)[Download OpenAPI JSON](https://rewalto.com/developers/openapi.json)

Contract snapshot 0.101.0 · Deployment and client release availability follow the integration note for your environment.

## Read the balance before spending

The balance separates free and paid credits and their expiry. Free allowance expires at month end; paid credits have their own expiry. Use the API’s balance, not a total inferred from a cached screen.

## Receipts explain delivered work

Usage history includes ledger entries and receipts, newest first and paged. Keep the rate version, receipt identifier, outcome and credit amount together when displaying a delivery.

## Unavailable is not zero

If balance or usage cannot be loaded, show an unavailable state with a retry option. Credit responses use no-store; do not serve a stale balance as the current one.

## Explain the balance in context

Display the free and paid portions with their own expiry information when supplied. A quoted ceiling and a completed delivery are different lifecycle events; keep them distinct in account history. If a user asks why a total changed, start from the ledger and linked receipt rather than reconstructing spending from clicks.

## Read history without double counting

Follow the API’s pagination and retain stable identifiers when displaying entries from more than one page. Keep the original credit amounts and outcomes instead of inferring a charge from a row count. Refresh account state after a confirmed operation; an old balance is not proof that an operation failed.

GET

## `/v1/credits/balance`

### Get the credit balance

The caller's organisation's credits. They are spent in this order: this month's free credits, then promotional credits, then paid credits. The first call in an IST month grants that month's 1,000 free credits, so a new organisation sees them at once.

Response status codes

| Status | Meaning |
| --- | --- |
| 200 | Success |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |

Full response fields and reusable schemas are in the downloadable OpenAPI contract.

GET

## `/v1/credits/usage`

### List credit usage

A page of the caller's organisation's ledger events and receipts, newest first. Only the caller's own organisation is ever shown.

Parameters

```
[
  {
    "name": "limit",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "pattern": "^[0-9]{1,3}$",
      "examples": [
        "50"
      ]
    },
    "description": "Entries per page, 1 to 200 (default 50). Sent as digits in the query string."
  },
  {
    "name": "cursor",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 400
    },
    "description": "The nextCursor of the previous page. Omit for the newest entries."
  },
  {
    "name": "view",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "pattern": "^(all|charges)$",
      "examples": [
        "charges"
      ]
    },
    "description": "all (the default): every ledger event and receipt. charges: one entry per charge. The reserve, settle and release events of a reservation that has a receipt (a run, or a charged Library read) are left out, so each charge is listed once, as its receipt (kind read or receipt, with its units and credits). Refunds, grants, top-ups, promotional grants, expiries and the holds of runs still in progress are listed as with all. Pass the same view with each page’s cursor."
  }
]
```

Response status codes

| Status | Meaning |
| --- | --- |
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |

Full response fields and reusable schemas are in the downloadable OpenAPI contract.

[All API documentation](https://rewalto.com/developers/docs)[Read OpenAPI contract](https://rewalto.com/developers/openapi.json)

---

Canonical page: https://rewalto.com/developers/docs/credits
Last content change: 2026-10-26