> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotion Code Endpoints

> Give buyers more codes for a coupon, each with its own restrictions

A promotion code is another code buyers can type for an existing [coupon](https://docs.waffo.ai/api-reference/endpoints/coupons/overview.md). It gives the coupon's discount. The coupon only limits its expiry and total uses; buyer restrictions are set on each promotion code. Use promotion codes for an influencer, a campaign channel, or a batch of single-use codes.

Promotion codes only exist for `active` coupons, in the coupon's store and environment. Creating promotion codes does not change the coupon's discount.

## Promotion Code Status Values

| Status | Description |
| - | - |
| `active` | Usable at checkout while its coupon is `active` |
| `inactive` | Deactivated. This is permanent — an inactive promotion code cannot be reactivated |

## Restrictions

Each promotion code has its own buyer restrictions. The coupon's `redeemBy` and `maxRedemptions` apply to every code as well:

| Field | Description |
| - | - |
| `customerEmails` | Only these buyers (max 100 emails, case-insensitive) |
| `perCustomerLimit` | Lifetime uses per buyer |
| `maxRedemptions` | Uses of this promotion code. Must not exceed the coupon's `maxRedemptions`; the coupon's limit still applies |
| `expiresAt` | Expiry. Must not be later than the coupon's `redeemBy`. Defaults to the coupon's `redeemBy` |
| `minimumAmount` | Minimum order amount per currency, before discount and tax, e.g. `{ "USD": "50.00" }`. Currencies not listed have no minimum |

Create promotion codes together with the coupon ([Create Coupon](https://docs.waffo.ai/api-reference/endpoints/coupons/create-coupon.md), up to 20) or one by one and in bulk with the endpoints below. The coupon's own `code` is not one of its promotion codes: it has no restrictions of its own, is not returned by `promotionCodes`, and can only be deactivated together with the coupon.

## Codes

Promotion codes follow the same [code format](https://docs.waffo.ai/api-reference/endpoints/coupons/overview.md) as coupons: 3–32 letters, digits or `-`, case-insensitive, stored in uppercase, unique among the store's active codes in the same environment, and released when deactivated. When you omit `code`, or generate codes in bulk, the random part uses uppercase letters and digits without the look-alike characters `0`, `O`, `1`, `I` and `L`.

## Safe Retries

Send an `X-Idempotency-Key` header (SDK: the `idempotencyKey` option) and reuse it when you retry. This matters most for [Generate Promotion Codes](https://docs.waffo.ai/api-reference/endpoints/promotion-codes/generate-promotion-codes.md): codes are random, so a retry without the key generates a second batch. See [Errors](https://docs.waffo.ai/api-reference/errors.md) for the key requirements.

## Reading Promotion Codes

These endpoints only write. List a coupon's promotion codes with [GraphQL](https://docs.waffo.ai/api-reference/endpoints/graphql/overview.md): `promotionCodes` and `promotionCodesCount`. Filter by `batchId` to read back a generated batch.

```graphql theme={"system"}
query PromotionCodes($couponId: String!) {
  promotionCodes(couponId: $couponId, limit: 50, offset: 0) {
    id
    code
    status
    batchId
    timesRedeemed
  }
  promotionCodesCount(couponId: $couponId)
}
```

## Endpoints

> **[Create Promotion Code](https://docs.waffo.ai/api-reference/endpoints/promotion-codes/create-promotion-code.md)**
>
> Add one promotion code to a coupon.

> **[Generate Promotion Codes](https://docs.waffo.ai/api-reference/endpoints/promotion-codes/generate-promotion-codes.md)**
>
> Generate 1–500 random promotion codes in one call.

> **[Deactivate Promotion Code](https://docs.waffo.ai/api-reference/endpoints/promotion-codes/deactivate-promotion-code.md)**
>
> Permanently deactivate a promotion code and release its code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.