---
title: "Create a coupon"
method: POST
path: "/coupons"
---

# Create a coupon

`POST /coupons`

Creates a coupon — the discount definition that promotional codes are built on.

Only `name` is required. Set `couponType` to `PERCENTAGE` and supply `percentOff` (1–100), or set it to `FLAT` and supply both `amountOff` and `currency`. When `couponType` is omitted the coupon is stored as `PERCENTAGE`, so send `percentOff` alongside it.

`duration` controls how long the discount keeps applying to a subscription: `once`, `forever` (the default here), or `repeating` — which additionally requires `durationInMonths`.

Fires the `coupon.created` webhook.

## Request body

- NewCoupon
  - `name` string, required — Name of the coupon
  - `couponType` 'PERCENTAGE' | 'FLAT' — Whether the discount is a percentage or a fixed amount
  - `percentOff` number, float — Percentage taken off, 1–100. Required when `couponType` is `PERCENTAGE`.
  - `amountOff` number, float — Fixed amount taken off. Required when `couponType` is `FLAT`.
  - `currency` string — Currency for `amountOff`. Required when `couponType` is `FLAT`.
  - `duration` 'once' | 'forever' | 'repeating' — How long the discount keeps applying to a subscription
  - `durationInMonths` integer — Number of months the discount repeats for. Required when `duration` is `repeating`.
  - `maxRedemptions` integer — Total redemptions allowed across every promotional code on this coupon. Omit for unlimited.
  - `limitToProducts` boolean — Restrict the coupon to `productIds`
  - `productIds` string[] — Products the coupon applies to
  - `valid` boolean — Whether the coupon can be redeemed straight away
  - `redeemBy` string, date-time — Last date the coupon can be redeemed
  - `externalId` string — The coupon's ID in the connected billing provider. Must be unique.
  - `integrationType` 'NONE' | 'STRIPE' | 'CHARGEBEE' | 'PADDLE' | 'SHOPIFY' | 'WOOCOMMERCE' | 'ZYLVIE' | 'POLAR' — The billing provider this coupon is synced with

## Response `200`

The created coupon.

- Coupon — A discount definition. Promotional codes point at a coupon for their value.
  - `id` string, uuid — The coupon ID
  - `name` string, nullable — Name of the coupon
  - `externalId` string, nullable — The coupon's ID in the connected billing provider, for example a Stripe coupon ID
  - `couponType` 'PERCENTAGE' | 'FLAT' — Whether the discount is a percentage or a fixed amount
  - `percentOff` number, float, nullable — Percentage taken off, 1–100. Used when `couponType` is `PERCENTAGE`.
  - `amountOff` number, float, nullable — Fixed amount taken off. Used when `couponType` is `FLAT`.
  - `currency` string, nullable — Currency for `amountOff`, for example `USD`
  - `duration` 'once' | 'forever' | 'repeating' — How long the discount keeps applying to a subscription
  - `durationInMonths` integer, nullable — Number of months the discount repeats for. Only set when `duration` is `repeating`.
  - `maxRedemptions` integer, nullable — Total redemptions allowed across every promotional code on this coupon. `null` means unlimited.
  - `timesRedeemed` integer — How many times this coupon has been redeemed so far
  - `couponCategory` 'CUSTOMER' | 'PAYOUT' — Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward
  - `limitToProducts` boolean — Whether the coupon only applies to `productIds`
  - `productIds` string[] — Products the coupon is restricted to
  - `collectionIds` string[] — Collections the coupon is restricted to
  - `valid` boolean — Whether the coupon can currently be redeemed
  - `redeemBy` string, date-time, nullable — Last date the coupon can be redeemed
  - `integrationType` 'NONE' | 'STRIPE' | 'CHARGEBEE' | 'PADDLE' | 'SHOPIFY' | 'WOOCOMMERCE' | 'ZYLVIE' | 'POLAR', nullable — The billing provider this coupon is synced with
  - `affiliateProgramId` string, uuid — The affiliate program this coupon belongs to
  - `createdAt` string, date-time — When the coupon was created
  - `updatedAt` string, date-time — When the coupon was last updated
  - `promotionalCodes` PromotionalCode[] — Promotional codes that point at this coupon
    - `id` string, uuid — The promotional code ID
    - `code` string — The actual promotional code string
    - `couponId` string, uuid — The parent coupon ID
    - `affiliateId` string, uuid, nullable — The affiliate ID this code is assigned to
    - `externalId` string, nullable — External ID (e.g., Stripe promotion code ID)
    - `active` boolean — Whether the promotional code is active
    - `expiresAt` string, date-time, nullable — Expiration date for the code
    - `maxRedemptions` integer, nullable — How many times this code can be redeemed. `null` means unlimited. Redemptions are also capped by the parent coupon's own limit.
    - `timesRedeemed` integer — Number of times this code has been redeemed
    - `firstTimeOrder` boolean — Whether this code is limited to first-time orders
    - `minimumAmount` number, float, nullable — Minimum purchase amount required
    - `minimumAmountCurrency` string, nullable — Currency for minimum amount
    - `limitToCustomers` boolean — Whether code is limited to specific customers
    - `customerId` string, nullable — Specific customer ID this code is limited to
    - `limitToAffiliate` boolean — Whether only the assigned affiliate may redeem this code
    - `isAutoGenerated` boolean — Whether this code was generated from a `codeStructure` rather than supplied by hand
    - `createdAt` string, date-time — Timestamp when the code was created
    - `updatedAt` string, date-time — Timestamp when the code was last updated
    - `coupon` Coupon — recursive
    - `affiliate` object, nullable — Affiliate details
      - `id` string, uuid
      - `firstName` string
      - `lastName` string
      - `email` string, email
    - `isAffiliateGenerated` boolean — Whether the affiliate created this code themselves from their portal
  - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured

## Other responses

- `400` — `name` was missing; `couponType` is `PERCENTAGE` and `percentOff` is missing or outside 1–100; `couponType` is `FLAT` and `amountOff` or `currency` is missing; `duration` is `repeating` and `durationInMonths` is missing; or a coupon with this `externalId` already exists.
- `401` — The `Authorization` header is missing, is not a `Bearer` header, or the token is not valid.
- `403` — API access is not enabled for this account.
- `404` — The affiliate program this token belongs to no longer exists.
- `429` — Too many requests for this token on this endpoint. Please slow down.
- `500` — The coupon could not be created.

---

[API](https://skmtc.net/referly/apis/referly-api.md) · [All operations](https://skmtc.net/referly/apis/referly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/referly/referly-api/revisions/0f506d61b9c3/schema)