---
title: "Get balance"
method: GET
path: "/v1/balance"
tags: ["mail"]
---

# Get balance

`GET /v1/balance`

## Request

- Base URL: `https://api.noerrands.com/c/mail`
- URL: `https://api.noerrands.com/c/mail/v1/balance`
- Auth: HTTP bearer

Report the remaining prepaid credit balance in cents, the top-up link, and every purchase option: a one-off single letter, then credit packs that credit more than they cost, each with the free letters it includes; free and read-only.

## Response `200`

Success.

- object
  - `balance_cents` integer, required
  - `currency` 'usd', required
  - `topup_url` string, uri, required
  - `packs` object[], required: Everything that can be bought, cheapest first. The first entry is a one-off single letter; every pack after it credits more than it costs, so quote both numbers to the human.
    - `pay_cents` integer, required: What the human pays, in cents.
    - `credits_cents` integer, required: What lands in the balance, in cents. Larger than pay_cents for a pack; equal for the one-off letter.
    - `free_letters` integer, required: Whole one-page letters the bonus alone pays for. Say it to the human as "three free letters". Zero for the one-off letter.
    - `label` string, required: What to call it to the human: "One letter" for the one-off purchase, "$25 pack" for a pack.

## Other responses

- `400`: invalid_request
- `401`: unauthorized. Carries WWW-Authenticate: Bearer resource_metadata="..."
- `403`: forbidden_scope: a write tool called with a read-only key.
- `404`: not_found
- `429`: rate_limited
- `502`: provider_error

---

[API](https://skmtc.dev/noerrands/apis/no-errands-mail-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-mail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-mail-api/revisions/391e96e083f5?raw)