Reward Configurations
Retrieve essential reward settings like cashback, redemption, and coupon configurations. These APIs help display details about how customers can earn and redeem rewards within your program.
Available APIs
GET - Cashback Configurations
https://api.gameball.co/api/v4/integrations/configurations/cashback
This API call retrieves your cashback configurations, providing essential details about how cashback rewards are structured and managed in Gameball. If the customerId
is provided, the API will return any special cashback rules associated with the customer’s tier, including potential bonuses or customized reward factors specific to that customer.
Security: Requires apiKey header
Request
Query Parameters
customerId string
Optional
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be database ID, random string, email or anything that uniquely identifies the customer.
If provided, the response will return the cashback rules specific to this customer’s tier, reflecting any special configurations or bonuses this customer is eligible for based on their tier cashback rules.
Response
application/json
defaultCashbackRule Object
The default cashback rule applied to all customers if no tier-specific rules are available.
tierCashbackRules array
A list of tier-specific cashback rules, which override the default cashback rule for customers in a specific tier.
Sample Response
{
"defaultCashbackRule": {
"rewardFactor": 10.0,
"amountRewardThreshold": 1.0,
"rewardWalletFactor": 1.0,
"rewardRankFactor": 1.0
},
"tierCashbackRules": [
{
"tierName": "Gold",
"rewardFactor": 0.0,
"amountRewardThreshold": 1.0,
"rewardWalletFactor": 20.0,
"rewardRankFactor": 1.0
}
]
}
GET - Redemption Configurations
https://api.gameball.co/api/v4/integrations/configurations/redemption
This API retrieves the configurations and rules associated with how customers can redeem points for discounts, coupons, or other rewards.
Security: Requires apikey and secretkey headers.
Request
Query Parameters
customerId string
Optional
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.
If provided, the API will return redemption configurations that match the customer based on various criteria, such as RFM , tiers, segments and specific customer attributes. This approach ensures that the redemption options are personalized and relevant to each customer's unique profile and engagement history.
Response
application/json
redemptionFactor number
This factor indicates the value of each loyalty point in terms of currency, defining how many currency units can be obtained by redeeming points.
Example: If the redemptionFactor
is set to 0.1,this means that a customer can redeem 10 points for 1 USD.
redemptionRules array
A list of redemption rules that define how points can be redeemed for discounts and coupons.
Defines the rules for redeeming points, including points required, value of points, applicable coupons, and eligibility criteria.
Example: a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts.
Sample Response
{
"redemptionFactor": 0.1,
"redemptionRules": [
{
"id": 2138,
"pointsToRedeem": 100,
"valueOfPoint": 25.0,
"ruleType": "percentage_discount_settings",
"coupon": {
"couponType": "percentage_discount",
"discountValue": 25.0,
"product": null,
"collections": [
{
"collectionId": "455218036961",
"collectionName": "Automated Collection"
}
],
"options": {
"name": "Redemption Rule Name",
"expiryAfter": 14,
"usageLimit": 2,
"capping": 50,
"minOrderValue": 150.0,
"combinesWith": {
"orderDiscounts": true,
"productDiscounts": true,
"shippingDiscounts": true
},
"codePrefix": "SUMMER",
"platforms": [],
"redeemInstructions": "Enter the coupon code at checkout to apply the discount."
}
},
"image": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads%2fClient_2933%2f936f65d8-e06d-4e28-b423-b5282999801bgameball.webp",
"creationDate": "2025-02-10T10:12:16.783408",
"isActive": true
]
}
GET - Coupon Configurations
https://api.gameball.co/api/v4/integrations/configurations/coupon
This API call retrieves your coupon configurations, including details about how coupons are structured, authenticated, and mapped within Gameball.
Security: Requires apikey and secretkey headers.
Response
application/json
url string
The URL where the coupon configuration is applied.
method string
The HTTP method used for the coupon configuration process (e.g., POST, PUT or GET).
queryParams array
List of query parameters used in the request.
headers array
List of headers used in the request.
payload string
The request payload format or template.
couponMapping object
A dictionary mapping coupon types to specific keys in your system.
enableFreeProduct boolean
Indicates whether free product coupons are enabled.
enableFixedRate boolean
Indicates whether fixed-rate discount coupons are enabled.
enableFreeShipping boolean
Indicates whether free shipping coupons are enabled.
enablePercentage boolean
Indicates whether percentage-based discount coupons are enabled.
platforms array
List of platforms for which the coupon configurations are applied.
Sample Response
{
"url": "https://api.mywebsite.com/coupons",
"method": "POST",
"queryParams": [
{
"key": "appId",
"value": "12345"
}
],
"headers": [
{
"key": "Authorization",
"value": "Bearer token"
}
],
"payload": "{ \"couponCode\": \"DISCOUNT10\" }",
"couponMapping": {
"fixed": "fixed_discount",
"percentage": "percentage_discount",
"freeProduct": "free_product",
"freeShipping": "free_delivery"
},
"enableFreeProduct": true,
"enableFixedRate": true,
"enableFreeShipping": true,
"enablePercentage": true
}
PUT - Update Coupon Configurations
https://api.gameball.co/api/v4/integrations/configurations/coupon
This API call updates your coupon configurations, allowing you to modify details about how coupons are structured, authenticated, and mapped within Gameball.
Security: Requires apikey and secretkey headers.
Request
Body
application/json
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. Allowed values are POST
, PUT
or GET
.
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
List of headers used in the request.
payload string
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.
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 dictionary mapping coupon attributes to specific keys in your system.
enableFreeProduct boolean
Indicates whether free product coupons are enabled.
enableFixedRate boolean
Indicates whether fixed-rate discount coupons are enabled.
enableFreeShipping boolean
Indicates whether free shipping coupons are enabled.
enablePercentage boolean
Indicates whether percentage-based discount coupons are enabled.
platforms array
Optional
List of platforms for which the coupon configurations are applied in your system.
Sample Request
{
"url": "https://api.mywebsite.com/coupons",
"method": "POST",
"queryParams": [
{
"key": "appId",
"value": "12345"
}
],
"headers": [
{
"key": "Authorization",
"value": "Bearer token"
}
],
"payload": "{ \"couponCode\": \"DISCOUNT10\" }",
"couponMapping": {
"fixed": "fixed_discount",
"percentage": "percentage_discount",
"freeProduct": "free_product",
"freeShipping": "free_delivery"
},
"enableFreeProduct": true,
"enableFixedRate": true,
"enableFreeShipping": true,
"enablePercentage": true
}
Last updated