Get Promotional Codes

Get all promotional codes or by ID/code/couponId/affiliateId

curl --request GET \
  --url https://www.pushlapgrowth.com/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>'

{
  "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]"
  }
}

GET

promotional-codes

Get all promotional codes or by ID/code/couponId/affiliateId

curl --request GET \
  --url https://www.pushlapgrowth.com/api/v1/promotional-codes \
  --header 'Authorization: Bearer <token>'

{
  "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]"
  }
}

Understanding Promotional Codes

Promotional codes are the actual discount codes that customers enter at checkout. Each promotional code is linked to a coupon, which defines the discount structure (amount, type, duration, etc.).

Key Concepts

Promotional codes are the customer-facing codes (e.g., “JOHN20”, “SAVE20”, “AFFILIATE10”)
They inherit their discount properties from the parent coupon
Multiple promotional codes can share the same coupon (same discount, different codes)
Each promotional code can be assigned to a specific affiliate for tracking

Query Options

You can retrieve promotional codes by:

id: Get a specific promotional code by ID
code: Get a promotional code by the actual code string
externalId: Get by external ID (e.g., Stripe promotion code ID)
couponId: Get all promotional codes for a specific coupon
affiliateId: Get all promotional codes for a specific affiliate
affiliateEmail: Get all promotional codes for an affiliate by email

If no parameters are provided, all promotional codes for your program are returned.

Authorizations

Authorization

string

header

required

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

Query Parameters

string<uuid>

The ID of the promotional code to retrieve

code

string

The promotional code string to retrieve

externalId

string

The external ID (e.g., Stripe promotion code ID)

couponId

string<uuid>

Get all promotional codes for a specific coupon

affiliateId

string<uuid>

Get all promotional codes for a specific affiliate

affiliateEmail

string<email>

Get all promotional codes for an affiliate by email

Response

A list of promotional codes or a single promotional code

object
object[]

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>

Update a Coupon Create a Promotional Code

⌘I

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

Understanding Promotional Codes

Key Concepts

Query Options

Authorizations

Query Parameters

Response

API Documentation

Affiliate Endpoints

Referral Endpoints

Sale Endpoints

Affiliate Link Endpoints

Coupon Endpoints

Promotional Code Endpoints

​Understanding Promotional Codes

​Key Concepts

​Query Options

Authorizations

Query Parameters

Response

Understanding Promotional Codes

Key Concepts

Query Options