Integrate Your Own Couponing Engine

If you already have an API or system that create coupons for your customer, we need to know information(configurations) about this endpoint, so Gameball can create coupon at your endpoint, for example an e-commerce CMS like WooCommerce has an endpoint for creating coupons and we show example of integrating it with Gameball.

Let's explain how the integration with your coupon system works on a bit lower tier.

The Initiate Redeem Request is triggered by your customer when he simply tries to create a new coupon in exchange of redeeming his points. This request is sent to Gameball Backend, which builds an HTTP request and send it to your coupon system endpoint. The HTTP request query parameters and payload, etc.. is defined by you in your coupon configurations section in dashboard. For example, the destination where the request will be sent to is the endpoint responsible for creating coupon(s) in your coupon system i.e: /app-api/coupon/create. In a nutshell, Gameball want to send request to your endpoint that creates coupon for your customers, let it be custom one created by your team or through e-commerce coupon system like Woocommerce example.

If you already have an API or system that create coupons for your customer, we need to know information(configurations) about this endpoint, so Gameball can create coupon at your endpoint.

Start the integration, you must define the following configurations in your dashboard:

The table below contains information about main configurations needed to integrate with Gameball.

Main Configuration attributes

Name	Required	Description
Coupon system url	Yes	Your coupon system endpoint responsible for creating coupons.
Method	Yes	Http Method type, i.e: POST, GET, PUT. (usually it is a POST method)
Authentication	Yes	API authentication, i.e: basic auth, no authentication, etc..
Query parameters	No	List of key value pairs of query params. Can contain API keys or other data
Headers	No	Request headers can contain values like API key, bearer token, etc..
Payload	Yes	Request body that contains the coupon details, i.e: coupon code, expiry date.

Payload attributes

Name	Type	Description
playerUniqueId	String	Customer unique id at your system that was used to create the customer at Gameball
entitledProductIds	Array of string	Array of product id (at your system) in which this voucher can be applied for, this should contain id's of product in case of free product voucher.
entitledCollectionIds	Array of string	Array of Categories Ids (At your system) that the generated coupon can be applied to.
oncePerCustomer	boolean	How many times the coupon can be used per customer, it is always sent by true since it is supported only to use one coupon once per customer.
code	String	The coupon code.
usageLimit	int	How many times the coupon can be used in total, for now it is always set to 1 because coupon can be only used once.
value	double	The value of discount.
couponType	object	Type of coupon, currently Gameball supports the following coupons only : fixed amount voucher percentage voucher free shipping free product
expiresAfter	int	Amount in days that the coupon will be expired after
minOrderValue	int	The minimum order value that the coupon can work with.
source	string	Defines which Gameball module created this coupon. Possible Values: Referral Reward - Customer Referral Reward - Friend Rewards Campaign Reward- Place Order 3 Times VIP Tier - Gold - Life time VIP Tier - Gold - Entry Reward Points Redemption Automation Flow

---

Understanding the Payload Configuration

The payload refers to the structure of the JSON body of the HTTP request that will be sent to the endpoint responsible for creating coupons in your coupon system. Since different coupon systems can have varying payload structures and parameter names, it’s important to customize this according to your requirements.

Each client can define their own payload using variables that Gameball will replace during the request creation. For example, if your coupon system API requires the following attributes in the body of the create coupon request:

• code (required)

• amount (required)

• customerEmail (optional)

Your payload configuration should appear as follows:

{
  "customerEmail": "{{customerId}}",
  "amount": "{{value}}",
  "code": "{{code}}"
}

In this configuration, the attribute names within curly brackets represent coupon attributes in Gameball. These names are fixed and mapped to their respective attributes in your coupon system.

For instance, if a customer in your system with the email [e-mail] wants to redeem a coupon valued at 50 EGP with the code 50EGP0FF, the backend will replace the keys in curly brackets with actual values, resulting in the following payload:

{
  "customerEmail": "[e-mail]",
  "amount": "50",
  "code": "50EGP0FF"
}

If you decide to change the name of the customerEmail attribute to email, the updated payload configuration will look like this:

