---
title: "Update a promotional code"
method: PUT
path: "/promotional-codes"
---

# Update a promotional code

`PUT /promotional-codes`

Updates a promotional code identified by `promotionalCodeId`, and fires the `promotional_code.updated` webhook.

Set `active` to `false` to switch a code off without deleting it — this is the safe way to retire a code an affiliate has already shared. Changing `code` renames it, and the new string must be unique within the program.

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

## Request body

- PromotionalCodeUpdate
  - `promotionalCodeId` string, uuid, required — The promotional code ID to update
  - `code` string — Rename the code. Must be unique within the program.
  - `active` boolean — Set to `false` to retire the code without deleting it
  - `expiresAt` string, date-time — Expiration date
  - `maxRedemptions` integer — Maximum redemptions
  - `firstTimeOrder` boolean — Limit to first-time orders
  - `minimumAmount` number, float — Minimum purchase amount
  - `minimumAmountCurrency` string — Currency for minimum amount
  - `limitToCustomers` boolean — Limit to specific customers
  - `customerId` string — Specific customer ID
  - `limitToAffiliate` boolean — Only affiliate can use
  - `externalId` string — The code's ID in the connected billing provider

## Response `200`

The updated promotional code.

- PromotionalCode — A code customers enter at checkout. Its discount comes from the coupon it belongs to.
  - `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 — 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
    - `autoCouponRule` object, nullable — Rule used to generate codes automatically for affiliates, if configured
  - `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

## Other responses

- `400` — `promotionalCodeId` was missing, the new `code` is already used in this program, 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 promotional code with that ID exists in this program.
- `429` — Too many requests for this token on this endpoint. Please slow down.
- `500` — The promotional code 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)