---
title: "Create top-up link"
method: POST
path: "/v1/topups"
tags: ["mail"]
---

# Create top-up link

`POST /v1/topups`

## Request

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

Create a Stripe Checkout link for one letter or a credit pack, and report every option with the credits and free letters it includes. Creates a Stripe Checkout session but charges nothing: money moves only if the human opens the link and pays, and the credit lands when Stripe confirms the payment. Free.

## Request body

- object
  - `amount_cents` 249 | 1000 | 2500 | 5000, required: What to charge, in cents: the one-off single letter or one of the credit packs, as its pay_cents. A pack credits more than it costs; see packs.

## Response `200`

Success.

- object
  - `checkout_url` string, uri, required
  - `expires_at` string, date-time, 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)