Create a coupon

curl --request POST \
  --url https://www.referly.so/api/v1/coupons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Launch 20%",
  "couponType": "PERCENTAGE",
  "percentOff": 123,
  "amountOff": 123,
  "currency": "USD",
  "duration": "forever",
  "durationInMonths": 123,
  "maxRedemptions": 123,
  "limitToProducts": false,
  "productIds": [
    "<string>"
  ],
  "valid": true,
  "redeemBy": "2023-11-07T05:31:56Z",
  "externalId": "<string>"
}
'

import requests

url = "https://www.referly.so/api/v1/coupons"

payload = {
    "name": "Launch 20%",
    "couponType": "PERCENTAGE",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "USD",
    "duration": "forever",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "limitToProducts": False,
    "productIds": ["<string>"],
    "valid": True,
    "redeemBy": "2023-11-07T05:31:56Z",
    "externalId": "<string>"
}
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({
    name: 'Launch 20%',
    couponType: 'PERCENTAGE',
    percentOff: 123,
    amountOff: 123,
    currency: 'USD',
    duration: 'forever',
    durationInMonths: 123,
    maxRedemptions: 123,
    limitToProducts: false,
    productIds: ['<string>'],
    valid: true,
    redeemBy: '2023-11-07T05:31:56Z',
    externalId: '<string>'
  })
};

fetch('https://www.referly.so/api/v1/coupons', 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/coupons",
  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([
    'name' => 'Launch 20%',
    'couponType' => 'PERCENTAGE',
    'percentOff' => 123,
    'amountOff' => 123,
    'currency' => 'USD',
    'duration' => 'forever',
    'durationInMonths' => 123,
    'maxRedemptions' => 123,
    'limitToProducts' => false,
    'productIds' => [
        '<string>'
    ],
    'valid' => true,
    'redeemBy' => '2023-11-07T05:31:56Z',
    'externalId' => '<string>'
  ]),
  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/coupons"

	payload := strings.NewReader("{\n  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\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/coupons")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.referly.so/api/v1/coupons")

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  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\n}"

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

{
  "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": [
    {
      "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": "<unknown>",
      "affiliate": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "jsmith@example.com"
      },
      "isAffiliateGenerated": true
    }
  ],
  "autoCouponRule": {}
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Coupon Endpoints

Create a Coupon

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.

POST

coupons

Create a coupon

curl --request POST \
  --url https://www.referly.so/api/v1/coupons \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Launch 20%",
  "couponType": "PERCENTAGE",
  "percentOff": 123,
  "amountOff": 123,
  "currency": "USD",
  "duration": "forever",
  "durationInMonths": 123,
  "maxRedemptions": 123,
  "limitToProducts": false,
  "productIds": [
    "<string>"
  ],
  "valid": true,
  "redeemBy": "2023-11-07T05:31:56Z",
  "externalId": "<string>"
}
'

import requests

url = "https://www.referly.so/api/v1/coupons"

payload = {
    "name": "Launch 20%",
    "couponType": "PERCENTAGE",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "USD",
    "duration": "forever",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "limitToProducts": False,
    "productIds": ["<string>"],
    "valid": True,
    "redeemBy": "2023-11-07T05:31:56Z",
    "externalId": "<string>"
}
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({
    name: 'Launch 20%',
    couponType: 'PERCENTAGE',
    percentOff: 123,
    amountOff: 123,
    currency: 'USD',
    duration: 'forever',
    durationInMonths: 123,
    maxRedemptions: 123,
    limitToProducts: false,
    productIds: ['<string>'],
    valid: true,
    redeemBy: '2023-11-07T05:31:56Z',
    externalId: '<string>'
  })
};

