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":"gb-icon-challenge-10@2x",
   "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/[e-mail]"
}

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/[e-mail]",
    "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":"[e-mail]",
    "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"
}