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

# Create promo code

> Create a new promo code that applies a discount at checkout. Can be scoped to specific products or plans.

Required permissions:
 - `promo_code:create`
 - `access_pass:basic:read`



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/whopsdk/openapi.documented.yml post /promo_codes
openapi: 3.1.0
info:
  title: Whop API
  description: >-
    The Whop REST API. Please see
    https://docs.whop.com/developer/api/getting-started for more details.
  termsOfService: https://whop.com/tos-developer-api/
  version: 1.0.0
servers:
  - url: https://api.whop.com/api/v1
    description: Production Whop API
security: []
tags:
  - name: Products
    description: Products
  - name: Plans
    description: Plans
  - name: Payments
    description: Payments
  - name: Refunds
    description: Refunds
  - name: Disputes
    description: Disputes
  - name: Dispute alerts
    description: Dispute alerts
  - name: Resolution center cases
    description: Resolution center cases
  - name: Checkout configurations
    description: Checkout configurations
  - name: Setup intents
    description: Setup intents
  - name: Payment methods
    description: Payment methods
  - name: Invoices
    description: Invoices
  - name: Promo codes
    description: Promo codes
  - name: Card transactions
    description: Card transactions
  - name: Ledger accounts
    description: Ledger accounts
  - name: Transfers
    description: Transfers
  - name: Withdrawals
    description: Withdrawals
  - name: Payout methods
    description: Payout methods
  - name: Verifications
    description: Verifications
  - name: Payout accounts
    description: Payout accounts
  - name: Topups
    description: Topups
  - name: Users
    description: Users
  - name: Companies
    description: Companies
  - name: Authorized users
    description: Authorized users
  - name: Fee markups
    description: Fee markups
  - name: Members
    description: Members
  - name: Memberships
    description: Memberships
  - name: Leads
    description: Leads
  - name: Entries
    description: Entries
  - name: Shipments
    description: Shipments
  - name: Reviews
    description: Reviews
  - name: Company token transactions
    description: Company token transactions
  - name: Affiliates
    description: Affiliates
  - name: Experiences
    description: Experiences
  - name: Forums
    description: Forums
  - name: Forum posts
    description: Forum posts
  - name: Chat channels
    description: Chat channels
  - name: Support channels
    description: Support channels
  - name: Messages
    description: Messages
  - name: Reactions
    description: Reactions
  - name: Dm members
    description: Dm members
  - name: Dm channels
    description: Dm channels
  - name: Notifications
    description: Notifications
  - name: Courses
    description: Courses
  - name: Course chapters
    description: Course chapters
  - name: Course lessons
    description: Course lessons
  - name: Course students
    description: Course students
  - name: Course lesson interactions
    description: Course lesson interactions
  - name: Apps
    description: Apps
  - name: Webhooks
    description: Webhooks
  - name: App builds
    description: App builds
  - name: Access tokens
    description: Access tokens
  - name: Account links
    description: Account links
  - name: Files
    description: Files
  - name: Ai chats
    description: Ai chats
  - name: Bounties
    description: Bounties
  - name: Stats
    description: Stats
  - name: Ad campaigns
    description: Ad campaigns
  - name: Ad groups
    description: Ad groups
  - name: Ads
    description: Ads
  - name: Conversions
    description: Conversions
