---
title: "Create Coupon"
method: POST
path: "/v1/coupons"
tags: ["Coupons"]
---

# Create Coupon

`POST /v1/coupons`

Creates a coupon. Exactly one of `amount_off` or `percent_off` must be provided; supplying
both, or neither, is rejected. When `duration` is `repeating`, `duration_in_months` is
required.

## Request body

- CouponBodyForCreateCouponRequest — An envelope wrapping a single coupon object.
  - `coupon` CreateCouponRequest, required — Parameters for creating a coupon. Exactly one of `amount_off` or `percent_off` must be set.
    - `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.
    - `name` string, required — Name of the coupon displayed to customers.
    - `amount_off` integer, nullable — A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).
    - `duration` 'once' | 'repeating' | 'forever' — - `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 — Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.
    - `percent_off` number, double, nullable — A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).
    - `max_redemptions` integer, nullable — A positive integer specifying the number of times the coupon can be redeemed before it’s no longer valid.
    - `metadata` object, nullable — Metadata to attach to this coupon.

## Response `200`

An envelope wrapping a single coupon object.

- CouponBodyForV1Coupon — An envelope wrapping a single coupon object.
  - `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

## Other responses

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

---

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