Object Reference

This section provides a list of the objects dealt with using the available API endpoints.

Cashback Object
The cashback object is returned in the Configurations API response body. It describes the cashback program configurations.
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"
{
    "rewardFactor":0.3,
    "amountRewardThreshold":10,
    "rewardWalletFactor":3,
    "rewardRankFactor":1
}
Challenge Object
Represents the challenge object that describes a configured challenge and tracks the relative player's progress.
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.
{
   "id":3350,
   "name":"view product + tag internal",
   "description":"",
   "rankReward":3,
   "walletReward":10,
   "repeatable":true,
   "maxAchievement":0,
   "type":"EventBased",
   "visibility":"AlwaysVisible",
   "icon":"[email protected]",
   "availability":{
      "minLevel":5,
      "tags":[
         "2nd tag"
      ]
   }
}
Event Object
The Event object is how you record any actions your users perform, along with any metadata that describe the action. For further elaboration on events check Understand your players' events.‌
Event and Metadata example:
Event Name
Key
Value
buy
product_id
a123456
​
price
30
​
product_category
fashion
​
product_tags
men & new_collection
"buy": {
  "product_id": "a123456",
  "price": 30,
  "product_category": "fashion"
  "product_tags": ["men", "new_collection"]
}
The following example shows a collection of events
"events": {
    "buy": {
      "category": "Electronics",
      "amount": 300
    },
    "travel": {
      "destinations": ["Paris", "Cairo"],
      "tickets": 4,
      "season": "Winter"
    },
    "visit_branch": {}
}
Leaderboard object
Defines the player rank and progress in the leaderboard based on the specified query parameters.
Parameter
Type
Description
displayName
string
Player's display name.
playerUniqueId
string
Unique identifier for a player at Gameball.
progress
integer
Player's progress (based on the specified query parameters).
rank
integer
Player's Rank (based on the specified query parameters).
levelName
string
Level Name.
Example: "Bronze"
levelIcon
string
Level's icon URL.
{
  "displayName": "Player 1",
  "playerUniqueId": "5097238429738",
  "progress": 1748,
  "rank":1,
  "levelName": "Bronze",
  "levelIcon": "https://cdn.gameball.co/uploads/c007/[email protected]"
}
Level Object
Contains information about the player's current level.‌
Parameters Description
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. 
{
    "name": "Gold",
    "description": null,
    "levelStartScore": 7500,
    "levelOrder": 4,
    "iconPath": "https://cdn.gameball.co/uploads/Client 1/[email protected]",
    "benefits": {
        "scoreEnteryReward": 0,
        "pointsEnteryReward": 0,
        "levelDiscount": null,
        "discountCapping": null
    }
}
LineItems Object
Represent a Product in your system with its relative information, this object is used in the Orders API.
Attribute
Type
Description
productId
string
The ID of the product that the line item belongs to
sku
string
The item's SKU (stock keeping unit).
title
string
The title of the product.
category
array
Product category (fashion, electronics.. etc). It can be one category or multiple categories.
Example:["natural","cosmetics"]
collection
array
Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store.
Example:["14313","4343"]
tags
array
Tag(s) attached to the item in the order.
Example:["VIP", "Elite"]
weight
number
Item weight. Must be positive.
vendor
string
The name of the item's supplier.
Example:"nike"
{
  "productId":"197765",
  "tag": ["VIP"],
  "category": [
      "natural",
      "cosmetics"
   ],
   "weight": "20",
   "vendor": "nike",
   "collection": ["14313", "4343"]
}
Merchant Object
Holds information of merchant and its branch‌
Parameters Description
Parameter
Type
Description
uniqueId
string
Merchant unique id or code
name
string
Merchant name
branch
string
Optional branch information
branch.uniqueId
string
Branch unique id or code
branch.name
string
Branch name
"merchant": {
    "uniqueId": "string",
    "name": "string",
    "branch": {
      "uniqueId": "string",
      "name": "string"
    }
  }
Notification Object
Represents a notification that your player receives.
Attribute
Type
Description
notificationId
string
Unique Identifier for a notification
title
string
Notification Title
body
string
Notification Body
isRead
boolean
Indicates whether the notification is read or not.
createdAt
string
Notification's creation date, as an ISO8601 timestamp.
Example: "2019-09-21T16:53:28.190Z"
lang
string
The language in which the notification is displayed. In case the lang is not provided in the request, defaultlang is returned.
Note: The language provided should be as per configured languages in your account.
Example: "en", "fr".
icon
string
Notification's icon URL.
{
   "notificationId" : "123",
   "title": "New level!",
   "body": "Keep it up! You are now on Bronze ",
   "isRead": true,
   "createdAt": "2021-05-12T00:08:09.646174",
   "lang": "en",
   "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb-icon-level-13.png"
}
Score Object
Contains info about the player's score.‌
Parameters Description
Parameter
Type
Description
scoreBalance
string
Player Score
scoreName
string
The naming of the score points that appears to the player.
"score": {
        "scoreBalance": 15830,
        "scoreName": "Score"
    }
