Promo Codes

Retrieve Promo Code

Changed on

Retrieves a promo code by ID.

get/promo_codes/{id}

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/promo_codes/{id}
  • Auth: HTTP bearer

Response

promo code retrieved

amount_offnumber required

Discount amount. Percentage discounts are represented as a decimal fraction.

churned_users_onlyboolean required

Whether the promo code is restricted to churned customers.

codestring nullable required

Code entered at checkout.

created_atstring 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_onlyboolean required

Whether the promo code applies only to existing memberships.

expires_atstring nullable required

When the promo code expires, as an ISO 8601 timestamp.

idstring required

Promo code ID, prefixed promo_.

metadataobject required

Custom key-value metadata stored on the promo code.

new_users_onlyboolean required

Whether the promo code is restricted to new customers.

one_per_customerboolean required

Whether each customer may redeem the promo code only once.

promo_duration_monthsinteger 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.

stockinteger required

Maximum uses when stock is limited.

unlimited_stockboolean required

Whether the promo code has no redemption limit.

updated_atstring required

When the promo code was updated, as an ISO 8601 timestamp.

usesinteger required

Memberships that used the promo code.

Example response

{
  "account": {
    "id": "biz_xxxxxxxxxxxxxx",
    "title": "Shine Time Auto Detailing"
  },
  "amount_off": 0.25,
  "code": "affiliate25",
  "created_at": "2026-01-01T12:00:00.000Z",
  "currency": "usd",
  "duration": "repeating",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "id": "promo_xxxxxxxxxxxxxx",
  "metadata": {},
  "new_users_only": true,
  "one_per_customer": true,
  "product": {
    "id": "prod_xxxxxxxxxxxxxx",
    "title": "Ceramic Coating Package"
  },
  "promo_duration_months": 3,
  "promo_type": "percentage",
  "status": "active",
  "stock": 200,
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes

  • f1020c3ecda4Revision changes
    • info

      added the optional property / to the response with the status

  • bdd0e2c70d58Revision changes
    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      the response's property format changed from date-time to no format for status

    • breaking

      the response's property type changed from no type to string for status

    • breaking

      the response's property format changed from date-time to no format for status

    • breaking

      the response's property type changed from object null to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      deleted the path request parameter id

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      added the new forever enum value to the response property for the response status

    • warning

      added the new once enum value to the response property for the response status

    • warning

      added the new repeating enum value to the response property for the response status

    • info

      the security scope access_pass:basic:read was removed from the endpoint's security scheme bearerAuth

    • info

      api tag Promo Codes added

    • info

      api tag Promo codes removed

    • info

      added the new optional header request parameter Api-Version-Date to all path's operations

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed subschema #2 from the response property oneOf list for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status