---
title: "Redeem a promotion code"
method: POST
path: "/v1/billing/promotions/redeem"
---

# Redeem a promotion code

`POST /v1/billing/promotions/redeem`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/billing/promotions/redeem`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Redeems one promotion code for the verified organization, with the billing owner's explicit confirmation. A code carries one benefit: promotional execution credit that expires and is spent before purchased credit, a complimentary slot for a named project that never becomes a paid subscription, a perk, or a discount on the project subscription shown in the next project quote. Every code that cannot be redeemed — unknown, ended, used up, not for this organization, or not combinable with a benefit already held — receives the same not_found answer; repeated refusals are throttled with rate_limited. The Idempotency-Key makes retries return the original grant. Nothing is charged and no payment method is needed.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `code` string, required
  - `project` string
  - `confirmed` true, required

## Response `201`

Redeem a promotion code

- object
  - `grant` object, required
    - `id` string, required
    - `source` 'operator' | 'code', required
    - `benefit` union, required
      - object
        - `kind` 'credit', required
        - `amount` object, required
          - `currency` 'USD', required
          - `microdollars` string, required
          - `scale` 6, required
      - object
        - `kind` 'project-slot', required
        - `project` string, required
      - object
        - `kind` 'perk', required
        - `perk` string, required
      - object
        - `kind` 'discount', required
        - `percentOff` integer
        - `amountOff` object
          - `currency` 'USD', required
          - `microdollars` string, required
          - `scale` 6, required
        - `duration` 'once' | 'repeating', required
        - `durationInMonths` integer
    - `state` 'active' | 'expired' | 'revoked', required
    - `startsAt` string, required
    - `endsAt` string
    - `revokedAt` string
  - `promotions` object, required
    - `grants` object[], required
      - `id` string, required
      - `source` 'operator' | 'code', required
      - `benefit` union, required
        - object
          - `kind` 'credit', required
          - `amount` object, required
            - `currency` 'USD', required
            - `microdollars` string, required
            - `scale` 6, required
        - object
          - `kind` 'project-slot', required
          - `project` string, required
        - object
          - `kind` 'perk', required
          - `perk` string, required
        - object
          - `kind` 'discount', required
          - `percentOff` integer
          - `amountOff` object
            - `currency` 'USD', required
            - `microdollars` string, required
            - `scale` 6, required
          - `duration` 'once' | 'repeating', required
          - `durationInMonths` integer
      - `state` 'active' | 'expired' | 'revoked', required
      - `startsAt` string, required
      - `endsAt` string
      - `revokedAt` string
    - `projectCapacity` object, required
      - `included` integer, required
      - `paid` integer, required
      - `complimentary` integer, required
    - `perks` object[], required
      - `perk` string, required
      - `endsAt` string, required
    - `restrictions` string[], required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing, test_to_live_escalation.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: idempotency_key_reused, project_archived, state_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)