---
title: "Redeem a voucher for allowance"
method: POST
path: "/vouchers/v1/redemptions"
tags: ["Vouchers"]
---

# Redeem a voucher for allowance

`POST /vouchers/v1/redemptions`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/vouchers/v1/redemptions`
- Auth: API key in header `SIGN-IN-WITH-X`

Redeems a promo code into the authenticated wallet's organization's allowance. It spends like any other allowance — a tier purchase settles from it with no on-chain payment.

Order-independent: this works as an agent's very first authenticated call (the organization is provisioned on demand) or long after `run402 init`. Never blocked by an organization's grace state, because redeeming is how an owner funds a renewal.

Idempotent for the redeeming organization: a repeat returns the original result with `already_redeemed: true` and never credits twice.

CLI: `run402 redeem <code>`, or `run402 init --voucher <code>`.

## Headers

- `SIGN-IN-WITH-X` string, required

## Request body

- object
  - `code` string, required: Case-insensitive; hyphens optional.

## Response `200`

Already redeemed by this organization — original result, no second credit

- object
  - `voucher_id` string, uuid
  - `amount_usd_micros` integer
  - `balance_usd_micros` integer: The organization's allowance AFTER the redemption.
  - `org_id` string, uuid
  - `redeemed_at` string, date-time
  - `already_redeemed` boolean: True when this exact organization already redeemed this code. The original result is returned unchanged and no second credit is made, so a timed-out client can retry safely.
  - `promo_lifetime_ceiling_usd_micros` integer: The lifetime promo-allowance ceiling that applied: what this organization may ever redeem from this voucher's issuer, in total. Codes from another issuer have their own ceiling.
  - `next_actions` object[]

## Other responses

- `201`: Allowance added
- `400`: Missing or malformed code
- `403`: PROMO_LIMIT_REACHED — the organization is at its lifetime promo-allowance ceiling for this voucher's issuer
- `404`: VOUCHER_NOT_FOUND — unknown or malformed code (deliberately indistinguishable)
- `409`: VOUCHER_ALREADY_REDEEMED — redeemed by a different organization
- `410`: VOUCHER_EXPIRED
- `429`: RATE_LIMITED — too many redemption attempts

---

[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/cc6ccb110365?raw)