Vouchers

Redeem a voucher for allowance

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>.

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

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Request body

codestring required

Case-insensitive; hyphens optional.

Example request

{
  "code": "R402-K8F3-Q2W9"
}

Response

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

voucher_idstring uuid
amount_usd_microsinteger
balance_usd_microsinteger

The organization's allowance AFTER the redemption.

org_idstring uuid
redeemed_atstring date-time
already_redeemedboolean

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_microsinteger

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_actionsobject[]

Example response

{
  "amount_usd_micros": 1000000
}

Changes

No recorded changes to this operation across all 1 revision of this API.