fetch('https://www.referly.so/api/v1/coupons', 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/coupons",
  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([
    'name' => 'Launch 20%',
    'couponType' => 'PERCENTAGE',
    'percentOff' => 123,
    'amountOff' => 123,
    'currency' => 'USD',
    'duration' => 'forever',
    'durationInMonths' => 123,
    'maxRedemptions' => 123,
    'limitToProducts' => false,
    'productIds' => [
        '<string>'
    ],
    'valid' => true,
    'redeemBy' => '2023-11-07T05:31:56Z',
    'externalId' => '<string>'
  ]),
  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/coupons"

	payload := strings.NewReader("{\n  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\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/coupons")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.referly.so/api/v1/coupons")

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  \"name\": \"Launch 20%\",\n  \"couponType\": \"PERCENTAGE\",\n  \"percentOff\": 123,\n  \"amountOff\": 123,\n  \"currency\": \"USD\",\n  \"duration\": \"forever\",\n  \"durationInMonths\": 123,\n  \"maxRedemptions\": 123,\n  \"limitToProducts\": false,\n  \"productIds\": [\n    \"<string>\"\n  ],\n  \"valid\": true,\n  \"redeemBy\": \"2023-11-07T05:31:56Z\",\n  \"externalId\": \"<string>\"\n}"

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

{
  "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": [
    {
      "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": "<unknown>",
      "affiliate": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "jsmith@example.com"
      },
      "isAffiliateGenerated": true
    }
  ],
  "autoCouponRule": {}
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Creating Coupons

Create a new coupon definition that can be used to generate promotional codes for your affiliates.

Coupon Types

PERCENTAGE: Discount based on a percentage (e.g., 20% off)
FLAT: Fixed amount discount (e.g., $10 off)

Duration Options

once: Applies to a single payment
forever: Applies to all future payments
repeating: Applies for a specific number of months

After creating a coupon, you’ll need to create promotional codes linked to this coupon. Promotional codes are the actual discount codes that customers will enter at checkout.

Authorizations

Authorization

string

header

required

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

Body

application/json

The coupon to create

name

string

required

Name of the coupon

Example:

"Launch 20%"

couponType

enum<string>

default:PERCENTAGE

Whether the discount is a percentage or a fixed amount

Available options:

PERCENTAGE,

FLAT

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.

Example:

"USD"

duration

enum<string>

default:forever

How long the discount keeps applying to a subscription

Available options:

once,

forever,

repeating

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

default:false

Restrict the coupon to productIds

productIds

string[]

Products the coupon applies to

valid

boolean

default:true

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

enum<string>

The billing provider this coupon is synced with

Available options:

NONE,

STRIPE,

CHARGEBEE,

PADDLE,

SHOPIFY,

WOOCOMMERCE,

ZYLVIE,

POLAR

Response

The created coupon.

A discount definition. Promotional codes point at a coupon for their value.

string<uuid>

The coupon ID

name

string | null

Name of the coupon

externalId

string | null

The coupon's ID in the connected billing provider, for example a Stripe coupon ID

couponType

enum<string>

Whether the discount is a percentage or a fixed amount

Available options:

PERCENTAGE,

FLAT

percentOff

number<float> | null

Percentage taken off, 1–100. Used when couponType is PERCENTAGE.

amountOff

number<float> | null

Fixed amount taken off. Used when couponType is FLAT.

currency

string | null

Currency for amountOff, for example USD

duration

enum<string>

How long the discount keeps applying to a subscription

Available options:

once,

forever,

repeating

durationInMonths

integer | null

Number of months the discount repeats for. Only set when duration is repeating.

maxRedemptions

integer | null

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

enum<string>

Whether the coupon discounts customers or is used to pay affiliates as a non-cash reward

Available options:

CUSTOMER,

PAYOUT

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

Last date the coupon can be redeemed

integrationType

enum<string> | null

The billing provider this coupon is synced with

Available options:

NONE,

STRIPE,

CHARGEBEE,

PADDLE,

SHOPIFY,

WOOCOMMERCE,

ZYLVIE,

POLAR

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

object[]

Promotional codes that point at this coupon

Show child attributes

autoCouponRule

object | null

Rule used to generate codes automatically for affiliates, if configured

Last modified on July 20, 2026

Get Coupons

Delete a Coupon

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

Create a Coupon

Creating Coupons

Coupon Types

Duration Options

Authorizations

Body

Response

​Creating Coupons

​Coupon Types

​Duration Options

Authorizations

Body

Response

Creating Coupons

Coupon Types

Duration Options