---
title: "Update a coupon"
method: PUT
path: "/coupons"
---

# Update a coupon

`PUT /coupons`

Updates a coupon identified by `couponId`, and fires the `coupon.updated` webhook.

Changing the discount affects every promotional code that points at this coupon, including codes already in circulation. Set `valid` to `false` to stop a coupon being applied without deleting it.

Every field you send is applied directly to the coupon, so sending a field that is not listed below will fail the request.

## Request body

- CouponUpdate
  - `couponId` string, uuid, required — The coupon to update
  - `name` string — 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
  - `amountOff` number, float — Fixed amount taken off. Must be greater than zero.
  - `currency` string — Currency for `amountOff`
  - `duration` 'once' | 'forever' | 'repeating' — How long the discount keeps applying to a subscription
  - `durationInMonths` integer — Number of months the discount repeats for
  - `maxRedemptions` integer — Total redemptions allowed
  - `limitToProducts` boolean — Restrict the coupon to `productIds`
  - `productIds` string[] — Products the coupon applies to
  - `valid` boolean — Set to `false` to stop the coupon being redeemed
  - `redeemBy` string, date-time — Last date the coupon can be redeemed

## Response `200`

The updated 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` — `couponId` was missing, `percentOff` is outside 1–100, `amountOff` is not greater than zero, or the request contained a field that cannot be updated.
- `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` — No coupon with that ID exists in this program.
- `429` — Too many requests for this token on this endpoint. Please slow down.
- `500` — The coupon could not be updated.

---

[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)