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	Create Customer	/integrations/player
GET	Retrieve Customer	/integrations/player/{playerUnqiueId}
GET	Retrieve Customer's Balance	/integrations/player/{playerUnqiueIdl}/balance
GET	Retrieve Customer's Hash	/integrations/player/{playerUnqiueId} /hash
GET	Retrieve Customer's Progress 👑	/integrations/player/{playerUnqiueIdl}/progress
DELETE	Delete Customer	/integrations/player/{playerUnqiueId}
GET	Rewards Campaign's Progress	/integrations/player/{playerUnqiueIdl}/progress/challenge/{handle}
GET	Customer's Coupons	/integrations/transactions/{playerUniqueId}/coupon
GET	Get Customer's Referrals	/integrations/players/{playerUniqueId}/referrals
GET	Get All Customer's Referrals	/integrations/players/referrals
POST	Attach Tags	/integrations/player/{playerUnqiueId}/tags
DELETE	Detach Tags	/integrations/player/{playerUnqiueId}/tags

POST - Create Customer

https://api.gameball.co/api/v3.0/integrations/player

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	An object with set of properties that you want to set for the customer. This object also includes a customobject inside for custom attributes.
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")

playerAttributes Object

Parameter	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}

{
   "playerUniqueId":"player123",
   "mobile": "+1234567", // optional (Channel Merging)
   "email": "[e-mail]", // optional (Channel Merging)
   "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
       "country": "Egypt",
        "city": "Cairo",
        "zip": "18754",
      "tags": "VIP,Platinum",
      "custom":{
          "location":"Miami",
          "graduationDate":"2018-07-04T21:06:29.158Z",
          "isMarried":false
      }
    },
    "referrerCode": null,
    "levelOrder": null
  }

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	VIP tier object holds information about the customer's current VIP tier at Gameball.
balance	object	An object that contains all the information about the customer's balance.
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

{
    "playerUniqueId": "player123",
    "gameballId": 160281869,
    "levelsProgress": 0,
    "level": {
        "id": 17812,
        "name": "very Basic ",
        "description": "",
        "levelStartScore": 0,
        "levelOrder": 1,
        "iconPath": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.png",
        "benefits": {
            "scoreEnteryReward": 0,
            "pointsEnteryReward": 0,
            "levelDiscount": null,
            "discountCapping": null
        }
    },
    "balance": {
        "pointsBalance": 0,
        "pointsValue": 0.0,
        "pendingPoints": 0,
        "pendingPointsValue": 0.0,
        "currency": "USD",
        "walletPointsName": "Points",
        "totalPositivePoints": 0,
        "totalPositivePendingPoints": 0,
        "totalNegativePoints": 0,
        "totalNegativePendingPoints": 0
    },
    "referralCode": "QQAF9B02734oKn",
    "referralLink": "https://wizardtest123.myshopify.com/account/register?ReferralCode=QQAF9B02734oKn",
    "dynamicReferralLink": null
}

Usage Examples

Example One

This example creates a new customer at Gameball, using playerUniqueId, playerAttributes with custom attributes.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
  "playerUniqueId":"player123",
  "mobile": "+1234567",
  "email": "[e-mail]",
  "playerAttributes":{
      "displayName":"Jon Snow",
      "firstName": "Jon",
      "lastName": "Snow",
      "mobile": "+1234567",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1980-09-19T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "country": "Egypt",
        "city": "Cairo",
        "zip": "18754",
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
      }
   }

  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'

Ruby

Gameball::Player.initialize_player({
   playerUniqueId:"player123",
   mobile: "+1234567",
   email: "[e-mail]",
   "playerAttributes":{
      displayName:"Jon Snow",
      firstName: "Jon",
      lastName: "Snow",
      mobile: "+1234567",
      email:"[e-mail]",
      gender:"M",
      dateOfBirth:DateTime.iso8601("1980-09-19T00:00:00.000Z"),
      joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
      country: "Egypt",
        city: "Cairo",
        zip: "18754",
      tags: "VIP,Platinum",
    	custom:{
           location:"Miami",
           graduationDate:"2018-07-04T21:06:29.158Z",
           isMarried:false
        }
    }
  })

PHP

