Comment on page

Configurations 👑

The Configurations Endpoints can be used to retrieve client different configurations.

Available Endpoints
Type
Description
Endpoint
GET
​Configurations​
/integrations/config
GET
​Redemption Rules​
/integrations/client/redemption/config
GET
​Challenge Configurations​
/integrations/config/challenge/{handle}
GET
​Cashback Rules​
/integrations/client/cashback
GET - Configurations
https://api.gameball.co/api/v3.0/integrations/config
This API call is used to retrieve your configured Gameball Settings along with all Gameball Programs Configurations. This endpoint allows you to retrieve your configured settings on Gameball account which can be used while creating your custom UI for the player profile on your website or mobile app.
It is very important to use this endpoint while building your own UI to keep all configurations related to Gameball are variable. No need to update your loyalty program static content inside your website or mobile app every time you change them through Gameball admin dashboard.
This endpoint is only available for our GURU customers only 👑
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
lang
string
No
Language filter. This could be used to specify the language needed to display your configurations in. If not provided, the response would be in default language.
Note: The language provided should be as per configured languages in your account.
Example: "en", "fr".
Response
Parameter
Type
Description
currency
string
Configured Currency
Example: "USD", "EUR".
programName
string
Name of your program.
Example: "TRIPLE H Store"
rankPointsName
string
Name of the rank points, measuring player's progress.
walletPointsName
string
Name of the points (monetary value).
botMainColor
string
The main color of your bot as configured from your Gameball dashboard.
controlConfig
object
An object describing the activity of the main factors.
levels
array
An array of level objects describing each level along with its configurations
challenges
array
An array of challenge objects describing each level along with its configurations
referral
object
An object describing the referral program configurations.
cashback
object
An object describing the cashback program configurations
redemption
object
An object describing the redemption configurations
The redemption object is described as follows
redemptionFactor: Indicates the monetary value which one point is equivalent to. 
Example: Redemption Value of 1 point is 0.01 (redemption factor).
redemptionRules: Array of Redemption Rule objects​
controlConfig Object
Parameter
Type
Description
gameballEnabled
boolean
Indicates whether Gameball is enabled or not.
redemptionEnabled
boolean
Indicates whether redemption configurations is enabled or not.
cashbackEnabled
boolean
Indicates whether cashback program is enabled or not.
referralEnabled
boolean
Indicates whether referral program is enabled or not.
visitorProfileEnabled
boolean
Indicates whether guest view is enabled or not.
userProfileEnabled
boolean
Indicates whether user view is enabled or not.
leaderboardEnabled
boolean
Indicates whether Leaderboard configurations are enabled or not.
notificationsEnabled
boolean
Indicates whether Notifications configurations are enabled or not.
achievementsEnabled
boolean
Indicates whether Achievements configurations are enabled or not.
level Object
Parameter
Type
Description
minProgress
integer
The required score to reach the level.
order
integer
Level Order
icon
string
icon URL of the level.
name
string
Level Name
benefits
object
"benefits":{ 
     "rankReward":0,
     "walletReward":0, 
     "levelDiscount":0,
     "discountCapping":0,
     "others":[]
}
The benefits object is defined as follows:
rankReward: Score rewarded upon reaching that level.
walletReward : Points rewarded upon reaching that level.
levelDiscount: The discount amount that the level grants.
discountCapping: The maximum value to which the discount is applicable.
Example: 10% discount for maximum order price 100 USD
others: An array of statement(s) that can be used to describe the benefits of the level. 
challenge Object
Parameter
Type
Description
id
integer
Unique identifier for the challenge.
name
string
Challenge Name
description
string
Challenge Description
rankReward
integer
Awarded rank upon challenge completion
walletReward
integer
Awarded points upon challenge completion
repeatable
boolean
A flag that indicates whether the challenge is repeatable or not.
maxAchievement
integer
An integer that defines how many times a player can achieve that challenge.
type
string
The type of the challenge. Possible values are as follows:
SignUp
SocialMedia
ScheduledChallenge
EventBased
HighScore
Birthday
Anniversary
visibility
string
Defines the visibility of the challenge. Possible values are:
"AlwaysVisibile"
"NotVisible"
"VisibleIfEarned"
icon
string
The icon's URL of the challenge.
availability
object
"availability":{
   "minLevel": 4,
   "tags": ["VIP"]
}
An object that describes challenge availability to players.
minLevel :  Minimum required level for the player to be eligible to the achieve the challenge.
tags:  Array of tags for which the challenge is available.
redirectionButtonText
string
Defines the text written on the redirection button (In case the redirection button is enabled for this challenge).
redirectionButtonLink
string
Defines the redirection link (In case the redirection button is enabled for this challenge).
referral Object
Parameter
Type
Description
referralMethod
string
Defines how the referral program rewards your players, Possible values:
"PlayerAndFriend"  denotes that both the referring and the referred player should be rewarded. The referred player also should complete the sign up process and perform a certain action according to your configurations.
"PlayerOnly" denotes that only the referring player that should be rewarded after a successful referral.
"PlayerAndGuest" denotes that both the referring and the referred player should be rewarded. Referred Player Registration is optional, but he would be rewarded after placing a successful order.
eventName
string
The name of the event which is linked to the referral action
eventMetaData
string
The event metadata which value should be monitored and checked for completing the referral.
playerReward
object
"playerReward":{
     "extraReward":{
         "rewardEvery":5,
         "rewardType":null,
         "score":2,
         "point":1,
         "voucher":null
       },
       "rewardType":"Vouchers",
       "score":0,
       "point":0,
       "voucher":{
          "voucherType":"Free Shipping",
          "productId":"",
          "productName":"",
          "value":0
       }
     }
