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

​
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

​
id
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[]
​
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