Create a promotional code

curl --request POST \
  --url https://www.referly.so/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "JANE20",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateEmail": "jsmith@example.com",
  "externalId": "<string>",
  "active": true,
  "expiresAt": "2023-11-07T05:31:56Z",
  "maxRedemptions": 123,
  "firstTimeOrder": true,
  "minimumAmount": 123,
  "minimumAmountCurrency": "<string>",
  "limitToCustomers": true,
  "customerId": "<string>",
  "limitToAffiliate": true,
  "isAutoGenerated": true,
  "codeStructure": {
    "firstName": true,
    "lastName": true,
    "email": true,
    "discountAmount": true,
    "couponName": true,
    "randomChars": true
  },
  "prefix": "<string>",
  "randomCharsLength": 4,
  "randomCharsCase": "mixed"
}
'

import requests

url = "https://www.referly.so/api/v1/promotional-codes"

payload = {
    "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "code": "JANE20",
    "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "affiliateEmail": "jsmith@example.com",
    "externalId": "<string>",
    "active": True,
    "expiresAt": "2023-11-07T05:31:56Z",
    "maxRedemptions": 123,
    "firstTimeOrder": True,
    "minimumAmount": 123,
    "minimumAmountCurrency": "<string>",
    "limitToCustomers": True,
    "customerId": "<string>",
    "limitToAffiliate": True,
    "isAutoGenerated": True,
    "codeStructure": {
        "firstName": True,
        "lastName": True,
        "email": True,
        "discountAmount": True,
        "couponName": True,
        "randomChars": True
    },
    "prefix": "<string>",
    "randomCharsLength": 4,
    "randomCharsCase": "mixed"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    couponId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    code: 'JANE20',
    affiliateId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    affiliateEmail: 'jsmith@example.com',
    externalId: '<string>',
    active: true,
    expiresAt: '2023-11-07T05:31:56Z',
    maxRedemptions: 123,
    firstTimeOrder: true,
    minimumAmount: 123,
    minimumAmountCurrency: '<string>',
    limitToCustomers: true,
    customerId: '<string>',
    limitToAffiliate: true,
    isAutoGenerated: true,
    codeStructure: {
      firstName: true,
      lastName: true,
      email: true,
      discountAmount: true,
      couponName: true,
      randomChars: true
    },
    prefix: '<string>',
    randomCharsLength: 4,
    randomCharsCase: 'mixed'
  })
};

fetch('https://www.referly.so/api/v1/promotional-codes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.referly.so/api/v1/promotional-codes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'couponId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'code' => 'JANE20',
    'affiliateId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'affiliateEmail' => 'jsmith@example.com',
    'externalId' => '<string>',
    'active' => true,
    'expiresAt' => '2023-11-07T05:31:56Z',
    'maxRedemptions' => 123,
    'firstTimeOrder' => true,
    'minimumAmount' => 123,
    'minimumAmountCurrency' => '<string>',
    'limitToCustomers' => true,
    'customerId' => '<string>',
    'limitToAffiliate' => true,
    'isAutoGenerated' => true,
    'codeStructure' => [
        'firstName' => true,
        'lastName' => true,
        'email' => true,
        'discountAmount' => true,
        'couponName' => true,
        'randomChars' => true
    ],
    'prefix' => '<string>',
    'randomCharsLength' => 4,
    'randomCharsCase' => 'mixed'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.referly.so/api/v1/promotional-codes"

	payload := strings.NewReader("{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.referly.so/api/v1/promotional-codes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.referly.so/api/v1/promotional-codes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "externalId": "<string>",
  "active": true,
  "expiresAt": "2023-11-07T05:31:56Z",
  "maxRedemptions": 123,
  "timesRedeemed": 123,
  "firstTimeOrder": true,
  "minimumAmount": 123,
  "minimumAmountCurrency": "<string>",
  "limitToCustomers": true,
  "customerId": "<string>",
  "limitToAffiliate": true,
  "isAutoGenerated": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "coupon": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "externalId": "<string>",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "<string>",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "timesRedeemed": 123,
    "limitToProducts": true,
    "productIds": [
      "<string>"
    ],
    "collectionIds": [
      "<string>"
    ],
    "valid": true,
    "redeemBy": "2023-11-07T05:31:56Z",
    "affiliateProgramId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "promotionalCodes": "<array>",
    "autoCouponRule": {}
  },
  "affiliate": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com"
  },
  "isAffiliateGenerated": true
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Promotional Code Endpoints