An object that defines the referring player's reward.
The playerReward object is defined as follows:
extraReward: An object that defines the extra reward the referring player is granted after completing specific number of referrals.
"extraReward":{
    "rewardEvery":5,
    "rewardType":null,
    "score":2,
    "point":1,
    "voucher":null
}
rewardEvery:Defines the frequency upon which the referring player is rewarded
rewardType :  Defines the type of the reward, possible values are: 
"Vouchers"
"Score&Points"
score: Score rewarded as an extra reward.
points: Points rewarded as an extra reward.
voucher: An object that defines the rewarded voucher.
      "voucher":
    {
         "voucherType":"Free Product",
         "productId":"6161866621123",
         "productName":"Antique Drawers",
         "value":250
       }
rewardEvery:Defines the frequency upon which the referring player is rewarded
rewardType :  Defines the type of the reward, possible values are: 
"Vouchers"
"Score&Points"
score: Score rewarded as an extra reward.
points: Points rewarded as an extra reward.
voucher:  An object that defines the rewarded voucher.
friendReward
object
Defines the referred player reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred player should also be rewarded.
The object is the same as the playerReward object excluding the extraReward.
cashback Object
Parameter
Type
Description
rewardFactor
number
In case you have different merchants (brands) on your platform, The rewardFactor defines the specific cashback percentage for the paid amount to be rewarded to your players.
Example: If you give 5% cashback (when the customer pays 100 USD, they will get 5 USD cashback). The rewardFactor would be 0.05
amountRewardThreshold
integer
Defines the amount of unit currencies needed to reward the player as per cashback rules.
Example:  For every 10 USD spent the player gets rewarded by 5 points, implies that the amountRewardThreshold is "10".
rewardWalletFactor
integer
Determines the points rewarded for each unit currency your player spends.
Example: 2 points for every 1 USD spent, implies that the rewardWalletFactor is "2"
rewardRankFactor
integer
In case your level up method is score,  this factor determines the score rewarded for each unit currency your player spends.
Example: 2 Score for every 1 USD spent, implies that the rewardRankFactor is "2"
Sample Response
{
   "currency":"EGP",
   "programName":"my program",
   "rankPointsName":"Score",
   "walletPointsName":"Points",
   "botMainColor":"#e7e23f",
   "controlConfig":{
      "gameballEnabled":true,
      "redemptionEnabled":true,
      "cashbackEnabled":true,
      "referralEnabled":true,
      "visitorProfileEnabled":true,
      "userProfileEnabled":true,
      "leaderboardEnabled":false,
      "notificationsEnabled":true,
      "achievementsEnabled":true
   },
   "levels":[
      {
         "minProgress":0,
         "order":1,
         "icon":"https://cdn.gameball.co/uploads/Client 1/[email protected]",
         "name":"Basic",
         "benefits":{
            "rankReward":0,
            "walletReward":0,
            "levelDiscount":0,
            "discountCapping":0,
            "others":[
               "benefits1",
               "benefits2"
            ]
         }
      }
   ],
   "challenges":[
      {
         "id":3350,
         "name":"view product + tag internal",
         "description":"",
         "rankReward":3,
         "walletReward":10,
         "repeatable":true,
         "maxAchievement":0,
         "type":"EventBased",
         "visibility":"AlwaysVisible",
         "icon":"gb-icon-challenge-10@2x",
         "availability":{
            "minLevel":5,
            "tags":[
               "2nd tag"
            ]
         },
        "redirectionButtonText": "Free Gift",
         "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
      }
   ],
   "referral":{
      "referralMethod":"PlayerAndFriend",
      "eventName":"",
      "eventMetaData":null,
      "playerReward":{
         "extraReward":{
            "rewardEvery":5,
            "rewardType":null,
            "score":2,
            "point":1,
            "voucher":null
         },
         "rewardType":"Vouchers",
         "score":0,
         "point":0,
         "voucher":{
            "voucherType":"Free Shipping",
            "productId":"",
            "productName":"",
            "value":0
         }
      },
      "friendReward":{
         "rewardType":"Vouchers",
         "score":0,
         "point":0,
         "voucher":{
            "voucherType":"Free Product",
            "productId":"6161866621123",
            "productName":"Antique Drawers",
            "value":250
         }
      }
   },
   "cashback":{
      "rewardFactor":0.3,
      "amountRewardThreshold":10,
      "rewardWalletFactor":3,
      "rewardRankFactor":1
   },
   "redemption":{
      "redemptionFactor":0.01,
      "redemptionRules":[
         {
            "ruleId":1097,
            "type":"Level",
            "equivalentPoints":0,
            "equivalentPointsValue":0,
            "productId":"",
            "productName":""
         },
         {
            "ruleId":1156,
            "type":"FreeProduct",
            "equivalentPoints":100,
            "equivalentPointsValue":50,
            "productId":"6161869406403",
            "productName":"Striped Skirt and Top"
         }
      ]
   }
}
Usage Example
cURL
Ruby
PHP
Python
.NET
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d 
 -v -i 'https://api.gameball.co/api/v3.0/integrations/config'
