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 rewards campaign and tracks the relative customer's progress.

Parameter	Type	Description
id	integer	Unique identifier for the rewards campaign.
name	string	Rewards Campaign Name
description	string	Rewards Campaign Description
rankReward	integer	Awarded rank upon rewards campaign completion
walletReward	integer	Awarded points upon rewards campaign completion
repeatable	boolean	A flag that indicates whether the rewards campaign is repeatable or not.
maxAchievement	integer	An integer that defines how many times a customer can achieve that rewards campaign.
type	string	The type of the rewards campaign. Possible values are as follows: SignUp SocialMedia ScheduledChallenge EventBased HighScore Birthday Anniversary
visibility	string	Defines the visibility of the rewards campaign. Possible values are: "AlwaysVisibile" "NotVisible" "VisibleIfEarned"
icon	string	The icon's URL of the rewards campaign.
availability	object	"availability":{ "minLevel": 4, "tags": ["VIP"] } An object that describes rewards campaign availability to customers. minLevel : Minimum required VIP tier for the customer to be eligible to the achieve the rewards campaign. tags: Array of tags for which the rewards campaign 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 customers' 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 customer rank and progress in the leaderboard based on the specified query parameters.

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

{
  "displayName": "Customer 1",
  "playerUniqueId": "5097238429738",
  "progress": 1748,
  "rank":1,
  "levelName": "Bronze",
  "levelIcon": "https://cdn.gameball.co/uploads/c007/[e-mail]"
}

Level Object

Contains information about the customer's current VIP tier.‌

Parameters Description

Parameter	Type	Description
minProgress	integer	The required score to reach the VIP tier.
order	integer	VIP Tier Order
icon	string	icon URL of the VIP tier.
name	string	VIP Tier 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 VIP tier. walletReward : Points rewarded upon reaching that VIP tier. levelDiscount: The discount amount that the VIP tier 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 VIP tier.

{
    "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 customer 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 customer's score.‌

Parameters Description

Parameter	Type	Description
scoreBalance	string	Customer Score
scoreName	string	The naming of the score points that appears to the customer.

"score": {
        "scoreBalance": 15830,
        "scoreName": "Score"
    }

PlayerAttributes Object

Contains all of the attributes describing your customer.‌

Parameters Description

Parameter	Type	Description
displayName	string	Customer's display name
firstName	string	Customer's first name
lastName	string	Customer's last name
gender	string	Customer's gender. Example: M or F, Male or Female.
email	string	Customer's email
mobile	string	Customer's mobile
dateOfBirth	string	Customer's date of birth Example: "1980-09-19T00:00:00.000Z"
joinDate	string	Customer join date at your system. Example: "2019-09-19T21:06:29.158Z"
tags	string	Comma separated string of tags to be attached to the customer . Example: "VIP,Platinum"
community	string	Describe which community a customer belongs to.
custom	object	Key value pairs of any extra customer 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 customer's points.‌

Parameters Description

Parameter	Type	Description
pointsBalance	number	Customer Points
pointsValue	number	The actual value equivalent to customer points.
currency	string	Store Currency
pointsName	string	The naming of the rewarding points that appears to the customer.

"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 customers, Possible values: "PlayerAndFriend" denotes that both the referring and the referred customer should be rewarded. The referred customer also should complete the sign up process and perform a certain action according to your configurations. "PlayerOnly" denotes that only the referring customer that should be rewarded after a successful referral. "PlayerAndGuest" denotes that both the referring and the referred customer should be rewarded. Referred Customer 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 customer'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 customer 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 customer 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 customer reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred customer 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	Customer unique identifier used to uniquely identify the customer 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"
}