$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Jon Snow";
$playerAttributes->firstName = 'Jon';
$playerAttributes->lastName = 'snow';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[e-mail]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->country= 'Egypt';
$playerAttributes->city= 'Cairo';
$playerAttributes->zip= '18754';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');

$playerRequest = \Gameball\Models\PlayerRequest::factory(
        "player123",
        null, // Mobile (not null according to your channel merging config)
        null, // Email (not null according to your channel merging config)
        $playerAttributes
);

$playerResponse = $gameball->player->initializePlayer($playerRequest);

Python

import gameball
gameball.api_key = "API_KEY"
gameball.transaction_key = "TRANSACTION_KEY"

# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "[e-mail]",
        "M",
        "1980-09-19T00:00:00.000Z",
        "2019-09-19T21:06:29.158Z",
        "Egypt",
        "Cairo",
        "18754",
        tags="VIP,Platinum",
        custom={
            'location':"Miami",
            'graduationDate':"2018-07-04T21:06:29.158Z",
            'isMarried':False
        }
    )
)
player_response = gameball.initialize_player(player_request)

.NET

using Gameball;
var Gameball = new Gameball.Gameball(apiKey: "API_KEY", secretKey: "SECRET_KEY");

var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "[e-mail]",
			Gender = "M",
			Mobile = "+1234567",
			DateOfBirth = new DateTime(1980, 9, 19),
			JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158),
			Country:"Egypt",
			City:"Cairo",
			Zip:"18754"
		}
	};
var response = Gameball.InitializePlayer(request);

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.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "referrerCode":"CODE11",
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":" Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"[e-mail]",
      "gender":"M",
      "dateOfBirth":"1978-01-11T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
  	}
   }
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player'

Ruby