paths:
  /promo_codes:
    post:
      tags:
        - Promo codes
      summary: Create promo code
      description: >-
        Create a new promo code that applies a discount at checkout. Can be
        scoped to specific products or plans.


        Required permissions:
         - `promo_code:create`
         - `access_pass:basic:read`
      operationId: createPromoCode
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_off:
                  type: number
                  description: >-
                    The discount amount. When promo_type is percentage, this is
                    the percent off (e.g., 20 for 20% off). When promo_type is
                    flat_amount, this is the currency amount off (e.g., 10.00
                    for $10.00 off).
                  example: 6.9
                base_currency:
                  $ref: '#/components/schemas/Currencies'
                  description: >-
                    The three-letter ISO currency code for the promo code
                    discount.
                churned_users_only:
                  type:
                    - boolean
                    - 'null'
                  description: >-
                    Whether to restrict this promo code to only users who have
                    previously churned from the company.
                code:
                  type: string
                  description: >-
                    The alphanumeric code customers enter at checkout to apply
                    the discount.
                company_id:
                  type: string
                  description: >-
                    The unique identifier of the company to create this promo
                    code for.
                  example: biz_xxxxxxxxxxxxxx
                existing_memberships_only:
                  type:
                    - boolean
                    - 'null'
                  description: >-
                    Whether this promo code can only be applied to existing
                    memberships, such as for cancellation retention offers.
                expires_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: >-
                    The datetime when the promo code expires and can no longer
                    be used. Null means it never expires.
                  example: '2023-12-01T05:00:00.401Z'
                new_users_only:
                  type: boolean
                  description: >-
                    Whether to restrict this promo code to only users who have
                    never purchased from the company before.
                one_per_customer:
                  type:
                    - boolean
                    - 'null'
                  description: Whether each customer can only use this promo code once.
                plan_ids:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                    description: >-
                      Represents a unique identifier that is Base64 obfuscated.
                      It is often used to refetch an object or as key for a
                      cache. The ID type appears in a JSON response as a String;
                      however, it is not intended to be human-readable. When
                      expected as an input type, any string (such as
                      `"VXNlci0xMA=="`) or integer (such as `4`) input value
                      will be accepted as an ID.
                  description: >-
                    The identifiers of plans this promo code applies to. When
                    product_id is also provided, only plans attached to that
                    product are included.
                product_id:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The identifier of the product to scope this promo code to.
                    When provided, the promo code only applies to plans attached
                    to this product.
                  example: prod_xxxxxxxxxxxxx
                promo_duration_months:
                  type: integer
                  description: >-
                    The number of billing months the discount remains active.
                    For example, 3 means the discount applies to the first 3
                    billing cycles.
                  example: 42
                promo_type:
                  $ref: '#/components/schemas/PromoTypes'
                  description: The discount type, either percentage or flat_amount.
                stock:
                  type:
                    - integer
                    - 'null'
                  description: >-
                    The maximum number of times this promo code can be used.
                    Ignored when unlimited_stock is true.
                  example: 42
                unlimited_stock:
                  type:
                    - boolean
                    - 'null'
                  description: >-
                    Whether the promo code can be used an unlimited number of
                    times.
              required:
                - amount_off
                - base_currency
                - code
                - company_id
                - new_users_only
                - promo_duration_months
                - promo_type
              description: Parameters for CreatePromoCode
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error:
                  type: invalid_request_error
                  code: parameter_missing
                  message: 'Missing required parameter: amount.'
                  param: amount
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error:
                  type: unauthorized
                  message: Invalid or missing API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error:
                  type: forbidden
                  message: You do not have permission to access this resource
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error:
                  type: not_found
                  message: Resource not found
        '422':
          description: Verification required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error: null
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      code:
                        type:
                          - string
                          - 'null'
                        description: >-
                          A short string indicating the specific error code,
                          e.g. 'parameter_missing', 'parameter_invalid',
                          'invalid_json'
                      param:
                        type:
                          - string
                          - 'null'
                        description: The parameter that caused the error, if applicable
                    required:
                      - type
                      - message
                required:
                  - error
              example:
                error:
                  type: internal_server_error
                  message: An unexpected error occurred
      security:
        - bearerAuth:
            - promo_code:create
            - access_pass:basic:read
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Whop from '@whop/sdk';

            const client = new Whop({
              apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
            });

            const promoCode = await client.promoCodes.create({
              amount_off: 6.9,
              base_currency: 'usd',
              code: 'code',
              company_id: 'biz_xxxxxxxxxxxxxx',
              new_users_only: true,
              promo_duration_months: 42,
              promo_type: 'percentage',
            });

            console.log(promoCode.id);
        - lang: Python
          source: |-
            import os
            from whop_sdk import Whop

            client = Whop(
                api_key=os.environ.get("WHOP_API_KEY"),  # This is the default and can be omitted
            )
            promo_code = client.promo_codes.create(
                amount_off=6.9,
                base_currency="usd",
                code="code",
                company_id="biz_xxxxxxxxxxxxxx",
                new_users_only=True,
                promo_duration_months=42,
                promo_type="percentage",
            )
            print(promo_code.id)
        - lang: Ruby
          source: |-
            require "whop_sdk"

            whop = WhopSDK::Client.new(api_key: "My API Key")

            promo_code = whop.promo_codes.create(
              amount_off: 6.9,
              base_currency: :usd,
              code: "code",
              company_id: "biz_xxxxxxxxxxxxxx",
              new_users_only: true,
              promo_duration_months: 42,
              promo_type: :percentage
            )

            puts(promo_code)
