Customer
The Customer API can be used to create, update and display customers' information as well as attach/detach tags in Gameball. Customers are uniquely identified by playerUniqueId.
Available Endpoints
Type
Description
Endpoint
POST
/integrations/player
GET
/integrations/player/{playerUnqiueId}
GET
/integrations/player/{playerUnqiueIdl}/balance
GET
/integrations/player/{playerUnqiueId}
/hash
GET
/integrations/player/{playerUnqiueIdl}/progress
DELETE
/integrations/player/{playerUnqiueId}
GET
/integrations/player/{playerUnqiueIdl}/progress/challenge/{handle}
GET
/integrations/transactions/{playerUniqueId}/coupon
GET
/integrations/players/{playerUniqueId}/referrals
GET
/integrations/players/referrals
POST
/integrations/player/{playerUnqiueId}/tags
DELETE
/integrations/player/{playerUnqiueId}/tags
POST - Create Customer
The API call is used to create or update a customer in Gameball with the provided attributes.
This endpoint could also be used in case of referral. In such case,referralCode
of the referring customer is to be provided along with the body parameters. So that Gameball understands that the newly created customer is being referred.
mobile
or email
should be sent along with the playerUniqueId
in case (only if) your account supports channel merging.
In cases where channel merging is supported, you have the flexibility to identify users by their mobile number or email. For accounts utilizing separate systems for online and offline channels, it's advisable to consider changing the customer's unique ID to either their mobile number or email address for enhanced efficiency.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer in your database.
Could be database ID, random string, email or anything that uniquely identifies the customer.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer's unique email. (Sent in case your account supports channel merging)
playerAttributes
object
No
referrerCode
string
No
Referring customer’s referral code. This is used in case of referral, where the customer to be created is referred by the customer having this code.
levelOrder
integer
No
The VIP tier order to place the customer in.
IMPORTANT: manual customer VIP tiering is available under special circumstances and is not available by default. Contact us for more info.
deviceToken
string
No
The FCM token (Firebase Cloud Messaging) needed for sending mobile push notifications. (Used only in case of mobile app)
osType
string
No*
OS Type according to the mobile device used (if any).
Note: Required in case deviceToken
is sent in the payload (e.g. "android", "ios")
guest
boolean
No
Guest attribute identifies whether the individual interacting with your system is a guest (someone who has not signed up) or a registered customer.
playerAttributes
Object
playerAttributes
ObjectParameter
Type
Description
displayName
string
Customer's display name.
firstName
string
Customer's first name.
lastName
string
Customer's last name.
mobile
string
Customer's mobile number.
gender
string
Customer's gender. Example: M or F, Male or Female.
email
string
Customer's email.
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"
country
string
Country of the customer.
city
string
City of the customer.
zip
string
ZIP of the customer.
totalSpent
float
Total amount spent by customer.
totalOrders
int
Total orders by customer.
lastOrderDate
date
Last order date.
avgOrderAmount
float
Average order amount.
custom
object
Key value pairs of any extra player attributes.
{"class" : "E2022", "weight" : 78}
Response
Parameter
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball
Note: in case your account supports channel merging, mobile
or email
could be used instead of playerUniqueId.
gameballId
string
Customer's ID at Gameball.
levelsProgress
int
The current progress of customer on the VIP tier.
level
object
balance
object
referralCode
string
Customer's Referral Code. Used to refer another customer.
referralLink
string
Referral URL.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
Sample Response
Usage Examples
Example One
This example creates a new customer at Gameball, using playerUniqueId
, playerAttributes
with custom
attributes.
Example Two
This example is a request sent to Gameball when customer with referralCode
“CODE11” successfully refers a new customer with playerUniqueId
“player456”. Customer attributes are also sent within the same request.
Note: All attributes inside the playerAttributes
object are optional, if the values of any attributes shown below are unavailable, remove the attribute from the playerAttributes
object.
GET - Retrieve Customer
This API call is used to retrieve customer's information.
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
Lang
string
No
Language to get the customer info with. 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"
.
Path Parameters
Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, mobile
or email
could be used instead of playerUniqueId
Response
Parameter
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball.
playerAttributes
object
referralCode
string
Customer's Referral Code. Used to refer another customer.
referralLink
string
Referral URL.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
level
object
levelsProgress
int
The current progress of the customer on the VIP tier.
points
object
The current balance of the customer.
Level
Object
Level
ObjectThe Level object contains info about the customer's current VIP tier.
Parameter
Type
Description
name
string
VIP tier Name.
description
string
VIP tier Description.
levelOrder
integer
VIP tier Order.
iconPath
string
Logo icon of the VIP tier.
benefits
object
An object contains the benefits of the current VIP tier of the specified customer.
The benefits object is described as follows:
scoreEntryReward
: Rewarded score on entering the current VIP tier.pointsEntryReward
: Rewarded points on entering the current VIP tier.levelDiscount
: Discount rewarded to the customer on entering the current VIP tier.discountCapping
: Maximum order total price that allows the discount to be applied.
Sample Response
Usage Example
The example shown is a request sent to Gameball to get a customer info with playerUniqueId
“player456”.
GET - Customer's Balance
This API call is used to retrieve customer's current points balance available for redemption and the corresponding equivalent amount.
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
secretKey
string
Yes
Client Secret Key
Path Parameters
Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, mobile
or email
could be used instead of playerUniqueId
Response
pointsBalance
integer
Customer current points balance.
pointsValue
integer
pendingPoints
integer
Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue
integer
totalPositivePoints
integer
Customer current total positive points.
totalPositivePendingPoints
integer
Customer current positive pending points.
totalNegativePoints
integer
Customer current total negative points.
totalNegativePendingPoints
integer
Customer current negative pending points.
currency
string
Store currency.
pointsName
string
The naming of the rewarding points that appears to the customer.
Sample Response
Usage Example
The example shown is a request sent to Gameball to get a customer's balance with his playerUniqueId
GET - Customer's Hash
This API call is used to retrieve customer's hash value which is calculated for each customer, and rotates with the customer's every transaction.
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
secretKey
string
Yes
Client Secret Key
Path Parameters
Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, mobile
or email
could be used instead of playerUniqueId
Response
Parameter
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball.
referralCode
string
Customer's Referral Code. Used to refer another customer.
referralLink
string
Referral URL.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
pointsBalance
integer
Customer current points balance.
pointsValue
number
pendingPoints
integer
Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue
number
currency
string
Store currency.
pointsName
string
The naming of the rewarding points that appears to the customer.
hash
string
A secret number hash that is calculated for each customer, and rotates with the customer's every transaction.
Sample Response
Usage Example
The example shown is a request sent to Gameball to get a customer's balance with his playerUniqueId
GET - Customer's Progress 👑
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
This API call is used to show the overall customer's progress in the available rewards campaigns, referral program and VIP tiers across Gameball programs.
This endpoint is only available for our GURU clients only 👑
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client APIKey
secretKey
string
Yes
Client Secret Key
Path Parameters
Parameter
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Response
Parameter
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball.
referralCode
string
Customer's referral code.
referralLink
string
Customer's referral link.
dynamicReferralLink
string
Referral URL for mobile APPs integrations with firebase.
playerAttributes
object
levelsProgress
object
An object contains the VIP tier information of the current
and the next
VIP tier (empty if the customer is on top VIP tier already) of the specified customer.
The Level object is described as follows:
order
: VIP tier's tier e.g., VIP tier 1, VIP tier 2, VIP tier 3.name
: VIP tier name.
minProgress
: Minimum score to be in that VIP tier .icon
: The icon URL describing the VIP tier .progress
: The current progress of customer on the VIP tier .
challengesProgress
array
totalReferredPlayers
integer
The total number of the customer's referred customers.
balance
object
balance
Object
balance
ObjectThe balance object contains info about the customer's points.
Parameter
Type
Description
pointsBalance
integer
Customer current points balance.
pointsValue
number
pendingPoints
integer
Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue
number
currency
string
Your system currency as configured at Gameball.
pointsName
string
The naming of the rewarding points that appears to the customer.
challenge
Object
challenge
ObjectThe challenge object shows description of the rewards campaigns as follows.
Parameter
Type
Description
isUnlocked
boolean
Indicates whether the rewards campaigns is unlocked for this customer or not.
highScoreAmount
integer
Indicates the customer's High Score. Note: This field is provided in case the rewards campaign is a High Score rewards campaign.
currentStreak
integer
The current streak refers to the count of the most recent and uninterrupted series of consecutive events or occurrences.
highestStreak
integer
The highest streak refers to the count of the longest unbroken sequence of events or occurrences achieved at any point in time.
completionPercentage
number
Shows the customer's current progress towards achieving the rewards campaign.
achievedCount
integer
The number of times this rewards campaign has been achieved by the customer.
challengeConfig
object
challengeConfig
Object
challengeConfig
Objectid
integer
Rewards Campaign Id.
name
string
Rewards Campaign internal name.
description
string
Rewards Campaign description.( In default language if not specified in query parameter)
rewards
array
isRepeatable
boolean
A boolean indicating if the Rewards Campaign is repeatable for the specified customer or not.
maxAchievement
integer
Maximum number of times the specified Rewards Campaign can be achieved. (-1 if can be achieved for an unlimited number of times)
type
string
Rewards Campaign type, can be one of the following:
Amount Based
Action Based
ActionBasedAndAmountBased
HighScore
UponLogin
NonCumulativeAmountBased
JoinAnniversary
EventBased
SocialActivities
ScheduledChallenge
Streak
visibility
string
Rewards Campaign 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 rewards campaign.
availability
Object
redirectionButtonText
string
The text written on the redirection button. (In case the redirection button is enabled for this rewards campaign).
redirectionButtonLink
string
The redirection link. (In case the redirection button is enabled for this rewards campaign)
reward
Object
reward
ObjectrankReward
integer
Progress rewarded towards rank.
walletReward
integer
Points rewarded in wallet.
couponReward
Object
couponReward
Object
couponReward
ObjectcouponType
string
Coupon type, can be one of the following:
Fixed
Percentage
Free Shipping
Free Product
Fixed Rate Discount
discountValue
double
Value of coupon, for example if the coupon rewards a fixed amount of points then the amount of points will be in discountValue.
minOrderValue
double
Minimum order value that this coupon can be applied to.
product
Object
In the case of a free product coupon this object indicates the details of the product,
The object has the the following attributes:
productId
productName
variantId
variantName
collections
array
Array of Collection objects in the case where the coupon can only be applied to specific collections, the collection object has the following attributes:
collectionId
collectionName
availability
Object
availability
ObjectminLevel
integer
Minimum VIP tier where this rewards campaign is available.
tags
array
An array of Tag names. (string)
Sample Response
Usage Example
The example shown is a request sent to Gameball to get a customer's progress with playerUniqueId
“player456”.
GET - Customer's Rewards Campaign's Progress
This API is used to get a customer's specific rewards campaign's progress.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the
customer at Gameball.
handle
string
Yes
Identifier of the rewards campaign, either the challengeId
, or the rewards campaign internal name.(Note: If rewards campaign name has the space character please replace it with customer would be New%20customer)
Query Parameters
Attribute
Type
Required
Description
lang
string
No
The language you wish to retrieve the information in.
Response
Attribute
Type
Description
challengesProgress
array
challengesProgress
Object
challengesProgress
ObjectAttribute
Type
Description
isUnlocked
boolean
A boolean indicating if the rewards campaign is unlocked for the specified customer.
highScoreAmount
double
Score reached so far. (Could be highScore or greater) (High Score Rewards Campaigns)
highScore
double
Score needed to be reached to achieve the rewards campaign. (High Score Rewards Campaigns)
completionPercentage
double
Percentage completed of rewards campaign. (Event based Rewards Campaigns)
achievedCount
integer
Number of times rewards campaign has been achieved by the specified customer.
currentStreak
integer
Current streak the specified customer is on.
highestStreak
integer
Highest streak the specified customer has reached.
challengeConfig
Object
Sample Response
Usage Example
The example shown is a request sent to Gameball to get a customer's rewards campaign's progress with playerUniqueId
“player456” and challengeHandle “New%20customer”
DELETE - Delete Customer
This API is used to delete a customer along with his attributes, transactions, achievements and actions.
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Usage Example
GET - Customer's Coupons
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
This endpoint is used to get the Coupons of a specific customer.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Response
Attribute
Type
Description
coupons
array
coupon
Object
coupon
Objectcode
string
Coupon Code.
isUsed
boolean
A boolean indicating if the coupon was used by the specified customer.
value
double
Value of coupon. ( in the case of percentage discount this would be the value in percentage of the coupon)
currency
string
Currency of the coupon.
creationDate
DateTime
The date that the coupon was created on.
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
product
object
startAt
DateTime
Date that the coupon starts at and can be applied.
endAt
DateTime
Date that the coupon expires at.
isExpired
boolean
Boolean indicating if the coupon is expired.
collections
array
An array of Collection Objects specifying the collections that the coupon can be applied on.
group
object
options
object
product
Object
product
ObjectproductId
integer
Unique identifier of the product.
productName
string
Name of the product.
productDisplayName
array
An array of display names for the product.
variantId
integer
In case the product has variants this is the id of the variant.
variantName
string
In case the product has variants this is the name of the variant.
collection
Object
collectionId
integer
Unique identifier of the collection.
collectionName
string
Name of the collection.
group
Object
group
Objecthandle
string
A unique identifier for the coupon group.
title
string
Title of the coupon group.
url
string
URL of the coupon group.
iconPath
string
Icon path of the coupon group.
description
string
Description of the coupon group.
maxPerPlayer
integer
Maximum number of times a customer can achieve coupons from this group.
startDate
DateTime
Date at which coupons can start to be redeemed from this group.
expiryDate
DateTime
Date at which you can no longer redeem coupons from this group.
isAvailable
boolean
A boolean flag indicating if there are coupon available to be redeemed from this group.
isValid
boolean
Flag indicating if the group is valid (Current Date is between start and expiry dates).
isActive
boolean
Flag indicating if the group is active or not (Client marked the group as active or not and group’s dates are valid).
options
Object
options
ObjectExpiryAfter
integer
Number of days until the coupon expires.
UsageLimit
integer
Maximum number of times a coupon or offer can be used.
Capping
double
Maximum limit on the total amount of discount that can be applied to an order.
MinOrderValue
double
The lowest amount a customer must spend on an order to qualify for the coupon.
CombinesWith
object
An object that that determines whether specific types of discounts can be combined and consists of three boolean values:
ShippingDiscounts
ProductDiscounts
OrderDiscounts
ProductId
string
Unique identifier of the product.
ProductName
string
Name of the product.
VariantId
string
In case the product has variants this is the id of the variant.
VariantName
string
In case the product has variants this is the name of the variant.
ProductDisplayName
string
Display name for the product.
HasCollections
boolean
Indicates if it has collections.
Platforms
array
List of platforms.
Sample Response
Usage Example
GET - Customer's Referrals
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
This endpoint is used to get the Referrals of a specific customer with the status of the referral for each referred customer, whether the referral has been completed (active
) or pending the needed referral action (pending
) as per your referral configurations.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Path Parameters
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Query Parameters
Attribute
Type
Required
Description
page
integer
No
Index of required page. (e.g. 1, 2, ..) Default: 1
limit
integer
No
limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200
Response
Attribute
Type
Description
referredFriends
array
count
integer
Count of customers in current page.
total
integer
Total number of customers referred by the given customer.
totalPending
integer
Total "pending"
number of customers referred by the given customer but haven't completed the required referral action (e.g. Placed an order).
totalActive
integer
Total "active"
number of customers successfully referred by the given customer and have completed the required referral action (e.g. Placed an order).
referredFriend Object
playerUniqueId
string
Unique identifier for the customer at Gameball.
displayName
string
Customer's display name.
email
string
Customer's email.
mobileNumber
string
Customer's mobile number.
joinDate
DateTime
The date at which the customer joined the store.
status
string
Indicates the status of the referred customer, the value of the string can be one of the following:
active
pending
Sample Response
Usage Example
GET - Get all Customer's Referrals
This endpoint is used to retrieve a comprehensive list of all referrals made by all customers along with the status of each referral for each referred customer, whether the referral has been completed (active
) or pending the needed referral action (pending
) as per your referral configurations.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Query Parameters
Attribute
Type
Required
Description
page
integer
No
Index of required page. (e.g. 1, 2, ..) Default: 1
limit
integer
No
limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200
Response
Attribute
Type
Description
referredFriends
array
count
integer
Count of customers in current page.
total
integer
Total number of customers referred by the given customer.
referredFriend Object
playerUniqueId
string
Unique identifier for the customer at Gameball.
displayName
string
Customer's display name.
email
string
Customer's email.
mobileNumber
string
Customer's mobile number.
joinDate
DateTime
The date at which the customer joined the store.
status
string
Indicates the status of the referred customer, the value of the string can be one of the following:
active
pending
referredBy
object
referredBy Object
Attribute
Type
Description
playerUniqueId
string
Unique identifier for the customer at Gameball.
displayName
string
Customer's display name.
email
string
Customer's email.
mobileNumber
string
Customer's mobile number.
Sample Response
Usage Example
POST - Attach Tags to Customer
This API is used to attach tags to a Customer.
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Path Parameters
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer at Gameball.
Body
Attribute
Type
Required
Description
tags
string
Yes
Comma separated string of tags to be attached to the customer.
Sample Body
Usage Example
The example shown is a request sent to Gameball to attach tags
"VIP,Platinum" to a customer with playerUniqueId
“player456”.
DELETE - Detach Tags
mobile
or email
should replace playerUniqueId
in case (only if) your account supports channel merging.
This API is used to detach tags from a customer.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Path Parameters
playerUniqueId
Yes
string
Unique identifier for the customer at Gameball.
Body
Attribute
Type
Required
Description
tags
string
Yes
Comma separated string of tags to be removed from the customer.
Sample Body
Usage Example
The example shown is a request sent to Gameball to detach tags
"VIP" from a customer with playerUniqueId
“player456”.
Last updated