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

# Promo Code

A Promo Code is a discount a buyer enters at checkout, either a percentage or a fixed amount off. It belongs to an account, can be limited to one product, and controls who can redeem it, how many times, until when, and for how many billing periods the discount lasts.

Use the Promo Codes API to create codes for an account, list and retrieve them, deactivate a code to pause redemptions or activate it again, and archive codes you no longer offer.

## Endpoints

| Endpoint | Request |
| - | - |
| [List Promo Codes](/api-reference/beta/promo-codes/list-promo-codes) | <Badge color="blue" size="sm" stroke>GET</Badge> `/promo_codes` |
| [Retrieve Promo Code](/api-reference/beta/promo-codes/retrieve-promo-code) | <Badge color="blue" size="sm" stroke>GET</Badge> `/promo_codes/{id}` |
| [Create Promo Code](/api-reference/beta/promo-codes/create-promo-code) | <Badge color="green" size="sm" stroke>POST</Badge> `/promo_codes` |
| [Activate Promo Code](/api-reference/beta/promo-codes/activate-promo-code) | <Badge color="green" size="sm" stroke>POST</Badge> `/promo_codes/{id}/activate` |
| [Deactivate Promo Code](/api-reference/beta/promo-codes/deactivate-promo-code) | <Badge color="green" size="sm" stroke>POST</Badge> `/promo_codes/{id}/deactivate` |
| [Delete Promo Code](/api-reference/beta/promo-codes/delete-promo-code) | <Badge color="red" size="sm" stroke>DELETE</Badge> `/promo_codes/{id}` |

## Attributes

<Columns cols={2}>
  <Column>
    <ResponseField name="id" type="string" required>
      Promo code ID, prefixed `promo_`.
    </ResponseField>

    <ResponseField name="account" type="object" required>
      Account that owns the promo code.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          Account ID, prefixed `biz_`.
        </ResponseField>

        <ResponseField name="title" type="string" required>
          Account display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="amount_off" type="number" required>
      Discount amount. Percentage discounts are represented as a decimal fraction.
    </ResponseField>

    <ResponseField name="churned_users_only" type="boolean" required>
      Whether the promo code is restricted to churned customers.
    </ResponseField>

    <ResponseField name="code" type="string | null" required>
      Code entered at checkout.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      When the promo code was created, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Currency used for a fixed-amount discount.

      Available options: `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`
    </ResponseField>

    <ResponseField name="duration" type="string" required>
      How long the discount applies.

      Available options: `forever`, `once`, `repeating`
    </ResponseField>

    <ResponseField name="existing_memberships_only" type="boolean" required>
      Whether the promo code applies only to existing memberships.
    </ResponseField>

    <ResponseField name="expires_at" type="string | null" required>
      When the promo code expires, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="metadata" type="object" required>
      Custom key-value metadata stored on the promo code.
    </ResponseField>

    <ResponseField name="new_users_only" type="boolean" required>
      Whether the promo code is restricted to new customers.
    </ResponseField>

    <ResponseField name="one_per_customer" type="boolean" required>
      Whether each customer may redeem the promo code only once.
    </ResponseField>

    <ResponseField name="product" type="object | null" required>
      Product the promo code is restricted to, or `null` when it is not product-scoped.

      <Accordion title="Properties" defaultOpen={true}>
        <ResponseField name="id" type="string" required>
          Product ID, prefixed `prod_`.
        </ResponseField>

        <ResponseField name="title" type="string" required>
          Product display name.
        </ResponseField>
      </Accordion>
    </ResponseField>

    <ResponseField name="promo_duration_months" type="integer | null" required>
      Billing intervals the discount applies to.
    </ResponseField>

    <ResponseField name="promo_type" type="string" required>
      Whether the discount is percentage-based or a fixed amount.

      Available options: `percentage`, `flat_amount`
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Promo code lifecycle status.

      Available options: `active`, `inactive`, `archived`
    </ResponseField>

    <ResponseField name="stock" type="integer" required>
      Maximum uses when stock is limited.
    </ResponseField>

    <ResponseField name="unlimited_stock" type="boolean" required>
      Whether the promo code has no redemption limit.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      When the promo code was updated, as an ISO 8601 timestamp.
    </ResponseField>

    <ResponseField name="uses" type="integer" required>
      Memberships that used the promo code.
    </ResponseField>
  </Column>

  <Column>
    <div className="api-resource-sticky-example">
      ```json PromoCode theme={null}
      {
      	"id": "promo_xxxxxxxxxxxxxx",
      	"code": "SUMMER25",
      	"account": {
      		"id": "biz_xxxxxxxxxxxxxx",
      		"title": "Shine Time Auto Detailing"
      	},
      	"product": {
      		"id": "prod_xxxxxxxxxxxxxx",
      		"title": "Ceramic Coating Package"
      	},
      	"status": "active",
      	"promo_type": "percentage",
      	"amount_off": 0.25,
      	"currency": "usd",
      	"duration": "repeating",
      	"promo_duration_months": 3,
      	"new_users_only": true,
      	"churned_users_only": false,
      	"existing_memberships_only": false,
      	"one_per_customer": true,
      	"unlimited_stock": false,
      	"stock": 200,
      	"uses": 37,
      	"expires_at": "2026-12-31T23:59:59.000Z",
      	"metadata": {},
      	"created_at": "2026-09-01T12:00:00.000Z",
      	"updated_at": "2026-09-01T12:00:00.000Z"
      }
      ```
    </div>
  </Column>
</Columns>


## Related topics

- [Promo Code](/api-reference/promo-codes/promo-code.md)
- [CLI Commands](/cli/commands.md)
- [Delete Promo Code](/api-reference/beta/promo-codes/delete-promo-code.md)


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