Skip to content

Show Promotion Code ​

Description ​

This API allows client to retrieve details of a specific promotion by its ID.

Endpoint ​

  • URL: /v1/promotions/{promotionId}
  • Method: GET

Path-parameters:

ParameterTypeRequiredDescriptionSinceExample
promotionIdstringtrueThe ID of the promotion to retrieve.-

Required Headers ​

json
{
  "Authorization": "Bearer JWT_TOKEN",
  "X-MerchantApiKey": "MERCHANT_API_KEY",
  "Content-Type": "application/json"
}

Example API Call (Using Fetch) ​

javascript
fetch("https://api.shopsynch.com/v1/promotions/679f8f5a3b5f2173201c2582", {
  method: "GET",
  headers: {
    "Authorization": "Bearer JWT_TOKEN",
    "X-MerchantApiKey": "MERCHANT_API_KEY",
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Response-fields:

FieldTypeDescriptionSinceExample
statusbooleanNo comments found.-true
messagestringNo comments found.-
dataobjectNo comments found.-
└─createdAtstringNo comments found.-yyyy-MM-dd HH:mm:ss
└─updatedAtstringNo comments found.-yyyy-MM-dd HH:mm:ss
└─idstringNo comments found.-
└─namestringName of promotion-
└─codestringThe code that customers will use to redeem the promotion-
└─descriptionstringA description of the promotion-
└─startDatestringThe start date and time of the promotion-yyyy-MM-dd HH:mm:ss
└─endDatestringThe end date and time of the promotion-yyyy-MM-dd HH:mm:ss
└─discountTypeenumThe type of discount this promotion applies.
Defaults to PERCENTAGE for backward compatibility with existing promotions
that were created before discount types were introduced.
[Enum: PERCENTAGE, FLAT_AMOUNT, FREE_SHIPPING, BUY_X_GET_Y]
-PERCENTAGE
└─discountValuenumberThe discount value — interpretation depends on discountType:
PERCENTAGE → value is a percentage. e.g. 10 means 10% off
FLAT_AMOUNT → value is a fixed amount in the tenant's currency. e.g. 500 means ₦500 off
FREE_SHIPPING → value is ignored, set to ZERO by convention
BUY_X_GET_Y → value is ignored, use requiredQuantity + freeQuantity instead
-0
└─maximumDiscountCapnumberFor PERCENTAGE promotions — caps the maximum monetary discount that can be applied.
e.g. "20% off but no more than ₦2,000"
Null means no cap.
Only meaningful when discountType = PERCENTAGE.
-0
└─minimumOrderValuenumberMinimum order subtotal required to qualify for this promotion.
Null or ZERO means no minimum.
-0
└─requiredQuantityint32For BUY_X_GET_Y promotions — the number of items the customer must purchase.
Only meaningful when discountType = BUY_X_GET_Y.
-0
└─freeQuantityint32For BUY_X_GET_Y promotions — the number of free items the customer receives.
Only meaningful when discountType = BUY_X_GET_Y.
-0
└─usageLimitint32Maximum number of times this promotion can be redeemed across all customers.
Null means unlimited.
-0
└─usageCountint32How many times this promotion has been redeemed so far.-0
└─perCustomerUsageLimitint32Maximum number of times a single customer can redeem this promotion.
Null means unlimited per customer.
-0
└─discountnumberThe discount amount for the promotion-0
└─statusstringThe status of the promotion (e.g., active, expired, upcoming)-
└─tenantIdstringNo comments found.-

Response-example:

json
{
  "status": true,
  "message": "",
  "data": {
    "createdAt": "yyyy-MM-dd HH:mm:ss",
    "updatedAt": "yyyy-MM-dd HH:mm:ss",
    "id": "",
    "name": "",
    "code": "",
    "description": "",
    "startDate": "yyyy-MM-dd HH:mm:ss",
    "endDate": "yyyy-MM-dd HH:mm:ss",
    "discountType": "PERCENTAGE",
    "discountValue": 0,
    "maximumDiscountCap": 0,
    "minimumOrderValue": 0,
    "requiredQuantity": 0,
    "freeQuantity": 0,
    "usageLimit": 0,
    "usageCount": 0,
    "perCustomerUsageLimit": 0,
    "discount": 0,
    "status": "",
    "tenantId": ""
  }
}

Next Steps ​

Build with joy