Use Your Own Couponing Engine

With Gameball integration, you can issue coupons when customers redeem points or as part of reward campaigns. The integration sends requests from Gameball to your coupon system, following the configurations you set up in the Gameball dashboard. This setup allows Gameball to generate coupons directly in your system, whether it’s a custom-built coupon system or a third-party e-commerce CMS.

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 or when he wins a coupon as a reward of a campaign. 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 . 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: https://your-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 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.

Coupon Redemption Workflow

The integration workflow involves two primary actions:

Initiating Redeem Request: Triggered when a customer wants to redeem points for a coupon or receives a campaign-based coupon reward .
Coupon Generation: Gameball sends an HTTP request to your specified endpoint for creating coupons, based on your system configurations.

This integration guide will walk you through two main steps: setting up your coupon system integration and enabling customer redemption and usage of those coupons.

Integration Guide Structure

Setting Up Coupon Configuration in Gameball

To start, access the coupon configuration section in the Gameball dashboard and provide the necessary details about your coupon endpoint.

Attributes

url string Required The URL of your API endpoint where coupons are created. Gameball will send requests to this endpoint whenever a coupon needs to be generated.

method string Required The HTTP method used to send requests to the coupon creation endpoint. Common values are POST or PUT.

contentType string Required The content type of the request that your server is expecting the request to be sent in. Common content types are application/json for JSON payloads or application/x-www-form-urlencoded for form data.

authentication object Optional Contains the authentication details required to access the coupon API. This can be set to support different authentication types, such as Basic or Bearer token.

authentication object

type string Optional Specifies the authentication type used by your system, such as Basic (for username and password) or Token (for token-based authentication). This field is essential to indicate which authentication method to apply.

username string Optional The username used for Basic Authentication. This attribute is required only if type is set to Basic.

password string Optional The password associated with the username for Basic Authentication. This attribute is required only if type is set to Basic.

token string Optional The token used for Token-based authentication, typically required when type is set to Token or Bearer. This token allows secure access to the API without needing a username or password.

values array Optional

An array of additional authentication values, which can include any extra details your system might require for custom or complex authentication setups. Each entry in the array is typically a key-value pair.

Example:

[
  { "key": "client_id", "value": "12345" },
  { "key": "scope", "value": "read:coupons" }
]

queryParams array Optional List of query parameters used in the request. Those that will be appended to the URL endpoint. These are used to pass specific parameters required by your coupon system as part of the URL itself, often for identification, filtering, or configuration purposes. Each query parameter is defined by a key-value pair, allowing you to tailor requests based on requirements in your API.

queryParams object

type string Required The data type of the query parameter, such as string or integer. This indicates the format in which the parameter’s value should be provided.

key string Required The name of the query parameter as expected by your API.

Example: "campaignId", "customerId"

value string Required The specific value assigned to this query parameter. This value can be a fixed string, number, or dynamically set based on the request context.

Example: "123", "loyalty"

headers array Optional Custom headers required for the request, such as API keys or content-related headers. Headers allow you to include additional data that may be necessary for the coupon endpoint to process the request correctly.

headers object

type string Required The type of header (e.g., string, integer).

key string Required The header key.

value string Required The header value.

Example:

[
  {
    "Type": "header",
    "Key": "X-Client-Version",
    "Value": "1.0"
  }
]

In this example,TheX-Client-Version may specify the client version for API versioning or tracking.

payload object Optional This specifies the structure of the JSON body Gameball will send to your endpoint when creating a coupon. Since different systems may use varying parameter names and structures, you can customize this payload to align with your system's requirements.

payload object

You should define the JSON payload with placeholders that Gameball will replace with actual data when sending the request.

Example:

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

In this setup:

{{playerUniqueId}}: Placeholder for the customer's ID .
{{value}}: Placeholder for the coupon’s discount value.
{{code}}: Placeholder for the generated coupon code.

The attribute names inside curly brackets represents coupon attributes in Gameball, these names are fixed, these name are mapped to their respective attributes in your coupon system, for example, If a customer with id CUS_12345 redeems a coupon worth 50 EGP with the code 50EGPOFF, Gameball backend will replace the keys inside each curly brackets {{}} with actual values so the payload sent after replacing attribute values based each attribute name should looks like :

{
  "customerId": "CUS_12345",
  "amount": "50",
  "code": "50EGPOFF"
}

If you changed the name of 'customerId' attribute to id , then the payload configuration should updated and look like this

{
 "id": "{{playerUniqueId}}",
 "amount":"{{value}}"
 "code": "{{code}}",
}

This allows Gameball to dynamically generate and send requests based on your configurations.

couponMapping object Optional A configuration object that specifies which types of coupons your system supports and maps them to corresponding internal settings. Each attribute within this object enables a specific coupon type, and you can toggle each one depending on what your system allows. Set each attribute to true or false based on the supported discount types.

couponMapping object

enableFreeProduct boolean Optional Indicates whether free product coupons are enabled in your system.

enableFixedRate boolean Optional Indicates whether fixed-rate discount coupons are enabled in your system.

enableFreeShipping boolean Optional Indicates whether free shipping coupons are enabled in your system.

enablePercentage boolean Optional Indicates whether percentage-based discount coupons are enabled in your system.

platforms array Optional A list of platforms (e.g., web, mobile, POS) where the coupon configurations apply within your system. This helps specify where the generated coupons can be used.

