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

# Get balance

`GET /v1/balance`

## Request

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

Report the prepaid credit balance in cents (general credit, which pays for labels), where to add more, and the credit packs on offer; free, read-only, and not consequential.

## 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-ship-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-ship-api/revisions/f0615c6bd5d8?raw)