PlayerAttributes Object
Contains all of the attributes describing your player.‌
Parameters Description
Parameter
Type
Description
displayName
string
Player's display name
firstName
string
Player's first name
lastName
string
Player's last name
gender
string
Player's gender. Example: M or F, Male or Female.
email
string
Player's email
mobile
string
Player's mobile
dateOfBirth
string
Player's date of birth
Example: "1980-09-19T00:00:00.000Z"
joinDate
string
Player join date at your system.
Example: "2019-09-19T21:06:29.158Z"
tags
string
Comma separated string of tags to be attached to the player.
Example: "VIP,Platinum"
community
string
Describe which community a player belongs to.
custom
object
Key value pairs of any extra player attributes.
{"class" : "E2022", "weight" : 78}
"playerAttributes": {
    "displayName":"Jon Snow",
    "firstName": "Jon",
    "lastName": "Snow",
    "email":"[email protected]",
    "mobile": "+1234567",
    "gender":"M",
    "dateOfBirth":"1980-09-19T00:00:00.000Z",
    "joinDate":"2019-09-19T21:06:29.158Z",
    "tags": "VIP,Platinum",
	  "custom":{
       "location":"Miami",
       "graduationDate":"2018-07-04T21:06:29.158Z",
       "isMarried":false
    }
}
Points Object
Contains information about the player's points.‌
Parameters Description
Parameter
Type
Description
pointsBalance
number
Player Points
pointsValue
number
The actual value equivalent to player points.
currency
string
Store Currency
pointsName
string
The naming of the rewarding points that appears to the player.
"points": {
        "pointsBalance": 11500,
        "pointsValue": 115,
        "currency": "USD",
        "pointsName": "Points"
    }
Referral Object
The referral object is returned in the configurations API response body. It describes the referral program configurations.
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.
{
   "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
      }
   }
}
Transaction object
Describes any transaction made in your system.
Attribute
Type
Description
transactionId
string
Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
gameballTrasnactionId
integer
Transaction ID on Gameball system.
type
string
Transaction type string. Can be one of the following:
AchievementReward
PaymentReward
Refund
Redemption
Expiry
Cancel
Migration
ManualAccumulation
DiscountCode
ManualDeduction
ManualReward
direction
string
Either "+" or "-" indicating transaction was an addition or deduction
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
points
integer
Number of points involved in the transaction
amount
number
Monetary amount involved in the transaction
transactionTime
string
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
merchantName
string
Merchant name for transaction
branchName
string
Branch Name for transaction
{
  "transactionId":"trx123",
  "gameballTransactionId":"gbtrx123",
  "transactionTime":"2019-09-21T16:53:28.190Z",
  "type":"Cash Back",
  "direction":"+",
  "playerUniqueId":"1234",
  "points":500,
  "amount":10,
  "merchantName":"merchant",
  "branchName":"branch"
}
​

REST API - Previous

Errors

Next - Tutorials

Build Custom UI Elements 👑

Last modified 1yr ago

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"

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.

Parameter	Type	Description
`displayName`	string	Player's display name.
`playerUniqueId`	string	Unique identifier for a player at Gameball.
`progress`	integer	Player's progress (based on the specified query parameters).
`rank`	integer	Player's Rank (based on the specified query parameters).
`levelName`	string	Level Name. Example: `"Bronze"`
`levelIcon`	string	Level's icon URL.

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.

Attribute	Type	Description
`productId`	string	The ID of the product that the line item belongs to
`sku`	string	The item's SKU (stock keeping unit).
`title`	string	The title of the product.
`category`	array	Product category (fashion, electronics.. etc). It can be one category or multiple categories. Example:`["natural","cosmetics"]`
`collection`	array	Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store. Example:`["14313","4343"]`
`tags`	array	Tag(s) attached to the item in the order. Example:`["VIP", "Elite"]`
`weight`	number	Item weight. Must be positive.
`vendor`	string	The name of the item's supplier. Example:`"nike"`

Event Name	Key	Value
buy	product_id	a123456
	price	30
	product_category	fashion
	product_tags	men & new_collection

Attribute	Type	Description
`notificationId`	string	Unique Identifier for a notification
`title`	string	Notification Title
`body`	string	Notification Body
`isRead`	boolean	Indicates whether the notification is read or not.
`createdAt`	string	Notification's creation date, as an ISO8601 timestamp. Example: `"2019-09-21T16:53:28.190Z"`
`lang`	string	The language in which the notification is displayed. In case the `lang` is not provided in the request, default`lang` is returned. Note: The language provided should be as per configured languages in your account. Example: `"en"`, `"fr"`.
`icon`	string	Notification's icon URL.