# Example 1
Gameball::Configurations.get_configurations()
​
# Example 2
Gameball::Configurations.get_configurations({lang: "en"})
$response = $gameball->config->getConfigurations();
configurations = gameball.get_configurations()
var response = Gameball.GetConfigurations();
GET - Challenge Configurations
This API is used to get the configurations of a specific challenge. ​
https://api.gameball.co/api/v3.0/integrations/config/challenge/{handle}
​
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
Attribute
Type
Required
Description
handle
string
Yes
Challenge handle could be either the Challenge Id or the Challenge internal name.
Response
Attribute
Type
Description
challengesConfig
object
A single object array of ChallengeConfig object
challengesConfig object
Attribute
Type
Description
id
integer
A single object array of ChallengeConfig object
name
string
​
description
string
Challenge description( In default language if not specified in query parameter)
rewards
array
An array of Reward objects, these are the rewards that are achieved by completing the specified challenge
isRepeatable
boolean
A boolean indicating if the challenge is repeatable for the specified Player or not
maxAchievement
integer
Maximum number of times the specified challenge can be achieved (-1 if can be achieved for an unlimited number of times)
type
string
Challenge type, can be one of the following:
Amount Based
Action Based
Amount & Action Based
High Score
Upon Login
NonCumulative Amount Based
Join Anniversary
Event Based
Social Activities
Scheduled Challenge
Streak
visibility
string
Challenge visibility type, can be one of the following: 
Always Visible
Not Visible
Visible If Earned
icon
string
URI indicating the file path to the icon of the challenge
availability
object
An availability object specifying the conditions where this challenge is available
redirectionButtonText
string
Defines the text written on the redirection button (In case the redirection button is enabled for this challenge).
redirectionButtonLink
string
Defines the redirection link (In case the redirection button is enabled for this challenge).
Sample Response
{
    "challenges": [
        {
            "id": 6128,
            "name": "IsRepeatable test",
            "description": "DescNew",
            "rewards": [
                {
                    "rankReward": 0,
                    "walletReward": 0,
                    "couponReward": {
                        "couponType": "Free Product",
                        "discountValue": null,
                        "minOrderValue": null,
                        "product": {
                            "productId": "7803615346931",
                            "productName": "Chequered Red Shirt",
                            "variantId": "43168747192563",
                            "variantName": null
                        },
                        "collections": []
                    }
                }
            ],
            "isRepeatable": false,
            "maxAchievement": 1,
            "type": "EventBased",
            "visibility": "Always Visible",
            "icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
            "availability": {
                "minLevel": 3,
                "tags": [
                    "active",
                    "inactive"
                ]
            },
            "redirectionButtonText": "Free Gift",
            "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
        }
    ]
}
GET - Redemption Rules
https://api.gameball.co/api/v3.0/integrations/client/redemption/config
This API endpoint is used to return all client’s redemption rules.
Request
Header
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
lang
string
No
Preferred language code. (e.g. "en", "es")
Response
Parameter
Type
Description
isRedemptionActive
boolean
A Boolean flag indicating if the redemption program is active for the client
​
​
​
pointsExpiryPeriod
int
Number of days that the points will expire after being rewarded
redemptionRules
array
An array of redemptionRule objects of the client.
redemptionRule object
Parameter
Type
Description
id
integer
Unique Identifier of the redemption rule.
pointsToRedeem
double
Points needed for the rule to be redeemed
valueOfPoint
double
In the case of a rule of type general_settings, this attribute specifies the monetary value of one point.
ruleType
string
Indicates the type of the rule and can be one of the following:
free_shipping_settings For rule that redeems a free shipping coupon
percentage_discount_settings: For rule that redeems a percentage based discount coupon
free_product_settings: For rule that redeems a free product coupon
fixed_rate_settings For rule that redeems a coupon that discounts a fixed amount
general_settings For general rule that allows user to trade points for their monetary value
custom
startDate
DateTime
Starting date when the rule can be applied (If null then it starts from the date it is created).
endDate
DateTime
Ending date when the rule will expire (If null then it will not expire).
coupon
object
A coupon object describing the coupon that is awarded when the rule is redeemed.
availableTo
object
An AvailableTo object specifying the availability of the rule (To whom this rule will be available).
howToRedeem
string
A text displaying the how to redeem section as configured in the dashboard
if lang header was provided the returned text will adapt to the sent lang parameter, else the default lang text will be returned.
availableTo Object
Parameter
Type
Description
level
object
A Level object indicating the level that the rule is available to,
The Level object has the following attributes:
levelName
String
levelId
int
tags
array
An array of tag names that the rule is available to
coupon Object
Parameter
Type
Description
couponType
string
Indicates the type of the coupon, the value of the string can be one of the following: 
free_shipping 
percentage_discount
fixed_discount
free_product
fixed_rate_discount
custom
discountValue
double
Indicating the discount value of the coupon, in the case of percentage it will indicate the percentage value of the discount.
minOrderValue
double
Minimum value the order has to reach in order for the coupon to be applied.
product
object
In the case of free_product coupon, a product object indicates the details of the free product.
applicableTo
object
Indicates if the coupon can only be applied to certain orders. It has the following attributes: 
collections: Array of collectionIds
productIds: Array of productIds
group
object
An object describing the coupon group which the coupon belongs to 
product Object
Parameter
Type
Description

