Promo List

The Promo List endpoint provides active promotions (discounts and bonuses) applied to products, airtime, packages, and gifts.
Each promo includes start and end dates, which determine when the promo is valid.

Endpoint

> GET ${BASE_URL}/promos

Sample Request

Curl

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        "BASE_URL/promos"

Typescript

import * as axios from "axios";

axios
  .get("BASE_URL/promos", {
    headers: {
      "Content-Type": "application/json",
      "x-api-token": "ACCESS_TOKEN"
    },
  })
  .then((response) => {
    console.log("Success:", response.data);
  })
  .catch((error) => {
    console.error(
      "Error:",
      error.response ? error.response.data : error.message,
    );
  });

Response Schema

Success: 200

{
  success: boolean;
  message: string;
  statusCode: number;
  data: Array<{
     id : number,
     productCategoryId : number,
     createdAt : string,
     updatedAt : string,
     promoName : string,
     promoImage : string, 
     promoDescription : string,
     promoStartDate : string,
     promoEndDate : string,
     discountPercentage : number,
     bonusPercentage : number,
     status : ACTIVE | INACTIVE,
     constraint : number,
  }>;
  meta: {
    itemsPerPage: number;
    totalItems: number;
    currentPage: number;
    totalPages: number;
    sortBy: Array<Array<string>>;
    filter: {
    };
  };
  links: {
    current: string;
  };
};

Here is a detailed explanation of the data returned by promo list

• id (number): Unique identifier for the promo.
• productCategoryId (number): The product category the promo applies to.
• promoName (string): Display name of the promo.
• promoDescription (string): User-friendly explanation of the promo.
• promoStartDate (string, ISO 8601): Date and time when the promo takes effect.
• promoEndDate (string, ISO 8601): Date and time when the promo expires.
• discountPercentage (number): Discount percentage applied by the promo (can be 0).
• bonusPercentage (number): Bonus percentage applied by the promo (can be 0).
• constraint (number): Limit or condition associated with the promo (business-specific meaning).
• status - Explains whether the promo is currently ACTIVE or INACTIVE. The promos listed in this api are the ACTIVE ones only.
• status ("ACTIVE" | "INACTIVE"): Current status of the promo.

Note: This API only returns ACTIVE promos.

Error: 404

{
  statusCode: number;
  success: boolean;
  message: string;
  data: any;
}

Sample Response

{
    "success": true,
    "message": "Successful",
    "statusCode": 200,
    "data": [
        {
            "id": 4,
            "createdAt": "2025-09-09T12:46:35.244Z",
            "updatedAt": "2025-09-09T12:46:35.244Z",
            "promoName": "Holiday Promo",
            "promoDescription": "Promo For the upcoming Holiday.",
            "promoStartDate": "2025-09-02T21:00:00.000Z",
            "promoEndDate": "2025-09-17T21:00:00.000Z",
            "promoImage": "promos/images/abc.png" // This image is available at https://telesend.et/promos/image/abc.png
            "discountPercentage": 0,
            "bonusPercentage": 50,
            "constraint": 150,
            "status": "ACTIVE",
            "productCategoryId": 1
        },
    ],
    "meta": {
        "itemsPerPage": 20,
        "totalItems": 4,
        "currentPage": 1,
        "totalPages": 1,
        "sortBy": [
            [
                "id",
                "DESC"
            ]
        ]
    },
    "links": {
        "current": "https://tapi.telesend.et/api/v1/client/promos?page=1&limit=20&sortBy=id:DESC"
    }
}