Create a Promotional Code

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.

POST

promotional-codes

Create a promotional code

curl --request POST \
  --url https://www.referly.so/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "JANE20",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateEmail": "jsmith@example.com",
  "externalId": "<string>",
  "active": true,
  "expiresAt": "2023-11-07T05:31:56Z",
  "maxRedemptions": 123,
  "firstTimeOrder": true,
  "minimumAmount": 123,
  "minimumAmountCurrency": "<string>",
  "limitToCustomers": true,
  "customerId": "<string>",
  "limitToAffiliate": true,
  "isAutoGenerated": true,
  "codeStructure": {
    "firstName": true,
    "lastName": true,
    "email": true,
    "discountAmount": true,
    "couponName": true,
    "randomChars": true
  },
  "prefix": "<string>",
  "randomCharsLength": 4,
  "randomCharsCase": "mixed"
}
'

import requests

url = "https://www.referly.so/api/v1/promotional-codes"

payload = {
    "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "code": "JANE20",
    "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "affiliateEmail": "jsmith@example.com",
    "externalId": "<string>",
    "active": True,
    "expiresAt": "2023-11-07T05:31:56Z",
    "maxRedemptions": 123,
    "firstTimeOrder": True,
    "minimumAmount": 123,
    "minimumAmountCurrency": "<string>",
    "limitToCustomers": True,
    "customerId": "<string>",
    "limitToAffiliate": True,
    "isAutoGenerated": True,
    "codeStructure": {
        "firstName": True,
        "lastName": True,
        "email": True,
        "discountAmount": True,
        "couponName": True,
        "randomChars": True
    },
    "prefix": "<string>",
    "randomCharsLength": 4,
    "randomCharsCase": "mixed"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    couponId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    code: 'JANE20',
    affiliateId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    affiliateEmail: 'jsmith@example.com',
    externalId: '<string>',
    active: true,
    expiresAt: '2023-11-07T05:31:56Z',
    maxRedemptions: 123,
    firstTimeOrder: true,
    minimumAmount: 123,
    minimumAmountCurrency: '<string>',
    limitToCustomers: true,
    customerId: '<string>',
    limitToAffiliate: true,
    isAutoGenerated: true,
    codeStructure: {
      firstName: true,
      lastName: true,
      email: true,
      discountAmount: true,
      couponName: true,
      randomChars: true
    },
    prefix: '<string>',
    randomCharsLength: 4,
    randomCharsCase: 'mixed'
  })
};

fetch('https://www.referly.so/api/v1/promotional-codes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.referly.so/api/v1/promotional-codes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'couponId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'code' => 'JANE20',
    'affiliateId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'affiliateEmail' => 'jsmith@example.com',
    'externalId' => '<string>',
    'active' => true,
    'expiresAt' => '2023-11-07T05:31:56Z',
    'maxRedemptions' => 123,
    'firstTimeOrder' => true,
    'minimumAmount' => 123,
    'minimumAmountCurrency' => '<string>',
    'limitToCustomers' => true,
    'customerId' => '<string>',
    'limitToAffiliate' => true,
    'isAutoGenerated' => true,
    'codeStructure' => [
        'firstName' => true,
        'lastName' => true,
        'email' => true,
        'discountAmount' => true,
        'couponName' => true,
        'randomChars' => true
    ],
    'prefix' => '<string>',
    'randomCharsLength' => 4,
    'randomCharsCase' => 'mixed'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.referly.so/api/v1/promotional-codes"

	payload := strings.NewReader("{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.referly.so/api/v1/promotional-codes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.referly.so/api/v1/promotional-codes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"couponId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"code\": \"JANE20\",\n  \"affiliateId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"affiliateEmail\": \"jsmith@example.com\",\n  \"externalId\": \"<string>\",\n  \"active\": true,\n  \"expiresAt\": \"2023-11-07T05:31:56Z\",\n  \"maxRedemptions\": 123,\n  \"firstTimeOrder\": true,\n  \"minimumAmount\": 123,\n  \"minimumAmountCurrency\": \"<string>\",\n  \"limitToCustomers\": true,\n  \"customerId\": \"<string>\",\n  \"limitToAffiliate\": true,\n  \"isAutoGenerated\": true,\n  \"codeStructure\": {\n    \"firstName\": true,\n    \"lastName\": true,\n    \"email\": true,\n    \"discountAmount\": true,\n    \"couponName\": true,\n    \"randomChars\": true\n  },\n  \"prefix\": \"<string>\",\n  \"randomCharsLength\": 4,\n  \"randomCharsCase\": \"mixed\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "externalId": "<string>",
  "active": true,
  "expiresAt": "2023-11-07T05:31:56Z",
  "maxRedemptions": 123,
  "timesRedeemed": 123,
  "firstTimeOrder": true,
  "minimumAmount": 123,
  "minimumAmountCurrency": "<string>",
  "limitToCustomers": true,
  "customerId": "<string>",
  "limitToAffiliate": true,
  "isAutoGenerated": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "coupon": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "externalId": "<string>",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "<string>",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "timesRedeemed": 123,
    "limitToProducts": true,
    "productIds": [
      "<string>"
    ],
    "collectionIds": [
      "<string>"
    ],
    "valid": true,
    "redeemBy": "2023-11-07T05:31:56Z",
    "affiliateProgramId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "promotionalCodes": "<array>",
    "autoCouponRule": {}
  },
  "affiliate": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com"
  },
  "isAffiliateGenerated": true
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Creating Promotional Codes