Type	Description	Endpoint
GET	Configurations	/integrations/config
GET	Redemption Rules	/integrations/client/redemption/config
GET	Challenge Configurations	/integrations/config/challenge/{handle}
GET	Cashback Rules	/integrations/client/cashback

Parameter	Type	Description
`currency`	string	Configured Currency Example: `"USD", "EUR"`.
`programName`	string	Name of your program. Example: `"TRIPLE H Store"`
`rankPointsName`	string	Name of the rank points, measuring player's progress.
`walletPointsName`	string	Name of the points (monetary value).
`botMainColor`	string	The main color of your bot as configured from your Gameball dashboard.
`controlConfig`	object	An object describing the activity of the main factors.
`levels`	array	An array of level objects describing each level along with its configurations
`challenges`	array	An array of challenge objects describing each level along with its configurations
`referral`	object	An object describing the referral program configurations.
`cashback`	object	An object describing the cashback program configurations
`redemption`	object	An object describing the redemption configurations The redemption object is described as follows `redemptionFactor`: Indicates the monetary value which one point is equivalent to. Example: Redemption Value of 1 point is 0.01 (redemption factor). `redemptionRules`: Array of Redemption Rule objects

Parameter	Type	Description
`gameballEnabled`	boolean	Indicates whether Gameball is enabled or not.
`redemptionEnabled`	boolean	Indicates whether redemption configurations is enabled or not.
`cashbackEnabled`	boolean	Indicates whether cashback program is enabled or not.
`referralEnabled`	boolean	Indicates whether referral program is enabled or not.
`visitorProfileEnabled`	boolean	Indicates whether guest view is enabled or not.
`userProfileEnabled`	boolean	Indicates whether user view is enabled or not.
`leaderboardEnabled`	boolean	Indicates whether Leaderboard configurations are enabled or not.
`notificationsEnabled`	boolean	Indicates whether Notifications configurations are enabled or not.
`achievementsEnabled`	boolean	Indicates whether Achievements configurations are enabled or not.

