Example using a custom coupon system

A wise proverb says

“TELL ME AND I’LL FORGET. SHOW ME AND I’LL REMEMBER. LET ME DO AND I’LL UNDERSTAND!”-CONFUCIUS

As we believe the best way to learn is by doing, in this section we will integrate a sample coupon system with Gameball to give you a taste of how real integration should look and how to smoothly integrate your coupon system with Gameball. Let's get our hands dirty!

If you already have your own APIs that create coupons, you did not need to re-create your code from scratch, just make sure your endpoint can be reached publicly and make sure to follow along to understand the integration process more.

1. First, we will define the coupon model and its attributes which will be created by Gameball.

enum ECouponType {
  Percentage = 1,
  FixedAmount = 2,
  FreeShipping = 3,
  FreeProduct = 4,
}

export class Coupon {
  public code: string;
  public playerId: string;
  public value: number;
  public usageLimit: number; // how many times the coupon can be used in general,(always 1)
  public expiresAfter: number;// number of days coupon will expires after
  public oncePerCustomer: boolean; // how many times the coupon can be used for one customer(always true)
  public entitledProductIds: string[];// Ids of products the coupon will be applied to in case of free product coupon
  public entitledCollectionIds: string[];// Ids of categories the coupon will be applied to.
  public copounType: ECouponType; //coupon types
  constructor(
    code: string,
    playerId: string,
    value: number,
    usageLimit: number,
    expiresAfter: number,
    oncePerCustomer: boolean,
    ProductIds: string[],
    categoriesIds: string[],
    couponType: ECouponType,
  ) {
    this.code = code;
    this.playerId = playerId;
    this.value = value;
    this.usageLimit = usageLimit;
    this.expiresAfter = expiresAfter;
    this.oncePerCustomer = oncePerCustomer;
    this.ProductIds = ProductIds;
    this.categoriesIds = categoriesIds;
    this.couponType = couponType;
  }
}

Make sure that your coupon model attributes matches the names of the variables you define in the payload request configuration

2. Now, lets add the endpoint responsible for creating the coupon, this is the endpoint Gameball backend will send the coupon creation request to.

// the endpoint responsible for creating new coupon
app.post('api/coupons', async (req: Request, res: Response) => {
  try {
    const { code, value, playerId, usageLimit, expiresAfter, oncePerCustomer, 
    ProductIds, categoriesIds, copounType } = req.body;
    const coupon = new Coupon (code, value, playerUniqueId, usageLimit, 
                                          expiresAfter, oncePerCustomer, 
                                          entitledProductIds, entitledCollectionIds, 
                                          copounType);
    res.status(200).send('Coupon created Sucessfully');
  } catch (err) {
    console.error(err);
    res.status(500).send('Server Error');
  }
});

This endpoint should expect a body that look like this :

{
  "code": "OFF25",
  "playerId": "12345",
  "value": 25,
  "usageLimit": 1,
  "expiresAfter": 10,
  "oncePerCustomer": true,
  "ProductIds": [],
  "categoriesIds": [],
  "couponType": 2
}

Your coupon creation endpoint must returns code 200 if your coupon is created successfully.

3. Based on the endpoint we created now, we should add the following configurations we mentioned previously

Name	Value
Coupon engine url	https://app-name.com/api/coupons
Method	POST
Headers	Method to authenticate this API, for example if you authenticate your request using apiKey, your headers will look like: {"apiKey":"1231afdqda"}
Payload	{ "playerUniqueId": "{{playerId}}", "entitledProductIds":"{{ProductIds}}", "entitledCollectionIds":"{{categoriesIds}}", "oncePerCustomer": "{{oncePerCustomer}}", "code": "{{code}}", "usageLimit": "{{usageLimit}}", "value": "{{value}}", "couponType": "{{couponType}}" }

In the payload json object, the key is always fixed, only values between {{}} are changed based on coupon class attribute names, for example if we changed name of value attribute in the coupon properties class to amount the json body should looks like this :

{
 "playerUniqueId": "{{playerId}}",
 "entitledProductIds":"{{ProductIds}}",
 "entitledCollectionIds":"{{categoriesIds}}",
 "oncePerCustomer": "{{oncePerCustomer}}",
 "code": "{{code}}",
 "usageLimit": "{{usageLimit}}",
 "value": "{{amount}}",
 "couponType": "{{couponType}}"
}

4. Define coupon type values. You may have noticed that there are four checkboxes at the end of the configurations page in the dashboard, each representing one of the coupon types supported by Gameball. You only need to check the coupon types that you want to support, and if your coupon system supports a type, you need to provide the corresponding value for it. For example, in the coupon system we have created, we support four coupon types that we have defined earlier inside the ECouponType enum, each type with its corresponding value. We will fill each coupon type with its value, as shown in the example below

4. Click on test connection to check if your configurations is correct or not.