Use Your Own Couponing Engine
Last updated
Last updated
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 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: 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 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.
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.
Integrate Your Coupon System First, you’ll configure Gameball to work with your existing coupon system. This involves setting up endpoint details, defining request parameters, and specifying payload structures in the Gameball dashboard. Once completed, Gameball will be able to automatically generate coupons in your system based on customers’ redeemed points or campaign rewards.
Customer Coupon Redemption and Usage After configuring your coupon system, this guide will show you how customers can redeem points to obtain these coupons. It will also cover the steps for customers to use these redeemed coupons during the checkout process, applying discounts or rewards based on the coupon configuration.
To start, access the coupon configuration section in the Gameball dashboard and provide the necessary details about your coupon endpoint.
This can be done through the Update Coupon Configuration API. This API to define your endpoint and specify how Gameball should send requests to create coupons.
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.
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.
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.
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.
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.
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.
After setting up your configurations:
Use Test Connection in the Gameball dashboard to ensure the integration is working or you can use the Get Coupon Configuration API to view or verify your existing configuration, – This API provides details on your current setup, helping ensure that Gameball correctly communicates with your couponing system.
Confirm that your coupon creation endpoint returns a 200 status for successful coupon creation.
Define a coupon model in your system that matches Gameball structure. This enables consistent data exchange between Gameball and your coupon system.
Create an endpoint in your system for Gameball to call when generating coupons.
Sample Payload:
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.
We are only interested in the create coupon endpoint, so we can safely ignore others endpoints related to coupon.
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.
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.
Based on this structure, you will add the configurations we mentioned previously.
Coupon creation endpoint https://example.com/wp-json/wc/v3/coupons
Method
POST
Request Headers
Payload
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 :
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 :
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.
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.
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
Customers can manually redeem points for a coupon. In this case, they need to specify a ruleId in the redemption request payload, which identifies the specific redemption rule (e.g., redeem points for a percentage discount, fixed amount, free shipping, etc.). The rule ID can be retrieved using the Get Redemption Configurations endpoint, allowing flexibility in how customers redeem coupons based on your program setup.
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
To enable customers to choose a redemption option, use the Get Redemption Configurations endpoint to fetch available redemption rules. Each rule specifies how many points are needed to redeem a specific type of coupon, whether it’s a percentage discount, fixed-rate discount, free shipping, or another custom offer.
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.
2. Redeem Points for Coupon
After selecting a redemption rule, customers can redeem points to receive a coupon. To do so, they will use the Redeem Points for Coupon API endpoint and specify the ruleId, ensuring the redemption aligns with the desired rule.
Example Payload: This payload redeems 100 points from the customer’s balance in exchange for a coupon based on the specified rule RULE123, which provides a 10% discount.
Example Response:The response includes the generated coupon code (SAVE10), which the customer can use in an order to receive a 10% discount.
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.