Parameter	Type	Description
`minProgress`	integer	The required score to reach the level.
`order`	integer	Level Order
`icon`	string	icon URL of the level.
`name`	string	Level Name
`benefits`	object	`"benefits":{` `"rankReward":0,` `"walletReward":0,` `"levelDiscount":0,` `"discountCapping":0,` `"others":[]` `}` The benefits object is defined as follows: `rankReward`: Score rewarded upon reaching that level. `walletReward` : Points rewarded upon reaching that level. `levelDiscount`: The discount amount that the level grants. `discountCapping`: The maximum value to which the discount is applicable. Example: 10% discount for maximum order price 100 USD `others`: An array of statement(s) that can be used to describe the benefits of the level.

Parameter	Type	Description
`id`	integer	Unique identifier for the challenge.
`name`	string	Challenge Name
`description`	string	Challenge Description
`rankReward`	integer	Awarded rank upon challenge completion
`walletReward`	integer	Awarded points upon challenge completion
`repeatable`	boolean	A flag that indicates whether the challenge is repeatable or not.
`maxAchievement`	integer	An integer that defines how many times a player can achieve that challenge.
`type`	string	The type of the challenge. Possible values are as follows: `SignUp` `SocialMedia` `ScheduledChallenge` `EventBased` `HighScore` `Birthday` `Anniversary`
`visibility`	string	Defines the visibility of the challenge. Possible values are: `"AlwaysVisibile"` `"NotVisible"` `"VisibleIfEarned"`
`icon`	string	The icon's URL of the challenge.
`availability`	object	`"availability":{` `"minLevel": 4,` `"tags": ["VIP"]` `}` An object that describes challenge availability to players. `minLevel` : Minimum required level for the player to be eligible to the achieve the challenge. `tags`: Array of tags for which the challenge is available.
`redirectionButtonText`	string	Defines the text written on the redirection button (In case the redirection button is enabled for this challenge).
`redirectionButtonLink`	string	Defines the redirection link (In case the redirection button is enabled for this challenge).

