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

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

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)

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

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

affiliate
object | null

Affiliate details

I