---
title: "Mint an allowance voucher"
method: POST
path: "/vouchers/v1"
tags: ["Vouchers"]
---

# Mint an allowance voucher

`POST /vouchers/v1`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/vouchers/v1`
- Auth: API key in header `x-run402-issuer-key`

Mints one single-use voucher under the issuer's caps (per-code maximum, outstanding unredeemed value, daily mint count). The raw code is returned exactly once. Replaying `idempotency_key` returns the original voucher's metadata with `already_minted: true` and no code.

## Request body

- object
  - `amount_usd_micros` integer, required
  - `idempotency_key` string, required
  - `ref` string, nullable: Opaque issuer context; never interpreted.
  - `expires_in_days` integer

## Response `200`

Idempotency-key replay — original voucher, no code

- object
  - `voucher_id` string, uuid
  - `code` string, nullable: The raw code, returned EXACTLY ONCE at first mint. Null on an idempotency-key replay: only the hash is stored, so the code cannot be re-served. An issuer that lost the first response mints a fresh code with a new idempotency key.
  - `amount_usd_micros` integer
  - `ref` string, nullable: Opaque issuer-supplied context handle. Stored verbatim, returned only to the issuing key, never interpreted by the platform.
  - `expires_at` string, date-time
  - `created_at` string, date-time
  - `already_minted` boolean

## Other responses

- `201`: Voucher minted
- `400`: Invalid amount, expiry, or missing idempotency key
- `401`: Missing or unknown issuer key
- `403`: Issuer cap reached (VOUCHER_AMOUNT_EXCEEDS_CAP, ISSUER_OUTSTANDING_CAP_REACHED, ISSUER_DAILY_MINT_CAP_REACHED)

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)