Configurations 👑

Available Endpoints

GET - Configurations

Request

Header

Response

`controlConfig` Object

`level` Object

`challenge` Object

`referral` Object

`cashback` Object

Sample Response

Usage Example

GET - Challenge Configurations

Request

Header

Path Parameters

Response

`challengesConfig` object

Sample Response

GET - Redemption Rules

Request

Header

Response

`redemptionRule` object

`availableTo` Object

`coupon` Object

Attribute	Type	Required	Description
`APIKey`	string	Yes	Client API key
`lang`	string	No	Language filter. This could be used to specify the language needed to display your configurations in. If not provided, the response would be in default language. Note: The language provided should be as per configured languages in your account. Example: `"en"`, `"fr"`.

Parameter	Type	Description
`isRedemptionActive`	boolean	A Boolean flag indicating if the redemption program is active for the client

`pointsExpiryPeriod`	int	Number of days that the points will expire after being rewarded
`redemptionRules`	array	An array of redemptionRule objects of the client.

Parameter	Type	Description
`id`	integer	Unique Identifier of the redemption rule.
`pointsToRedeem`	double	Points needed for the rule to be redeemed
`valueOfPoint`	double	In the case of a rule of type `general_settings`, this attribute specifies the monetary value of one point.
`ruleType`	string	Indicates the type of the rule and can be one of the following: `free_shipping_settings` For rule that redeems a free shipping coupon `percentage_discount_settings`: For rule that redeems a percentage based discount coupon `free_product_settings`: For rule that redeems a free product coupon `fixed_rate_settings` For rule that redeems a coupon that discounts a fixed amount `general_settings` For general rule that allows user to trade points for their monetary value `custom`
`startDate`	DateTime	Starting date when the rule can be applied (If null then it starts from the date it is created).
`endDate`	DateTime	Ending date when the rule will expire (If null then it will not expire).
`coupon`	object	A coupon object describing the coupon that is awarded when the rule is redeemed.
`availableTo`	object	An AvailableTo object specifying the availability of the rule (To whom this rule will be available).
`howToRedeem`	string	A text displaying the how to redeem section as configured in the dashboard if lang header was provided the returned text will adapt to the sent lang parameter, else the default lang text will be returned.

Parameter	Type	Description
`level`	object	A Level object indicating the level that the rule is available to, The Level object has the following attributes: levelName String levelId int
`tags`	array	An array of tag names that the rule is available to

Parameter	Type	Description
`couponType`	string	Indicates the type of the coupon, the value of the string can be one of the following: `free_shipping` `percentage_discount` `fixed_discount` `free_product` `fixed_rate_discount` `custom`
`discountValue`	double	Indicating the discount value of the coupon, in the case of percentage it will indicate the percentage value of the discount.
`minOrderValue`	double	Minimum value the order has to reach in order for the coupon to be applied.
`product`	object	In the case of `free_product` coupon, a product object indicates the details of the free product.
`applicableTo`	object	Indicates if the coupon can only be applied to certain orders. It has the following attributes: `collections`: Array of collectionIds `productIds`: Array of productIds
`group`	object	An object describing the coupon group which the coupon belongs to