components:
  schemas:
    Currencies:
      type: string
      enum:
        - 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
      description: The available currencies on the platform
    PromoTypes:
      type: string
      enum:
        - percentage
        - flat_amount
      description: The type of promo code used to discount a plan
    PromoCode:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the promo code.
          example: promo_xxxxxxxxxxxx
        amount_off:
          type: number
          description: >-
            The discount amount. Interpretation depends on promo_type: if
            'percentage', this is the percentage (e.g., 20 means 20% off); if
            'flat_amount', this is dollars off (e.g., 10.00 means $10.00 off).
          example: 6.9
        currency:
          $ref: '#/components/schemas/Currencies'
          description: The monetary currency of the promo code.
        churned_users_only:
          type: boolean
          description: >-
            Restricts promo use to only users who have churned from the company
            before.
        code:
          type:
            - string
            - 'null'
          description: The specific code used to apply the promo at checkout.
        created_at:
          type: string
          format: date-time
          description: The datetime the promo code was created.
          example: '2023-12-01T05:00:00.401Z'
        existing_memberships_only:
          type: boolean
          description: >-
            Restricts promo use to only be applied to already purchased
            memberships.
        duration:
          oneOf:
            - $ref: '#/components/schemas/PromoDurations'
            - type: 'null'
          description: The duration of the promo.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date/time of when the promo expires.
          example: '2023-12-01T05:00:00.401Z'
        new_users_only:
          type: boolean
          description: >-
            Restricts promo use to only users who have never purchased from the
            company before.
        promo_duration_months:
          type:
            - integer
            - 'null'
          description: The number of months the promo is applied for.
          example: 42
        one_per_customer:
          type: boolean
          description: Restricts promo use to only be applied once per customer.
        product:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              description: The unique identifier for the product.
              example: prod_xxxxxxxxxxxxx
            title:
              type: string
              description: >-
                The display name of the product shown to customers on the
                product page and in search results.
              example: Pickaxe Analytics
          required:
            - id
            - title
          description: The product this promo code applies to
        promo_type:
          $ref: '#/components/schemas/PromoTypes'
          description: The type (% or flat amount) of the promo.
        status:
          $ref: '#/components/schemas/PromoCodeStatus'
          description: Indicates if the promo code is live or disabled.
        stock:
          type: integer
          description: The quantity limit on the number of uses.
          example: 42
        unlimited_stock:
          type: boolean
          description: Whether or not the promo code has unlimited stock.
        uses:
          type: integer
          description: The amount of times the promo codes has been used.
          example: 42
        company:
          type: object
          properties:
            id:
              type: string
              description: The unique identifier for the company.
              example: biz_xxxxxxxxxxxxxx
            title:
              type: string
              description: The written name of the company.
          required:
            - id
            - title
          description: The company for the promo code.
      required:
        - id
        - amount_off
        - currency
        - churned_users_only
        - code
        - created_at
        - existing_memberships_only
        - duration
        - expires_at
        - new_users_only
        - promo_duration_months
        - one_per_customer
        - product
        - promo_type
        - status
        - stock
        - unlimited_stock
        - uses
        - company
      description: >-
        A promo code applies a discount to a plan during checkout. Promo codes
        can be percentage-based or fixed-amount, and can have usage limits and
        expiration dates.
    PromoDurations:
      type: string
      enum:
        - forever
        - once
        - repeating
      description: The duration setting for the promo code
    PromoCodeStatus:
      type: string
      enum:
        - active
        - inactive
        - archived
      description: Statuses for promo codes
  securitySchemes:
    bearerAuth:
      type: http
      description: >-
        A company API key, company scoped JWT, app API key, or user OAuth token.
        You must prepend your key/token with the word 'Bearer', which will look
        like `Bearer ***************************`
      scheme: bearer
      bearerFormat: auth-scheme

````