Gameball::Player.initialize_player({
   referrerCode:"CODE11",
   playerUniqueId:"player456",
   playerAttributes:{
      displayName:" Tyrion Lannister",
      firstName:"Tyrion",
      lastName:"Lannister",
      email:"[e-mail]",
      gender:"M",
      dateOfBirth:DateTime.iso8601("1978-01-11T00:00:00.000Z"),
      joinDate:DateTime.iso8601("2019-09-19T21:06:29.158Z"),
      custom:{
         location:"Miami",
         graduationDate:"2018-07-04T21:06:29.158Z",
         isMarried:false
  	}
   })

PHP

$playerAttributes = new \Gameball\Models\PlayerAttributes();
$playerAttributes->displayName = "Tyrion Lannister";
$playerAttributes->firstName = 'Tyrion';
$playerAttributes->lastName = 'Lannister';
$playerAttributes->gender = 'M';
$playerAttributes->email = '[e-mail]';
$playerAttributes->dateOfBirth = '1978-01-11T00:00:00.000Z';
$playerAttributes->joinDate = '2021-09-19T21:06:29.158Z';
$playerAttributes->addCustomAttribute('isMarried' , true);
$playerAttributes->addCustomAttribute('location' , 'Miami');
$playerAttributes->addCustomAttribute('graduationDate' , '2018-07-04T21:06:29.158Z');

$playerRequest = \Gameball\Models\PlayerRequest::factory(
        "player456",
        null, // Mobile (not null according to your channel merging config)
        null, // Email (not null according to your channel merging config)
        $playerAttributes,
        "CODE11" // ReferrerCode
);

$playerResponse = $gameball->player->initializePlayer($playerRequest);

Python

# Initialize Player
player_request = gameball.playerObject("player123", 
    player_attributes = gameball.playerAttributes(
        "Jon Snow",
        "Jon",
        "Snow",
        "+1234567",
        "[e-mail]",
        "M",
        "1980-09-19T00:00:00.000Z",
        "2019-09-19T21:06:29.158Z",
        tags="VIP,Platinum",
        custom={
            'location':"Miami",
            'graduationDate':"2018-07-04T21:06:29.158Z",
            'isMarried':False
        }    
    ),
    referrer_code="CODE11"
)
player_response = gameball.initialize_player(player_request)

.NET

var request = new PlayerRequest()
	{
		PlayerUniqueId = "player123",
		PlayerAttributes = new PlayerAttributes()
		{
			DisplayName = "Jon Snow",
			FirstName = "Jon",
			LastName = "Snow",
			Email = "[e-mail]",
			Gender = "M",
			Mobile = "+1234567",
			DateOfBirth = new DateTime(1980, 9, 19),
			JoinDate = new DateTime(2019, 9, 19, 21, 6, 29, 158)
		},
		ReferrerCode = "CODE11"
	};
var response = Gameball.InitializePlayer(request);

GET - Retrieve Customer

This API call is used to retrieve customer's information.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}

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	An object with set of customer properties defined previously at the customer's creation.
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	Level object holds information about the customer's current VIP tier at Gameball.
levelsProgress	int	The current progress of the customer on the VIP tier.
points	object	The current balance of the customer.

Level Object

The 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

{
   "playerUniqueId":"player456",
   "playerAttributes":{
      "displayName":"Jon Snow",
      "email":"[e-mail]",
      "mobileNumber":"0123456789",
      "gender":"M",
      "joinDate":"09/19/2019 21:06:29",
      "tags":[
         "VIP",
         "Elite"
      ],
      "custom":{
         "location":"Miami",
         "graduationDate":"2018-07-04T21:06:29.158Z",
         "isMarried":false
      }
   },
   "referralCode":"CODE12",
   "referralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
   "dynamicReferralLink":"https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
   "level":{
      "name":"Gold",
      "description":null,
      "levelOrder":4,
      "iconPath":"https://cdn.gameball.co/uploads/Client 1/[e-mail]",
      "benefits":{
         "scoreEntryReward":0,
         "pointsEntryReward":0,
         "levelDiscount":null,
         "discountCapping":null
      }
   },
    "levelProgress": 0,
    "points": {
        "pointsBalance": 0,
        "pointsValue": 0.0,
        "pendingPoints": 0,
        "pendingPointsValue": 0.0,
        "currency": "USD",
        "walletPointsName": "Points",
        "totalPositivePoints": 0,
        "totalPositivePendingPoints": 0,
        "totalNegativePoints": 0,
        "totalNegativePendingPoints": 0
    }
}

Usage Example

The example shown is a request sent to Gameball to get a customer info with playerUniqueId“player456”.

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'

Ruby

Gameball::Player.get_player_info("player456")

PHP

$playerResponse = $gameball->player->getPlayerInfo("player456");

Python

player_response = gameball.get_player_info("player456")

.NET

var response = Gameball.GetPlayerInfo(“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.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/balance

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
pointsBalance	integer	Customer current points balance.
pointsValue	integer	The customer's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	integer	The customer's equivalent monetary value to pendingPoints according to your Cashback program configurations.
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

{
    "pointsBalance": 11500,
    "pointsValue": 115,
    "pendingPoints": 200,
    "pendingPointsValue": 2,
    "totalPositivePoints": 12500,
    "totalPositivePendingPoints": 135,
    "totalNegativePoints": 1000,
    "totalNegativePendingPoints": 20
    "currency": "USD",
    "pointsName": "Points"
}

Usage Example

The example shown is a request sent to Gameball to get a customer's balance with his playerUniqueId

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'

Ruby

Gameball::Player.get_player_balance("player456")

PHP

$playerResponse = $gameball->player->getPlayerBalance("player456");

Python

player_response = gameball.get_player_balance("player456")

.NET

var response = Gameball.GetPlayerBalance(“player456”);

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.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/hash

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	The customer's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	number	The customer's equivalent monetary value to pendingPoints according to your Cashback program configurations.
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

   {
    "pLayerId": 406044,
    "playerUniqueId": "6886288195890",
    "displayName": "m3 z3",
    "firstName": "m3",
    "lastName": "z3",
    "gender": null,
    "email": "[e-mail]",
    "mobileNumber": null,
    "dateOfBirth": null,
    "joinDate": "2023-03-01T10:28:30",
    "referralCode": "ED1D58A3vTiok9",
    "referralLink": "https://gbdashboardv2-gbx.myshopify.com/account/register?ReferralCode=ED1D58A3vTiok9",
    "dynamicReferralLink": null,
    "levelName": "Basico",
    "levelIconPath": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.png",
    "pointsBalance": 945,
    "pointsValue": 94.5,
    "pendingPoints": 0,
    "pendingPointsValue": 0,
    "pointsToExpire": 555,
    "pointsToExpireValue": 55.5,
    "expiryDate": "2023-03-02T12:23:59.885053",
    "currency": "AED",
    "pointsName": "Puntos",
    "lastActivePointsStatus": 555,
    "lastPendingPointsStatus": 0,
    "lastLevelStatus": "none",
    "lastActivePointsDate": "2023-03-01T12:23:59.913354",
    "lastPendingPointsDate": null,
    "lastLevelDate": null,
    "hash": "502371"
  }

Usage Example

The example shown is a request sent to Gameball to get a customer's balance with his playerUniqueId

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' 
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'

Ruby

Gameball::Player.get_player_balance("player456")

PHP

$playerResponse = $gameball->player->getPlayerBalance("player456");

Python

player_response = gameball.get_player_balance("player456")

.NET

var response = Gameball.GetPlayerBalance(“player456”);

GET - Customer's Progress 👑

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/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	An object with set of customer properties.
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	An array of rewards campaigns objects where each describe an available rewards campaigns for the customer and his progress in each.
totalReferredPlayers	integer	The total number of the customer's referred customers.
balance	object	An object that describes the customer's current balance.

balanceObject

The balance object contains info about the customer's points.

Parameter	Type	Description
pointsBalance	integer	Customer current points balance.
pointsValue	number	The customer's equivalent monetary value topointsBalance according to your Cashback program configurations.
pendingPoints	integer	Customer current pending points. (Not active yet, therefore cannot be used at this moment)
pendingPointsValue	number	The customer's equivalent monetary value to pendingPoints according to your Cashback program configurations.
currency	string	Your system currency as configured at Gameball.
pointsName	string	The naming of the rewarding points that appears to the customer.

challenge Object

The 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	AchallengeConfigObject that describes the details of the rewards campaign.

challengeConfig Object

Attribute	Type	Description
id	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	An array of Reward objects, these are the rewards that are achieved by completing the specified Rewards Campaign.
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	An availability object specifying the conditions where this rewards campaignis available.
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

Attribute	Type	Description
rankReward	integer	Progress rewarded towards rank.
walletReward	integer	Points rewarded in wallet.
couponReward	Object	Coupon object that describes the coupon that is rewarded when completing this rewards campaign.

couponReward Object

Attribute	Type	Description
couponType	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

Attribute	Type	Description
minLevel	integer	Minimum VIP tier where this rewards campaign is available.
tags	array	An array of Tag names. (string)

Sample Response

{
  "playerUniqueId": "player456",
  "referralCode": "CODE12",
  "referralLink": "https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
  "dynamicReferralLink": "https://gameofthrones.myshopify.com/account/register?ReferralCode=CODE12",
  "playerAttributes": {
    "dateOfBirth": null,
    "communityId": null,
    "tags": ["VIP"]
  },
  "levelsProgress": {
    "current": {
      "order": 1,
      "name": "level 1",
      "minProgress": 0,
      "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
    },
    "next": {
      "order": 2,
      "name": "level 2",
      "minProgress": 2000,
      "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb.png"
    }
  },
  "challengesProgress": [
    {
      "isUnlocked": true,
      "highScoreAmount": null,
      "completionPercentage": 0,
      "achievedCount": 0,
      "challengeConfig": {
        "id": 1234,
        "name": "Challenge Name",
        "description": "Challenge Description",
        "rewards": [
          {
            "rankReward": 0,
            "walletReward": 0,
            "couponReward": {
              "couponType": "Free Product",
              "discountValue": null,
              "minOrderValue": null,
              "product": {
                "productId": "123456789",
                "productName": "Chequered Red Shirt",
                "variantId": "123456789",
                "variantName": null
              },
              "collections": []
            }
          }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "EventBased",
        "visibility": "Always Visible",
        "icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
        "availability": {
          "minLevel": 1,
          "tags": []
        },
        "redirectionButtonText": "Free Gift",
        "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
      }
    }
  ],
  "totalReferredPlayers": 0,
  "points": {
    "pointsBalance": 11500,
    "pointsValue": 115,
    "pendingPoints": 200,
    "pendingPointsValue": 2,
    "currency": "USD",
    "pointsName": "Points"
  }
}

Usage Example

The example shown is a request sent to Gameball to get a customer's progress with playerUniqueId“player456”.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/progress'

Ruby

Gameball::Player.get_player_progress("player456")

PHP

$playerResponse = $gameball->player->getPlayerProgress("player456");

Python

player_response = gameball.get_player_progress("player456")

.NET

var response = Gameball.GetPlayerProgress(“player456”);

GET - Customer's Rewards Campaign's Progress

This API is used to get a customer's specific rewards campaign's progress.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/progress/challenge/{handle}

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	A single object array of ChallengesProgress object.

challengesProgress Object

Attribute	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	AchallengeConfigObject that describes the details of the rewards campaign.

Sample Response

{
  "challengesProgress": [
    {
      "isUnlocked": true,
      "highScoreAmount": null,
      "highScore": null,
      "completionPercentage": 50.0,
      "achievedCount": 0,
      "currentStreak": null,
      "highestStreak": null,
      "challengeConfig": {
        "id": 1234,
        "name": "Challenge Name",
        "description": "Challenge Description",
        "rewards": [
          {
            "rankReward": 0,
            "walletReward": 0,
            "couponReward": {
              "couponType": "Free Product",
              "discountValue": null,
              "minOrderValue": null,
              "product": {
                "productId": "123456789",
                "productName": "Chequered Red Shirt",
                "variantId": "123456789",
                "variantName": null
              },
              "collections": []
            }
          }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "EventBased",
        "visibility": "Always Visible",
        "icon": "https://s3.us-east-2.amazonaws.com/gameball.dev.uploads/uploads/gb-library/general/annoncement.png",
        "availability": {
          "minLevel": 1,
          "tags": []
        },
        "redirectionButtonText": "Free Gift",
        "redirectionButtonLink": "https://claires.myshopify.com/products/jeans"
      }
    }
  ]
}

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”

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/progress/challenge/New%20customer'

Ruby

Gameball::Player.get_player_challenge_progress("player456","New Customer")

PHP

/$playerResponse = $gameball->player->getPlayerChallengeProgress("player456","New Customer");

Python

player_response = gameball.get_player_challenge_progress("player456","New Customer")

.NET

var response = Gameball.GetPlayerChallengeProgress(“player456”,"New Customer");

DELETE - Delete Customer

This API is used to delete a customer along with his attributes, transactions, achievements and actions.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}

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

cURL

curl -X DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456'

Ruby

Gameball::Player.delete("player456")

PHP

$playerResponse = $gameball->player->delete("player456");

Python

player_response = gameball.deletePlayer("player456")

.NET

var response = Gameball.DeletePlayer(“player456”);

GET - Customer's Coupons

https://api.gameball.co/api/v3.0/integrations/transactions/{playerUniqueId}/coupon

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	An array of Coupon objects.

coupon Object

Parameter	Type	Description
code	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	In the case of free_product coupon, a product object indicates the details of the free product.
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	An object describing the coupon group which the coupon belongs to.
options	object	An object describing the coupon's options.

product Object

Parameter	Type	Description
productId	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

Type		Description
collectionId	integer	Unique identifier of the collection.
collectionName	string	Name of the collection.

group Object

Parameter	Type	Description
handle	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).

optionsObject

Parameter	Type	Description
ExpiryAfter	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

[
    {
        "code": "R7KVWwoT4c",
        "isUsed": false,
        "value": 30.0,
        "currency": "EGP",
        "creationDate": "2022-09-21T11:08:42.298758",
        "couponType": "custom",
        "product": {
            "productId": null,
            "productName": null,
            "productDisplayName": null,
            "variantId": null,
            "variantName": null
        },
        "startAt": "2021-09-21T11:08:42.298758",
        "endAt": "2023-09-21T11:08:42.298758",
        "isExpired": false,
        "collections": [],
        "group": {
            "handle": "free_macdo",
            "title": "Free MACDO",
            "url": "https://www.mcdonalds.eg/eat/menu/Item/Chicken-MACDO-",
            "iconPath": "https://www.mcdonalds.eg/Cms_Data/Contents/En/Media/images/Menu/large-Image/Chicken-MACDO.png",
            "description": "Coupons in this group give a free macdo and can be rdeemed in all Mcdonalds branches"
        }
    },
    {
        "code": "zFHYySXdiy",
        "isUsed": false,
        "value": 50.0,
        "currency": "EGP",
        "creationDate": "2022-09-21T11:07:22.718595",
        "couponType": "percentage_discount",
        "product": {
            "productId": null,
            "productName": null,
            "productDisplayName": null,
            "variantId": null,
            "variantName": null
        },
        "startAt": null,
        "endAt": null,
        "isExpired": false,
        "collections": [],
        "group": null
    },
    
]

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/coupon'

Ruby

Gameball::Player.get_player_coupon("player456")

PHP

$playerResponse = $gameball->player->getPlayerCoupon("player456");

Python

player_response = gameball.get_player_coupon("player456")

.NET

var response = Gameball.GetPlayerCoupon(“player456”);

GET - Customer's Referrals

https://api.gameball.co/api/v3.0/integrations/players/{playerUniqueId}/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	An array of referredFriend objects.
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

Parameter	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.
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

{
   "referredFriends":[
      {
         "displayName":"Jon Snow",
         "email":"[e-mail]",
         "mobileNumber":"0123456789",
         "joinDate":"09/19/2019 21:06:29",
         "status":"Pending",
         "playerUniqueId":"123"
      },
      {
         "displayName":"Arya Stark",
         "email":"[e-mail]",
         "mobileNumber":"0111111119",
         "joinDate":"09/19/2018 22:16:25",
         "status":"Active",
         "playerUniqueId":"123"
      }
   ],
   "total":2,
   "count":2,
   "totalPending":1,
   "totalActive":1
}

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/players/player456/referrals'

Ruby

Gameball::Player.get_player_referrals("player456")

PHP

$playerResponse = $gameball->players->getPlayerReferrals("player456");

Python

player_response = gameball.get_player_referrals("player456")

.NET

var response = Gameball.GetPlayerReferrals(“player456”);

GET - Get all Customer's Referrals

https://api.gameball.co/api/v3.0/integrations/players/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	An array of referredFriend objects.
count	integer	Count of customers in current page.
total	integer	Total number of customers referred by the given customer.

referredFriend Object

Parameter	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.
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	A 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

{
    "referredFriends": [
        {
            "playerUniqueId": "7181703840036",
            "displayName": "referral1 referral1",
            "email": "[e-mail]",
            "mobileNumber": null,
            "joinDate": "0001-01-01T00:00:00",
            "status": "Pending",
            "referredBy": {
                "playerUniqueId": "7181695156516",
                "displayName": "test test",
                "email": "[e-mail]",
                "mobileNumber": null
            }
        },
        {
            "playerUniqueId": "7181952418084",
            "displayName": "adam referral",
            "email": "[e-mail]",
            "mobileNumber": null,
            "joinDate": "0001-01-01T00:00:00",
            "status": "Active",
            "referredBy": {
                "playerUniqueId": "7181703840036",
                "displayName": "referral1 referral1",
                "email": "[e-mail]",
                "mobileNumber": null
            }
        }
    ],
    "count": 2,
    "total": 2
}

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186'
 -v -i 'https://api.gameball.co/api/v3.0/integrations/players/referrals'

POST - Attach Tags to Customer

This API is used to attach tags to a Customer.

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/tags

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

{
   "tags":"VIP,Platinum"
}

Usage Example

The example shown is a request sent to Gameball to attach tags "VIP,Platinum" to a customer with playerUniqueId“player456”.

cURL

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d 
'{
   "tags":"VIP,Platinum"
 }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/tags'

Ruby

Gameball::Player.attach_tags("player456","VIP,Platinum")

PHP

$playerResponse = $gameball->player->attachTags("player456", "VIP,Platinum");

Python

player_response = gameball.attach_tags("player456","VIP,Platinum")

.NET

var response = Gameball.AttachTags(“player456”, "VIP,Platinum");

DELETE - Detach Tags

https://api.gameball.co/api/v3.0/integrations/player/{playerUnqiueId}/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

Attribute	Required	Type	Description
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

{
   "tags":"VIP"
}

Usage Example

The example shown is a request sent to Gameball to detach tags "VIP" from a customer with playerUniqueId“player456”.

cURL

curl -X DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "tags":"VIP"
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/tags'

Ruby

Gameball::Player.detach_tags("player456","VIP,Platinum")

PHP

$playerResponse = $gameball->player->detachTags("player456", "VIP");

Python

player_response = gameball.detach_tags("player456","VIP")

.NET

var response = Gameball.DetachTags(“player456”, "VIP");