Promotion Engine SDK

The promotion-engine SDK is a headless product designed to enable brands and presales to seamlessly create and manage campaigns. This SDK provides a set of APIs for both brands and presales, allowing them to work independently on our platform.

Installation

To install the promotion-engine SDK, use the following npm command:

npm install promotion-engine

Usage

Initialization

import PE from "promotion-engine";

// Initialize the SDK with your API key and hostname
const pe = new PE({ apiKey: "", baseUrl: "http://localhost:8080" });

Endpoints

Brand External API Management

1. Redeem Promo Code

Method: POST

Endpoint: /promo_code/redeem-promo-code

Description: Redeem Promo Code at Brands Platform end.

Request Object

| Parameters | Type | Description | | ---------------- | :----: | :----------------------------------------------------------------- | | promocode | string | The promo code to redeem. | | brand | string | Brand identifier. | | pre_sales_id | string | Presales ID. | | customer | object | Customer details. | | age | number | Customer's age. | | gender | string | Customer's gender. | | country | string | Customer's country. | | state | string | Customer's state. | | city | string | Customer's city. | | order | object | Order details. | | amount | number | Order amount. | | paymentMethod | string | Payment method. | | shippingCharge | number | Shipping charge. | | sku | array | Array of SKU details. | | sku | string | SKU identifier. | | price | number | Price per item. | | itemQuantity | number | Quantity of items. | | user_mobile | string | User's mobile number. | | user_email | string | User's email address. | | user_id | string | User ID. |

Example:

const redeemPromoCode = async () => {
  const { data, error } = await pe.redeemPromoCode({
    user_mobile: "xxxxxxxxxx",
    promocode: "christmas2023",
    // other parameters
  });

  console.log(data, error);
};

redeemPromoCode();

Response:

{
  "status": {
    "code": 200,
    "error": false
  },
  "message": "Promo Code is valid.",
  "result": {
    "discount": 200,
    "promoCodeValue": 1500,
    "message": "You got a cashback of 20% of your order.",
    "skuData": [
      {
        "sku": "SKU1",
        "price": 1000,
        "itemQuantity": 1
      }
    ],
    "usageId": "6bf21948-ec82-41ec-8aa7-942705db68be"
  }
}

NOTES:

• The usageId in the response represents a unique identifier for the redeemed promo code, and it can be used to place an order.

• The usageId is valid for 10 minutes. After this period, a new call to the "Redeem Promo Code" endpoint is required to obtain a new usageId for placing orders.

2. Place Order

Method: POST

Endpoint: /usage/{id}/place-order

Description: Place an order at Brands Platform end.

Request Object

| Parameters | Type | Description | | ------------------ | ------- | ------------------------------------------------------------ | | id | string | The ID associated with the order. | | user_mobile | string | User's mobile number. | | user_email | string | User's email address. | | order_id | string | Order ID. | | return_period | number | Return period in days. | | isRedeemed | boolean | Whether the order is redeemed or not. | | promocode_id | string | Promo code identifier. | | pre_sales_id | string | Presales ID. | | usage_time_stamp | string | Timestamp of usage. | | user_id | string | User ID. | | order_data | any | Order data (structure may vary). | | totalAmount | number | Total order amount. | | discountedAmount | number | Discounted amount. | | use_within | string | Timeframe within which the promo code can be used. | | isExpired | boolean | Whether the promo code is expired or not. | | discountValue | number | The discount value applied. | | commission | number | Commission amount. | | processing_fee | number | Processing fee amount. | | payout | string | Payout details. |

3. Return Order

Method: POST

Endpoint: /usage/return-order

Description: Return an order at Brands Platform end.

Request Object

| Property | Type | Description | | ----------- | ------ | --------------------------------------- | | order_id | string | Order ID to initiate the return process. |

4. Attach with User

Method: POST

Endpoint: /promo_code/attach-with-user

Description: Attach a Promo Code with a user.

Request Object

| Property | Type | Description | | ----------- | ------ | --------------------------------------- | | promocode | string | Promo Code to attach with the user. | | brand | string | Brand identifier (optional). | | user_mobile | string | User's mobile number. | | user_email | string | User's email address. |

Presales External API Management

1. List Affiliate Campaigns

Method: GET

Endpoint: /promotions/get-all-aff-dynamic/{id}

Description: Get all dynamic affiliate campaigns for a presale.

Parameters:

| Property | Type | Description | | -------- | ------ | ----------------------------------------------- | | id | string | Presale ID to retrieve affiliate campaigns for. |

Response:

{
  "status": {
    "code": 200,
    "error": false
  },
  "message": "Affiliate campaigns retrieved successfully.",
  "result": [
    {
      "promotionId": "unique_promotion_id_1",   // Promotion identifier
      "campaignId": "unique_campaign_id_1",     // Campaign identifier
      "campaignName": "Campaign 1",             // Campaign name
      "brandName": "Brand 1"                    // Brand name associated with the campaign
    },
    {
      "promotionId": "unique_promotion_id_2",
      "campaignId": "unique_campaign_id_2",
      "campaignName": "Campaign 2",
      "brandName": "Brand 2"
    }
    // ... Additional campaigns
  ]
}

2. Generate Promo Code

Method: POST

Endpoint: /promo_code/generate-promo-code

Description: Generate a dynamic promo code for presales at the Brands Platform end.

Request Object

| Parameters | Type | Description | | -------------- | ------ | --------------------------------------------- | | promotion_id | string | Promotion ID for which the promo code is generated. | | user_mobile | string | User's mobile number for associating with the generated promo code. | | user_email | string | User's email address (optional). |

NOTE:

• The promotion_id and user_mobile parameters are required for generating the promo code.

Response:

{
  "status": {
    "code": 200,
    "error": false
  },
  "message": "Promo Code is valid.",
  "result": {
    "promocodeDetails": {
      "id": "unique_promocode_id",
      "code": "YOUR_GENERATED_PROMO_CODE",
      "promotion_id": "your_promotion_id",
      "description": "Promocode Description",
      "type": "dynamic",
      "number_of_uses": 0,
      "minPurchaseAmount": 1000,
      "maxRedemptions": 1,
      "start_date": "2023-01-01T00:00:00.000Z",
      "end_date": "2023-01-01T00:00:00.000Z",
      "number_of_use_per_customer": 1,
      "is_exclusive": true,
      "is_custom_usage": false,
      "duration": "null",
      "interval": "null",
      "user_id": "user_id",
      "tnc": "Terms and Conditions",
      "redemptionProcess": "Redemption Process",
      "logo": "Logo",
      "creatives": "Creatives",
      "name": "Name"
    },
    "brandUrl": "https://www.example.com"
  }
}

3. Attach with User

Method: POST

Endpoint: /promo_code/attach-with-user

Description: Attach a Promo Code with a user.

Request Object

| Property | Type | Description | | ----------- | ------ | --------------------------------------- | | promocode | string | Promo Code to attach with the user. | | brand | string | Brand identifier (optional). | | user_mobile | string | User's mobile number. | | user_email | string | User's email address. |