{
  "email": "{{customerId}}",
  "amount": "{{value}}",
  "code": "{{code}}"
}

Optional Payload Attributes

Payload attributes are generally optional. You should send attributes based on your specific preferences or according to the integration requirements of the e-commerce CMS coupon system. For example, when integrating with WooCommerce, you’ll find that the code attribute is required, so the minimum payload must include:

{
  "code": "{{code}}"
}

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.

---

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.

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.

• 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

• 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.

• 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	{ "customerId": "{{customerId}}", "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 :

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

• 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

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

---

Example using e-commerce platform(WooCommerce)

Please note that the same steps can be applied to different platforms with a slight changes based on your platform, we are only using WooCommerce for the sake of this example.

In this guide, we will show you how to integrate a platform's existing coupon system with Gameball backend, we will give example of integrating Gameball with WooCommerce coupon system.

Integrating With WooCommerce coupon API

We are only interested in the create coupon endpoint, so we can safely ignore others endpoints related to coupon.

1. Search on google or in your platform documentation for the API responsible for creating coupons or coupon system API or similar keywords, you will find it here.

2. Fill in the configurations based on the coupon HTTP request structure in your create coupon endpoint, for example WooCommerce will expect Gameball Backend to send an HTTP request with the following JSON body when creating a new coupon.

POST /wp-json/wc/v3/coupons HTTP/1.1
Content-Type: application/json
Authorization: Basic API_KEY:API_SECRET

{
  "code": "MYCOUPON",
  "amount": 10,
  "discount_type": "percent",
  "usage_limit": 100,
  "expiry_date": "2023-12-31"
  "product_ids" :"[]",
  "product_categories" : "[]",
}

Based on this structure, you will add the configurations we mentioned previously

Name	Value
coupon creation endpoint	https://example.com/wp-json/wc/v3/coupons
Method	POST
Request Headers	{ Authorization : OAuth oauth_consumer_key="ck_c9943d372c50",oauth_signature_method="HMAC-SHA1",oauth_timestamp="",oauth_nonce="ESXiR5boeRS",oauth_version="1.0",oauth_signature="ws%2F6UwgNor56Huc4ULYTVp51bIQ%3D" }
Payload	{ "customerId": "{{email_restrictions}}", "entitledProductIds":"{{product_ids}}", "entitledCollectionIds":"{{product_categories}}", "oncePerCustomer": "{{usage_limit_per_user}}", "code": "{{code}}", "usageLimit": "{{usage_limit}}", "value": "{{amount}}", "couponType": "{{discount_type}}" }

In the payload json object, the key is always fixed, only values between {{}} are changed based on coupon property names in the request body, for example if WooCommerce changed name of discount_type attribute in the coupon properties table to coupon_type the json body should looks like this :

{
 "customerId": "{{email_restrictions}}",
 "entitledProductIds":"{{product_ids}}",
 "entitledCollectionIds":"{{product_categories}}",
 "oncePerCustomer": "{{usage_limit_per_user}}",
 "code": "{{code}}",
 "usageLimit": "{{usage_limit}}",
 "value": "{{amount}}",
 "couponType": "{{coupon_type}}"
}

You need to pass the required attributes only, in WooCommerce coupon API, the coupon code attribute is the only required attribute, so the following payload is also valid :

{
"code":"{{code}}"
}

You can pass other attributes based on your preferences, for example, couponType attribute is not required in case you want to create the default type.

The coupon creation endpoint must return 200 code in order for coupon to be created successfully.

• Define coupon type values. You may have noticed there are four checkboxes at the end of the configurations page in dashboard, each checkbox represents one of the coupon types supported by Gameball, you need to check if WooCommerce support it or not and if it support it you need to provide value for it based on its corresponding type in WooCommerce coupon API, for example, there are three discount types in WooCommerce percent, fixed_cart and fixed_product. So, we will check fixed rate, percentage and free product coupons in dashboard and insert the corresponding value for each coupon type in WooCommerce, i.e: percentage coupon value will be percent.

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

Now you are all set to start creating coupons for your customers !