---
title: "Create Promo Code"
method: POST
path: "/v1/promo_codes"
tags: ["Promo Codes"]
---

# Create Promo Code

`POST /v1/promo_codes`

Creates a promotion code referencing an existing coupon. If `code` is omitted, a unique
code is generated automatically. The supplied `code` must be unique across your promotion
codes.

## Request body

- PromoCodeBodyForCreatePromoCodeRequest — An envelope wrapping a single promotion code object.
  - `promo_code` CreatePromoCodeRequest, required — Parameters for creating a promotion code that customers redeem to apply an existing coupon.
    - `coupon_id` string, required — ID of the Coupon this promotion code applies.
    - `code` string, nullable — The customer-facing code. Must be unique across your promotion codes. If null, a code is generated automatically.
    - `max_redemptions` integer, nullable — The number of times the promo code can be redeemed.
    - `customer` string, nullable — The customer that can be associated with the promo code. If null, the promo code can be redeemed by any customer.
    - `metadata` object, nullable — Metadata associated with the promo code.

## Response `200`

An envelope wrapping a single promotion code object.

- PromoCodeBodyForPromoCode — An envelope wrapping a single promotion code object.
  - `promo_code` PromoCode, required — A promo code represents a code for a coupon that can be redeemed by a customer.
    - `promo_code_id` string, required — The ID of the promo code.
    - `code` string, required — The customer-facing code. Regardless of case, this code must be unique across all active
    - `coupon` V1Coupon, required — A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions and checkout sessions.
      - `coupon_id` string, required — Unique identifier for the object.
      - `amount_off` integer, nullable — Amount that will be taken off the subtotal of any invoices for this customer.
      - `applies_to` union — What a coupon's discount is restricted to.
        - object
          - `products` string[], required — The product that this coupon applies to.
        - object
          - `prices` string[], required — The price that this coupon applies to.
        - object
          - `fee_types` FeeType[], required — The fee types that this coupon applies to.
        - 'shipping' — The coupon applies to shipping.
      - `duration` 'once' | 'repeating' | 'forever', required — - `once`: Applies to the first charge from a subscription with this coupon applied. - `repeating`: Applies to charges in the first duration_in_months months from a subscription with this coupon applied. - `forever`: Applies to all charges from a subscription with this coupon applied.
      - `duration_in_months` integer, nullable — If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.
      - `metadata` object, nullable — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
      - `name` string, required — Name of the coupon displayed to customers.
      - `percent_off` number, double, nullable — Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon.
      - `max_redemptions` integer, nullable — Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.
      - `times_redeemed` integer, nullable — Number of times this coupon has been applied to a customer.
      - `valid` boolean, required — Taking account of the above properties, whether this coupon can still be applied to a customer.
      - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
      - `test_mode` boolean, required — Whether the coupon is in test mode
    - `max_redemptions` integer, nullable — The number of times the promo code can be redeemed.
    - `times_redeemed` integer, required — The number of times the promo code has been redeemed.
    - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `customer` string, nullable — The customer that can be associated with the promo code. If null, the promo code can be redeemed by any customer.
    - `active` boolean, required — Whether the promo code is currently active.
    - `metadata` object, nullable — Metadata associated with the promo code.
    - `test_mode` boolean, required — Whether the promo code is in test mode.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)