---
title: "List Promo Codes"
method: GET
path: "/promo_codes"
tags: ["Promo Codes"]
---

# List Promo Codes

`GET /promo_codes`

Lists promo codes for an account with cursor pagination, filters, and sorting.

## Query parameters

- `account_id` string, required
- `status` 'active' | 'inactive' | 'archived' | 'expired'
- `product_ids` string[]
- `plan_ids` string[]
- `created_before` string, date-time
- `created_after` string, date-time
- `order` 'created_at'
- `direction` 'asc' | 'desc'
- `first` integer
- `after` string
- `last` integer
- `before` string

## Response `200`

promo codes listed

- object
  - `data` PromoCodeListItem[], required
    - `amount_off` number, required — Discount amount. Percentage discounts are represented as a decimal fraction.
    - `churned_users_only` boolean, required — Whether the promo code is restricted to churned customers.
    - `code` string, nullable, required — Code entered at checkout.
    - `created_at` string, required — When the promo code was created, as an ISO 8601 timestamp.
    - `currency` 'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau', required — Currency used for a fixed-amount discount.
    - `duration` 'forever' | 'once' | 'repeating', required — How long the discount applies.
    - `existing_memberships_only` boolean, required — Whether the promo code applies only to existing memberships.
    - `expires_at` string, nullable, required — When the promo code expires, as an ISO 8601 timestamp.
    - `id` string, required — Promo code ID, prefixed `promo_`.
    - `metadata` object, required — Custom key-value metadata stored on the promo code.
    - `new_users_only` boolean, required — Whether the promo code is restricted to new customers.
    - `one_per_customer` boolean, required — Whether each customer may redeem the promo code only once.
    - `product` PromoCodeProduct, required
      - `id` string, required — Product ID, prefixed `prod_`.
      - `title` string, required — Product display name.
    - `promo_duration_months` integer, nullable, required — Billing intervals the discount applies to.
    - `promo_type` 'percentage' | 'flat_amount', required — Whether the discount is percentage-based or a fixed amount.
    - `status` 'active' | 'inactive' | 'archived', required — Promo code lifecycle status.
    - `stock` integer, required — Maximum uses when stock is limited.
    - `unlimited_stock` boolean, required — Whether the promo code has no redemption limit.
    - `updated_at` string, required — When the promo code was updated, as an ISO 8601 timestamp.
    - `uses` integer, required — Memberships that used the promo code.
  - `page_info` object, required
    - `end_cursor` string, nullable, required
    - `has_next_page` boolean, required
    - `has_previous_page` boolean, required
    - `start_cursor` string, nullable, required

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthorized
- `404` — Resource not found

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/db0883548bc5/schema)