Skip to content
Hayonix

API reference · Billing

Redeem a promo code for promotional credit

POST/v1/orgs/{org_id}/billing/promo-redemptions
Console sessionbilling:manageOrganizationIdempotency-Key

Adds the code’s promotional credit, which expires at expires_at. Each organization can redeem a code once (409 already_redeemed); an unknown or used-up code answers 400.

Console session only: no API key can be granted the billing:manage permission it needs. Requires the billing:manage permission (a key's scope, or a role that includes it).

Request

Headers
HeaderRequiredDescription
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Path parameters

  • org_idstring

    Your organization. The SDKs and the CLI fill it in from the API key.

    ID with prefix org_

Body

JSON (application/json): RedeemPromoRequest.

  • codestringrequired

    Machine-readable code

    3–40 characters

Response

201 PromoRedemption — The credit granted

  • objectstringrequired

    Always `promo_redemption`: the type of this object

    One ofpromo_redemption

  • idstringrequired

    Unique ID (`prdm_…`)

    ID with prefix prdm_

  • amountstringrequired

    Integer nano-USD as a decimal string

    pattern ^-?[0-9]+$

  • expires_atstring (date-time)required

    When it expires (null: never) (ISO 8601, UTC)

Example response
Example response
{
  "object": "promo_redemption",
  "id": "prdm_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "amount": "1500000000",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
402insufficient_credit_errorThe organization is out of credit or over a spend limit.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.