--- title: "Create a promotional code" method: POST path: "/promotional-codes" --- # Create a promotional code `POST /promotional-codes` Creates a promotional code against an existing coupon. `couponId` is always required — the coupon supplies the discount. There are two ways to create a code: - **Give it yourself.** Send `code` with the exact string you want. It must be unique within the program. - **Have it generated.** Set `isAutoGenerated` to `true` and send `codeStructure` describing which pieces to combine — the affiliate's first name, last name, email prefix, the discount value, the coupon name, and/or random characters. An affiliate is required in this mode, and you can shape the result further with `prefix`, `randomCharsLength` and `randomCharsCase`. Assign the code to an affiliate with `affiliateId` or `affiliateEmail` so their redemptions are tracked. Assigned codes are also connected to that affiliate's links automatically in the background. Fires the `promotional_code.created` webhook. ## Request body - NewPromotionalCode - `couponId` string, uuid, required — The coupon ID this promotional code belongs to - `code` string — The exact code string customers will type. Required unless `isAutoGenerated` is `true`. Must be unique within the program. - `affiliateId` string, uuid — Assign the code to this affiliate so their redemptions are credited. Required when `isAutoGenerated` is `true` unless `affiliateEmail` is supplied. - `affiliateEmail` string, email — Assign the code to the affiliate with this email address. Alternative to `affiliateId`. - `externalId` string — The code's ID in the connected billing provider, for example a Stripe promotion code ID - `active` boolean — Whether the code is active (default: true) - `expiresAt` string, date-time — Expiration date - `maxRedemptions` integer — Maximum redemptions - `firstTimeOrder` boolean — Limit to first-time orders (default: false) - `minimumAmount` number, float — Minimum purchase amount - `minimumAmountCurrency` string — Currency for minimum amount - `limitToCustomers` boolean — Limit to specific customers (default: false) - `customerId` string — Specific customer ID - `limitToAffiliate` boolean — Only affiliate can use (default: false) - `isAutoGenerated` boolean — Generate the code from `codeStructure` instead of using `code`. Requires an affiliate. - `codeStructure` object — Which pieces to combine into the generated code, in this order: first name, last name, email prefix, discount value, coupon name, then random characters. Required when `isAutoGenerated` is `true`. - `firstName` boolean — Include affiliate's first name - `lastName` boolean — Include affiliate's last name - `email` boolean — Include part of affiliate's email - `discountAmount` boolean — Include discount value - `couponName` boolean — Include coupon name - `randomChars` boolean — Add random characters - `prefix` string — String placed at the front of a generated code - `randomCharsLength` integer — Length of random characters (default: 4) - `randomCharsCase` 'uppercase' | 'lowercase' | 'mixed' — Case for random characters (default: mixed) ## Response `200` The created promotional code, with its parent coupon and assigned affiliate. - 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` — `couponId` was missing; `code` was missing and `isAutoGenerated` was not set; `isAutoGenerated` was set without an affiliate; or the resulting code already exists in this program. - `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 coupon was not found in this program, or the affiliate was not found. - `429` — Too many requests for this token on this endpoint. Please slow down. - `500` — The promotional code 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)