Create a Promotional Code

Create a new promotional code

curl --request POST \
  --url https://www.pushlapgrowth.com/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateEmail": "[email protected]",
  "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": 123,
  "randomCharsCase": "uppercase"
}
'

{
  "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>",
    "couponType": "PERCENTAGE",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "<string>",
    "duration": "once",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "limitToProducts": true,
    "productIds": [
      "<string>"
    ],
    "valid": true,
    "redeemBy": "2023-11-07T05:31:56Z",
    "integrationType": "<string>",
    "affiliateProgramId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "promotionalCodes": "<array>"
  },
  "affiliate": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "[email protected]"
  }
}

POST

promotional-codes

Create a new promotional code

curl --request POST \
  --url https://www.pushlapgrowth.com/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "couponId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "<string>",
  "affiliateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "affiliateEmail": "[email protected]",
  "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": 123,
  "randomCharsCase": "uppercase"
}
'

{
  "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>",
    "couponType": "PERCENTAGE",
    "percentOff": 123,
    "amountOff": 123,
    "currency": "<string>",
    "duration": "once",
    "durationInMonths": 123,
    "maxRedemptions": 123,
    "limitToProducts": true,
    "productIds": [
      "<string>"
    ],
    "valid": true,
    "redeemBy": "2023-11-07T05:31:56Z",
    "integrationType": "<string>",
    "affiliateProgramId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "promotionalCodes": "<array>"
  },
  "affiliate": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "[email protected]"
  }
}

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

Promotional code details

couponId

string<uuid>

required

The coupon ID this promotional code belongs to

code

string

The promotional code string (required if not auto-generated)

affiliateId

string<uuid>

The affiliate ID to assign this code to

affiliateEmail

string<email>

The affiliate email (alternative to affiliateId)

externalId

string

External ID (e.g., 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

Whether to auto-generate the code (default: false)

codeStructure

object

Structure for auto-generated codes (required if isAutoGenerated is true)

Show child attributes

codeStructure.firstName

boolean

Include affiliate's first name

codeStructure.lastName

boolean

Include affiliate's last name

codeStructure.email

boolean

Include part of affiliate's email

codeStructure.discountAmount

boolean

Include discount value

codeStructure.couponName

boolean

Include coupon name

codeStructure.randomChars

boolean

Add random characters

prefix

string

Prefix for auto-generated codes

randomCharsLength

integer

Length of random characters (default: 4)

randomCharsCase

enum<string>

Case for random characters (default: mixed)

Available options:

uppercase,

lowercase,

mixed

Response

Promotional code created successfully

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

Maximum number of times this code can be used

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 affiliate can use this code

isAutoGenerated

boolean

Whether this code was auto-generated

createdAt

string<date-time>

Timestamp when the code was created

updatedAt

string<date-time>

Timestamp when the code was last updated

coupon

object

The parent coupon details

Show child attributes

coupon.id

string<uuid>

The coupon ID

coupon.name

string

Name of the coupon

coupon.externalId

string | null

External ID (e.g., Stripe coupon ID)

coupon.couponType

enum<string>

Type of discount - percentage or flat amount

Available options:

PERCENTAGE,

FLAT

coupon.percentOff

number<float> | null

Percentage off (1-100) for percentage coupons

coupon.amountOff

number<float> | null

Amount off for flat coupons

coupon.currency

string | null

Currency for flat amount coupons (e.g., USD, EUR)

coupon.duration

enum<string>

How long the discount applies

Available options:

once,

forever,

repeating

coupon.durationInMonths

integer | null

Number of months for repeating duration

coupon.maxRedemptions

integer | null

Maximum number of times this coupon can be redeemed

coupon.limitToProducts

boolean

Whether coupon is limited to specific products

coupon.productIds

string[]

Array of product IDs this coupon applies to

coupon.valid

boolean

Whether the coupon is currently valid

coupon.redeemBy

string<date-time> | null

Date by which the coupon must be redeemed

coupon.integrationType

string | null

Integration type (e.g., stripe, custom)

coupon.affiliateProgramId

string<uuid>

The affiliate program ID

coupon.createdAt

string<date-time>

Timestamp when the coupon was created

coupon.updatedAt

string<date-time>

Timestamp when the coupon was last updated

coupon.promotionalCodes

array

Promotional codes associated with this coupon

affiliate

object

Affiliate details

Show child attributes

affiliate.id

string<uuid>

affiliate.firstName

string

affiliate.lastName

string

affiliate.email

string<email>

Get Promotional Codes Delete a Promotional Code

⌘I

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

Creating Promotional Codes

Manual vs Auto-Generated Codes

Manual Codes

Auto-Generated Codes

Code Structure Options

Additional Settings

Authorizations

Body

Response

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

​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