platforms object

displayName string Required The user-friendly name of the platform where the coupon configuration will be applied. This is the name shown in interfaces or documentation to help users identify the platform.

Example: "Web", "Mobile App", or "Point of Sale"

value string Required The internal identifier for the platform used within your system. This value must match what is stored in the platform object for correct identification and mapping in the coupon configuration.

Example: "web", "mobile_app", or "pos"

Testing and Validating Configuration

After setting up your configurations:

Confirm that your coupon creation endpoint returns a 200 status for successful coupon creation.

Example Coupon Model

Define a coupon model in your system that matches Gameball structure. This enables consistent data exchange between Gameball and your coupon system.

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

class Coupon {
  public code: string;
  public customerId: string;
  public value: number;
  public usageLimit: number;
  public expiresAfter: number;
  public oncePerCustomer: boolean;
  public entitledProductIds: string[];
  public entitledCollectionIds: string[];
  public couponType: ECouponType;
}

Coupon Creation Endpoint

Create an endpoint in your system for Gameball to call when generating coupons.

app.post('/api/coupons', async (req, res) => {
  try {
    const { code, value, customerId, usageLimit, expiresAfter, oncePerCustomer, entitledProductIds, entitledCollectionIds, couponType } = req.body;
    const coupon = new Coupon(code, customerId, value, usageLimit, expiresAfter, oncePerCustomer, entitledProductIds, entitledCollectionIds, couponType);
    res.status(200).send('Coupon created successfully');
  } catch (err) {
    console.error(err);
    res.status(500).send('Server Error');
  }
});

Sample Payload:

{
  "code": "OFF25",
  "customerId": "12345",
  "value": 25,
  "usageLimit": 1,
  "expiresAfter": 10,
  "oncePerCustomer": true,
  "entitledProductIds": [],
  "entitledCollectionIds": [],
  "couponType": 2
}

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.

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.

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.

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

Once your coupon system is fully configured within Gameball, you’re all set to allow customers to start redeeming points for coupons and using these coupons as rewards. With the integration in place, Gameball will seamlessly communicate with your couponing system to generate coupons based on customer redemptions and campaign rewards.

Coupon Redemption Guide

Once a coupon is redeemed or awarded to a customer, it can be applied to an order, allowing the customer to enjoy discounts or offers based on the coupon configurations.

Overview of Coupon Redemption Scenarios

Coupon as a Campaign Reward Gameball allows you to configure campaigns on the dashboard where customers can win coupons as rewards. When a customer completes the criteria for a campaign, Gameball automatically issues a coupon to the customer’s account. The customer can then use this coupon code for a discount or offer.

Manual Coupon Redemption

If a customer opts to redeem a coupon using their points, follow the steps below to ensure a smooth redemption process:

1. Retrieve Redemption Rules

Example Description: Use this step to display options to customers. For instance, if you have two redemption rules in place , This response shows that customers can redeem a 10% discount for 100 points or a $20 discount for 200 points as one option.

{
  "redemptionFactor": 0.1,
  "redemptionRules": [
    {
      "id": 2138,
      "pointsToRedeem": 100,
      "valueOfPoint": 0.1,
      "ruleType": "fixed_rate_settings",
      "startDate": "2024-10-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z",
      "coupon": {
        "couponType": "fixed_rate_discount",
        "discountValue": 10.0,
        "minOrderValue": 50.0,
      }
    },
    {
      "id": 2139,
      "pointsToRedeem": 100,
      "valueOfPoint": 0.1,
      "ruleType": "free_shipping_settings",
      "startDate": "2024-10-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z",
      "coupon": {
        "couponType": "free_shipping",
        "minOrderValue": 50.0
      },
    }
  ]
}

2. Redeem Points for Coupon

Example Payload: This payload redeems points from the customer’s balance in exchange for a coupon based on the specified rule with id 2138, which provides a 10% discount.
```
{
  "customerId": "customer_12345",
  "ruleId": 2138,
  "transactionId": "txn_7890",
  "transactionTime": "2024-10-15T09:30:00.000Z"
}
```

Example Response:The response includes the generated coupon code (SAVE10), which the customer can use in an order to receive a 10% discount.

{
  "customerId": "customer_12345",
  "gameballTransactionId": "12345678",
  "transactionId": "txn_7890",
  "couponCode": "SAVE10",
  "redeemEquivalentPoints": 100,
  "expiryDate": "2025-01-15T23:59:59.000Z"
}

Applying a Redeemed Coupon to an Order

Once a coupon has been redeemed, whether automatically through a campaign or manually via points redemption, the customer can apply it to an order to avail the associated discount or offer. Here’s how to apply the coupon during the order process:

Apply Coupon to an Order To use a redeemed coupon, the customer includes the coupon code in the order request, allowing the system to apply the associated discount. Use the Order endpoint for this purpose.
- Example Payload: In this payload, the couponCode (SAVE10) is applied to an order, reducing the totalPaid amount from $150 to $135, reflecting a 10% discount.
  { "customerId": "customer_12345", "orderId": "ORD123456", "orderDate": "2024-10-15T10:00:00.000Z", "totalPrice": 150.00, "totalPaid": 135.00, "coupons": { "couponCodes": [ "SAVE10" ] }, }

PreviousCoupons Redemption NextGameball Couponing Engine

Last updated 1 month ago