Object Reference
This section provides a list of the objects dealt with using the available API endpoints.
Last updated
This section provides a list of the objects dealt with using the available API endpoints.
Last updated
The cashback object is returned in the Configurations API response body. It describes the cashback program configurations.
Represents the challenge object that describes a configured rewards campaign and tracks the relative customer's progress.
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.
The following example shows a collection of events
Defines the customer rank and progress in the leaderboard based on the specified query parameters.
Contains information about the customer's current VIP tier.
Represent a Product in your system with its relative information, this object is used in the Orders API.
Holds information of merchant and its branch
Represents a notification that your customer receives.
Contains info about the customer's score.
Contains all of the attributes describing your customer.
Contains information about the customer's points.
The referral object is returned in the configurations API response body. It describes the referral program configurations.
Describes any transaction made in your system.
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 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.
Event Name
Key
Value
buy
product_id
a123456
price
30
product_category
fashion
product_tags
men & new_collection
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.
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.
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"
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
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.
Parameter
Type
Description
scoreBalance
string
Customer Score
scoreName
string
The naming of the score points that appears to the customer.
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}
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.
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.
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