Create promotional codes that customers can use at checkout. Each promotional code must be linked to an existing coupon.

Manual vs Auto-Generated Codes

Manual Codes

Specify the exact code string you want to create:

{
  "couponId": "coupon_123",
  "code": "SAVE20",
  "affiliateId": "affiliate_456"
}

Auto-Generated Codes

Let the system generate codes based on a structure:

{
  "couponId": "coupon_123",
  "affiliateId": "affiliate_456",
  "isAutoGenerated": true,
  "codeStructure": {
    "firstName": true,
    "randomChars": true
  },
  "prefix": "SAVE",
  "randomCharsLength": 4,
  "randomCharsCase": "uppercase"
}

This would generate a code like: SAVEJOHN8X4Z

Code Structure Options

When using auto-generated codes, you can combine:

firstName: Include affiliate’s first name
lastName: Include affiliate’s last name
email: Include part of affiliate’s email (before @)
discountAmount: Include the discount value
couponName: Include the coupon name
randomChars: Add random characters

Additional Settings

active: Whether the code is currently active
expiresAt: Expiration date for the code
maxRedemptions: Maximum number of times the code can be used
firstTimeOrder: Limit to first-time customers only
minimumAmount: Minimum purchase amount required
limitToAffiliate: Only the affiliate can use this code
limitToCustomers: Restrict to specific customers

The coupon must exist before creating promotional codes. The promotional code inherits its discount properties from the parent coupon.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The promotional code to create

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.

Example:

"JANE20"

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.

Show child attributes

prefix

string

String placed at the front of a generated code

randomCharsLength

integer

default:4

Length of random characters (default: 4)

randomCharsCase

enum<string>

default:mixed

Case for random characters (default: mixed)

Available options:

uppercase,

lowercase,

mixed

Response

The created promotional code, with its parent coupon and assigned affiliate.

A code customers enter at checkout. Its discount comes from the coupon it belongs to.

string<uuid>

The promotional code ID

code

string

The actual promotional code string

couponId

string<uuid>

The parent coupon ID

affiliateId

string<uuid> | null

The affiliate ID this code is assigned to

externalId

string | null

External ID (e.g., Stripe promotion code ID)

active

boolean

Whether the promotional code is active

expiresAt

string<date-time> | null

Expiration date for the code

maxRedemptions

integer | null

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> | null

Minimum purchase amount required

minimumAmountCurrency

string | null

Currency for minimum amount

limitToCustomers

boolean

Whether code is limited to specific customers

customerId

string | null

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

object

The coupon this code takes its discount from

Show child attributes

affiliate

object | null

Affiliate details

Show child attributes

isAffiliateGenerated

boolean

Whether the affiliate created this code themselves from their portal

Last modified on July 20, 2026

Get Promotional Codes

Delete a Promotional Code

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

Create a Promotional Code

Creating Promotional Codes

Manual vs Auto-Generated Codes

Manual Codes

Auto-Generated Codes

Code Structure Options

Additional Settings

Authorizations

Body

Response

​Creating Promotional Codes

​Manual vs Auto-Generated Codes

​Manual Codes

​Auto-Generated Codes

​Code Structure Options

​Additional Settings

Authorizations

Body

Response

Creating Promotional Codes

Manual vs Auto-Generated Codes

Manual Codes

Auto-Generated Codes

Code Structure Options

Additional Settings