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 |
| string | Yes | Client API key |
Body
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer in your database. Could be database ID, random string, email or anything that uniquely identifies the customer. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging) |
| string | No | Customer's unique email. (Sent in case your account supports channel merging) |
| object | No | An object with set of properties that you want to set for the customer.
This object also includes a |
| 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. |
| 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. |
| string | No | The FCM token (Firebase Cloud Messaging) needed for sending mobile push notifications. (Used only in case of mobile app) |
| string | No* | OS Type according to the mobile device used (if any).
Note: Required in case |
| 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 |
| string | Customer's display name. |
| string | Customer's first name. |
| string | Customer's last name. |
| string | Customer's mobile number. |
| string | Customer's gender. Example: M or F, Male or Female. |
| string | Customer's email. |
| string | Customer's date of birth. Example: |
| string | Customer join date at your system. Example: |
| string | Comma separated string of tags to be attached to the customer. Example: |
| string | Country of the customer. |
| string | City of the customer. |
| string | ZIP of the customer. |
| float | Total amount spent by customer. |
| int | Total orders by customer. |
| date | Last order date. |
| float | Average order amount. |
| object | Key value pairs of any extra player attributes.
|
Response
Parameter | Type | Description |
| string | Unique identifier for the customer at Gameball
Note: in case your account supports channel merging, |
| string | Customer's ID at Gameball. |
| int | The current progress of customer on the VIP tier. |
| object | VIP tier object holds information about the customer's current VIP tier at Gameball. |
| object | An object that contains all the information about the customer's balance. |
| string | Customer's Referral Code. Used to refer another customer. |
| string | Referral URL. |
| 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 |
| string | Yes | Client APIKey |
| 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: |
Path Parameters
Parameter | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, |
Response
Parameter | Type | Description |
| string | Unique identifier for the customer at Gameball. |
| object | An object with set of customer properties defined previously at the customer's creation. |
| string | Customer's Referral Code. Used to refer another customer. |
| string | Referral URL. |
| string | Referral URL for mobile APPs integrations with firebase. |
| object | Level object holds information about the customer's current VIP tier at Gameball. |
| int | The current progress of the customer on the VIP tier. |
| 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 |
| string | VIP tier Name. |
| string | VIP tier Description. |
| integer | VIP tier Order. |
| string | Logo icon of the VIP tier. |
| object | An object contains the benefits of the current VIP tier of the specified customer. The benefits object is described as follows:
|
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 |
| string | Yes | Client APIKey |
| string | Yes | Client Secret Key |
Path Parameters
Parameter | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, |
Response
Parameter | Type | Description |
---|---|---|
| integer | Customer current points balance. |
| integer | The customer's equivalent monetary value to |
| integer | Customer current pending points. (Not active yet, therefore cannot be used at this moment) |
| integer | The customer's equivalent monetary value to |
| integer | Customer current total positive points. |
| integer | Customer current positive pending points. |
| integer | Customer current total negative points. |
| integer | Customer current negative pending points. |
| string | Store currency. |
| 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 |
| string | Yes | Client APIKey |
| string | Yes | Client Secret Key |
Path Parameters
Parameter | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball.
Note: in case your account supports channel merging, |
Response
Parameter | Type | Description |
| string | Unique identifier for the customer at Gameball. |
| string | Customer's Referral Code. Used to refer another customer. |
| string | Referral URL. |
| string | Referral URL for mobile APPs integrations with firebase. |
| integer | Customer current points balance. |
| number | The customer's equivalent monetary value to |
| integer | Customer current pending points. (Not active yet, therefore cannot be used at this moment) |
| number | The customer's equivalent monetary value to |
| string | Store currency. |
| string | The naming of the rewarding points that appears to the customer. |
| 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 |
| string | Yes | Client APIKey |
| string | Yes | Client Secret Key |
Path Parameters
Parameter | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
Response
Parameter | Type | Description |
| string | Unique identifier for the customer at Gameball. |
| string | Customer's referral code. |
| string | Customer's referral link. |
| string | Referral URL for mobile APPs integrations with firebase. |
| object | An object with set of customer properties. |
| object | An object contains the VIP tier information of the The Level object is described as follows:
|
| array | An array of rewards campaigns objects where each describe an available rewards campaigns for the customer and his progress in each. |
| integer | The total number of the customer's referred customers. |
| object | An object that describes the customer's current balance. |
balance
Object
balance
ObjectThe balance object contains info about the customer's points.
Parameter | Type | Description |
| integer | Customer current points balance. |
| number | The customer's equivalent monetary value to |
| integer | Customer current pending points. (Not active yet, therefore cannot be used at this moment) |
| number | The customer's equivalent monetary value to |
| string | Your system currency as configured at Gameball. |
| 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 |
| boolean | Indicates whether the rewards campaigns is unlocked for this customer or not. |
| integer | Indicates the customer's High Score. Note: This field is provided in case the rewards campaign is a High Score rewards campaign. |
| integer | The current streak refers to the count of the most recent and uninterrupted series of consecutive events or occurrences. |
| integer | The highest streak refers to the count of the longest unbroken sequence of events or occurrences achieved at any point in time. |
| number | Shows the customer's current progress towards achieving the rewards campaign. |
| integer | The number of times this rewards campaign has been achieved by the customer. |
| object | A |
challengeConfig
Object
challengeConfig
ObjectAttribute | Type | Description |
---|---|---|
| integer | Rewards Campaign Id. |
| string | Rewards Campaign internal name. |
| string | Rewards Campaign description.( In default language if not specified in query parameter) |
| array | An array of Reward objects, these are the rewards that are achieved by completing the specified Rewards Campaign. |
| boolean | A boolean indicating if the Rewards Campaign is repeatable for the specified customer or not. |
| integer | Maximum number of times the specified Rewards Campaign can be achieved. (-1 if can be achieved for an unlimited number of times) |
| string | Rewards Campaign type, can be one of the following:
|
| string | Rewards Campaign visibility type, can be one of the following:
|
| string | URI indicating the file path to the icon of the rewards campaign. |
| Object | An availability object specifying the conditions where this rewards campaignis available. |
| string | The text written on the redirection button. (In case the redirection button is enabled for this rewards campaign). |
| string | The redirection link. (In case the redirection button is enabled for this rewards campaign) |
reward
Object
reward
ObjectAttribute | Type | Description |
---|---|---|
| integer | Progress rewarded towards rank. |
| integer | Points rewarded in wallet. |
| Object | Coupon object that describes the coupon that is rewarded when completing this rewards campaign. |
couponReward
Object
couponReward
ObjectAttribute | Type | Description |
---|---|---|
| string | Coupon type, can be one of the following:
|
| double | Value of coupon, for example if the coupon rewards a fixed amount of points then the amount of points will be in discountValue. |
| double | Minimum order value that this coupon can be applied to. |
| Object | In the case of a free product coupon this object indicates the details of the product, The object has the the following attributes:
|
| 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:
|
availability
Object
availability
ObjectAttribute | Type | Description |
---|---|---|
| integer | Minimum VIP tier where this rewards campaign is available. |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Path Parameters
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
| string | Yes | Identifier of the rewards campaign, either the |
Query Parameters
Attribute | Type | Required | Description |
| string | No | The language you wish to retrieve the information in. |
Response
Attribute | Type | Description |
| array | A single object array of |
challengesProgress
Object
challengesProgress
ObjectAttribute | Type | Description |
| boolean | A boolean indicating if the rewards campaign is unlocked for the specified customer. |
| double | Score reached so far. (Could be highScore or greater) (High Score Rewards Campaigns) |
| double | Score needed to be reached to achieve the rewards campaign. (High Score Rewards Campaigns) |
| double | Percentage completed of rewards campaign. (Event based Rewards Campaigns) |
| integer | Number of times rewards campaign has been achieved by the specified customer. |
| integer | Current streak the specified customer is on. |
| integer | Highest streak the specified customer has reached. |
| Object | A |
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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Path Parameters
Attribute | Type | Required | Description |
| 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 |
| string | Yes | Client API key |
| string | Yes | Client Secret Key |
Path Parameters
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
Response
Attribute | Type | Description |
| array | An array of Coupon objects. |
coupon
Object
coupon
ObjectParameter | Type | Description |
---|---|---|
| string | Coupon Code. |
| boolean | A boolean indicating if the coupon was used by the specified customer. |
| double | Value of coupon. ( in the case of percentage discount this would be the value in percentage of the coupon) |
| string | Currency of the coupon. |
| DateTime | The date that the coupon was created on. |
| string | Indicates the type of the coupon, the value of the string can be one of the following:
|
| object | In the case of |
| DateTime | Date that the coupon starts at and can be applied. |
| DateTime | Date that the coupon expires at. |
| boolean | Boolean indicating if the coupon is expired. |
| array | An array of Collection Objects specifying the collections that the coupon can be applied on. |
| object | An object describing the coupon group which the coupon belongs to. |
| object | An object describing the coupon's options. |
product
Object
product
ObjectParameter | Type | Description |
---|---|---|
| integer | Unique identifier of the product. |
| string | Name of the product. |
| array | An array of display names for the product. |
| integer | In case the product has variants this is the id of the variant. |
| string | In case the product has variants this is the name of the variant. |
collection
Object
Type | Description | |
---|---|---|
| integer | Unique identifier of the collection. |
| string | Name of the collection. |
group
Object
group
ObjectParameter | Type | Description |
---|---|---|
| string | A unique identifier for the coupon group. |
| string | Title of the coupon group. |
| string | URL of the coupon group. |
| string | Icon path of the coupon group. |
| string | Description of the coupon group. |
| integer | Maximum number of times a customer can achieve coupons from this group. |
| DateTime | Date at which coupons can start to be redeemed from this group. |
| DateTime | Date at which you can no longer redeem coupons from this group. |
| boolean | A boolean flag indicating if there are coupon available to be redeemed from this group. |
| boolean | Flag indicating if the group is valid (Current Date is between start and expiry dates). |
| 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
ObjectParameter | Type | Description |
---|---|---|
| integer | Number of days until the coupon expires. |
| integer | Maximum number of times a coupon or offer can be used. |
| double | Maximum limit on the total amount of discount that can be applied to an order. |
| double | The lowest amount a customer must spend on an order to qualify for the coupon. |
| object | An object that that determines whether specific types of discounts can be combined and consists of three boolean values:
|
| string | Unique identifier of the product. |
| string | Name of the product. |
| string | In case the product has variants this is the id of the variant. |
| string | In case the product has variants this is the name of the variant. |
| string | Display name for the product. |
| boolean | Indicates if it has collections. |
| 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 |
| string | Yes | Client API key |
Path Parameters
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
Query Parameters
Attribute | Type | Required | Description |
| integer | No | Index of required page. (e.g. 1, 2, ..) Default: 1 |
| integer | No | limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200 |
Response
Attribute | Type | Description |
| array | An array of referredFriend objects. |
| integer | Count of customers in current page. |
| integer | Total number of customers referred by the given customer. |
| integer | Total |
| integer | Total |
referredFriend Object
Parameter | Type | Description |
---|---|---|
| string | Unique identifier for the customer at Gameball. |
| string | Customer's display name. |
| string | Customer's email. |
| string | Customer's mobile number. |
| DateTime | The date at which the customer joined the store. |
| string | Indicates the status of the referred customer, the value of the string can be one of the following:
|
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 |
| string | Yes | Client API key |
Query Parameters
Attribute | Type | Required | Description |
| integer | No | Index of required page. (e.g. 1, 2, ..) Default: 1 |
| integer | No | limit of results per page. (e.g. 10, 20, ..) Default: 50 Max: 200 |
Response
Attribute | Type | Description |
| array | An array of referredFriend objects. |
| integer | Count of customers in current page. |
| integer | Total number of customers referred by the given customer. |
referredFriend Object
Parameter | Type | Description |
---|---|---|
| string | Unique identifier for the customer at Gameball. |
| string | Customer's display name. |
| string | Customer's email. |
| string | Customer's mobile number. |
| DateTime | The date at which the customer joined the store. |
| string | Indicates the status of the referred customer, the value of the string can be one of the following:
|
| object | A referredBy object |
referredBy Object
Attribute | Type | Description |
| string | Unique identifier for the customer at Gameball. |
| string | Customer's display name. |
| string | Customer's email. |
| 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 |
| string | Yes | Client API key |
Path Parameters
Attribute | Type | Required | Description |
| string | Yes | Unique identifier for the customer at Gameball. |
Body
Attribute | Type | Required | Description |
| 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 |
| string | Yes | Client API key |
Path Parameters
Attribute | Required | Type | Description |
---|---|---|---|
| Yes | string | Unique identifier for the customer at Gameball. |
Body
Attribute | Type | Required | Description |
| 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”.