Skip to content

Promotion Unique Codes Management ​

Use these endpoints to bulk generate, list, disable, and export individual, single-use coupon codes under a promotional campaign.

Common Authentication & Headers ​

  • Requires merchant authentication: Authorization: Bearer JWT_TOKEN.
  • Requires X-MerchantApiKey: MERCHANT_API_KEY.

1. List Promotion Codes ​

Endpoint ​

GET /v1/promotions/{promotionId}/codes

Query parameters ​

ParameterTypeRequiredDescription
pageintegerNoZero-based page number. Default: 0.
limitintegerNoItems per page (default 20).
statusstringNoFilter by code status (ACTIVE, REDEEMED, DISABLED).

Responses (200 OK) ​

json
{
  "status": true,
  "message": "Promotion codes retrieved successfully",
  "data": {
    "items": [
      {
        "id": "67c1aa12d43a5c1234567801",
        "code": "VIP-9A8B7C",
        "status": "ACTIVE",
        "redemptionCount": 0,
        "createdAt": "2026-03-08T14:00:00Z"
      }
    ],
    "total": 1,
    "page": 0,
    "limit": 20
  }
}

2. Bulk Generate Promotion Codes ​

Generates unique single-use coupon codes under the promotion.

Endpoint ​

POST /v1/promotions/{promotionId}/codes/generate

Request body ​

Field NameTypeRequiredDescription
countintegerYesNumber of codes to generate (1 - 1000).
prefixstringNoOptional code prefix string (e.g. VIP).
json
{
  "count": 100,
  "prefix": "VIP"
}

Responses (200 OK) ​

json
{
  "status": true,
  "message": "100 promotion codes generated successfully",
  "data": {
    "generatedCount": 100
  }
}

3. Disable a Promotion Code ​

Deactivates a specific promotion code so it can no longer be redeemed.

Endpoint ​

POST /v1/promotions/{promotionId}/codes/{codeId}/disable

Responses (200 OK) ​

json
{
  "status": true,
  "message": "Promotion code disabled successfully",
  "data": null
}

4. Export Promotion Codes as CSV ​

Downloads all generated coupon codes for the campaign in CSV format.

Endpoint ​

GET /v1/promotions/{promotionId}/codes/export

Response ​

Returns a CSV file attachment with columns: Code,Status,RedemptionCount,CreatedAt.

Build with joy