Object Reference

This section provides a list of the objects dealt with using the available API endpoints.

Cashback Object

The cashback object is returned in the Configurations API response body. It describes the cashback program configurations.

Parameter

Type

Description

rewardFactor

number

In case you have different merchants (brands) on your platform, The rewardFactor defines the specific cashback percentage for the paid amount to be rewarded to your players.

Example: If you give 5% cashback (when the customer pays 100 USD, they will get 5 USD cashback). The rewardFactor would be 0.05

amountRewardThreshold

integer

Defines the amount of unit currencies needed to reward the player as per cashback rules. Example: For every 10 USD spent the player gets rewarded by 5 points, implies that the amountRewardThreshold is "10".

rewardWalletFactor

integer

Determines the points rewarded for each unit currency your player spends.

Example: 2 points for every 1 USD spent, implies that the rewardWalletFactor is "2"

rewardRankFactor

integer

In case your level up method is score, this factor determines the score rewarded for each unit currency your player spends.

Example: 2 Score for every 1 USD spent, implies that the rewardRankFactor is "2"

{
    "rewardFactor":0.3,
    "amountRewardThreshold":10,
    "rewardWalletFactor":3,
    "rewardRankFactor":1
}

Challenge Object

Represents the challenge object that describes a configured rewards campaign and tracks the relative customer's progress.

Parameter

Type

Description

id

integer

Unique identifier for the rewards campaign.

name

string

Rewards Campaign Name

description

string

Rewards Campaign Description

rankReward

integer

Awarded rank upon rewards campaign completion

walletReward

integer

Awarded points upon rewards campaign completion

repeatable

boolean

A flag that indicates whether the rewards campaign is repeatable or not.

maxAchievement

integer

An integer that defines how many times a customer can achieve that rewards campaign.

type

string

The type of the rewards campaign. Possible values are as follows: SignUp

SocialMedia

ScheduledChallenge

EventBased

HighScore

Birthday

Anniversary

visibility

string

Defines the visibility of the rewards campaign. Possible values are:

  • "AlwaysVisibile"

  • "NotVisible"

  • "VisibleIfEarned"

icon

string

The icon's URL of the rewards campaign.

availability

object

"availability":{

"minLevel": 4,

"tags": ["VIP"]

}

An object that describes rewards campaign availability to customers.

  • minLevel : Minimum required VIP tier for the customer to be eligible to the achieve the rewards campaign.

  • tags: Array of tags for which the rewards campaign is available.

{
   "id":3350,
   "name":"view product + tag internal",
   "description":"",
   "rankReward":3,
   "walletReward":10,
   "repeatable":true,
   "maxAchievement":0,
   "type":"EventBased",
   "visibility":"AlwaysVisible",
   "icon":"gb-icon-challenge-10@2x",
   "availability":{
      "minLevel":5,
      "tags":[
         "2nd tag"
      ]
   }
}

Event Object

The Event object is how you record any actions your users perform, along with any metadata that describe the action. For further elaboration on events check Understand your customers' events.‌

Event and Metadata example:

Event Name

Key

Value

buy

product_id

a123456

price

30

product_category

fashion

product_tags

men & new_collection

"buy": {
  "product_id": "a123456",
  "price": 30,
  "product_category": "fashion"
  "product_tags": ["men", "new_collection"]
}

The following example shows a collection of events

"events": {
    "buy": {
      "category": "Electronics",
      "amount": 300
    },
    "travel": {
      "destinations": ["Paris", "Cairo"],
      "tickets": 4,
      "season": "Winter"
    },
    "visit_branch": {}
}

Leaderboard object

Defines the customer rank and progress in the leaderboard based on the specified query parameters.

Parameter

Type

Description

displayName

string

Customer's display name.

playerUniqueId

string

Unique identifier for a customer at Gameball.

progress

integer

Customer's progress (based on the specified query parameters).

rank

integer

Customer's Rank (based on the specified query parameters).

levelName

string

VIP Tier Name.

Example: "Bronze"

levelIcon

string

VIP Tier's icon URL.

{
  "displayName": "Customer 1",
  "playerUniqueId": "5097238429738",
  "progress": 1748,
  "rank":1,
  "levelName": "Bronze",
  "levelIcon": "https://cdn.gameball.co/uploads/c007/e7e1580c-f1ae-48be-9e14-2635848c6817icon-level-bronze@2x.png"
}

Level Object

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

Parameters Description

Parameter

Type

Description

minProgress

integer

The required score to reach the VIP tier.

order

integer

VIP Tier Order

icon

string

icon URL of the VIP tier.

name

string

VIP Tier Name

benefits

object

"benefits":{

"rankReward":0,

"walletReward":0,

"levelDiscount":0,

"discountCapping":0,

"others":[]

}

The benefits object is defined as follows:

  • rankReward: Score rewarded upon reaching that VIP tier.

  • walletReward : Points rewarded upon reaching that VIP tier.

  • levelDiscount: The discount amount that the VIP tier grants.

  • discountCapping: The maximum value to which the discount is applicable. Example: 10% discount for maximum order price 100 USD

  • others: An array of statement(s) that can be used to describe the benefits of the VIP tier.

{
    "name": "Gold",
    "description": null,
    "levelStartScore": 7500,
    "levelOrder": 4,
    "iconPath": "https://cdn.gameball.co/uploads/Client 1/2cf4b388-f957-4789-8309-5476907c1baeicon-level-gold@2x.png",
    "benefits": {
        "scoreEnteryReward": 0,
        "pointsEnteryReward": 0,
        "levelDiscount": null,
        "discountCapping": null
    }
}

LineItems Object

Represent a Product in your system with its relative information, this object is used in the Orders API.

Attribute

Type

Description

productId

string

The ID of the product that the line item belongs to

sku

string

The item's SKU (stock keeping unit).

title

string

The title of the product.

category

array

Product category (fashion, electronics.. etc). It can be one category or multiple categories.

Example:["natural","cosmetics"]

collection

array

Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store.

Example:["14313","4343"]

tags

array

Tag(s) attached to the item in the order.

Example:["VIP", "Elite"]

weight

number

Item weight. Must be positive.

vendor

string

The name of the item's supplier.

Example:"nike"

{
  "productId":"197765",
  "tag": ["VIP"],
  "category": [
      "natural",
      "cosmetics"
   ],
   "weight": "20",
   "vendor": "nike",
   "collection": ["14313", "4343"]
}

Merchant Object

Holds information of merchant and its branch‌

Parameters Description

Parameter

Type

Description

uniqueId

string

Merchant unique id or code

name

string

Merchant name

branch

string

Optional branch information

branch.uniqueId

string

Branch unique id or code

branch.name

string

Branch name

"merchant": {
    "uniqueId": "string",
    "name": "string",
    "branch": {
      "uniqueId": "string",
      "name": "string"
    }
  }

Notification Object

Represents a notification that your customer receives.

Attribute

Type

Description

notificationId

string

Unique Identifier for a notification

title

string

Notification Title

body

string

Notification Body

isRead

boolean

Indicates whether the notification is read or not.

createdAt

string

Notification's creation date, as an ISO8601 timestamp.

Example: "2019-09-21T16:53:28.190Z"

lang

string

The language in which the notification is displayed. In case the lang is not provided in the request, defaultlang is returned.

Note: The language provided should be as per configured languages in your account.

Example: "en", "fr".

icon

string

Notification's icon URL.

{
   "notificationId" : "123",
   "title": "New level!",
   "body": "Keep it up! You are now on Bronze ",
   "isRead": true,
   "createdAt": "2021-05-12T00:08:09.646174",
   "lang": "en",
   "icon": "https://cdn.gameball.co/uploads/client776/ad8b2587-959f-48fd-ab58-a643323652begb-icon-level-13.png"
}

Score Object

Contains info about the customer's score.‌

Parameters Description

Parameter

Type

Description

scoreBalance

string

Customer Score

scoreName

string

The naming of the score points that appears to the customer.

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

PlayerAttributes Object

Contains all of the attributes describing your customer.‌

Parameters Description

Parameter

Type

Description

displayName

string

Customer's display name

firstName

string

Customer's first name

lastName

string

Customer's last name

gender

string

Customer's gender. Example: M or F, Male or Female.

email

string

Customer's email

mobile

string

Customer's mobile

dateOfBirth

string

Customer's date of birth

Example: "1980-09-19T00:00:00.000Z"

joinDate

string

Customer join date at your system.

Example: "2019-09-19T21:06:29.158Z"

tags

string

Comma separated string of tags to be attached to the customer .

Example: "VIP,Platinum"

community

string

Describe which community a customer belongs to.

custom

object

Key value pairs of any extra customer attributes.

{"class" : "E2022", "weight" : 78}

"playerAttributes": {
    "displayName":"Jon Snow",
    "firstName": "Jon",
    "lastName": "Snow",
    "email":"jon.snow@example.com",
    "mobile": "+1234567",
    "gender":"M",
    "dateOfBirth":"1980-09-19T00:00:00.000Z",
    "joinDate":"2019-09-19T21:06:29.158Z",
    "tags": "VIP,Platinum",
	  "custom":{
       "location":"Miami",
       "graduationDate":"2018-07-04T21:06:29.158Z",
       "isMarried":false
    }
}

Points Object

Contains information about the customer's points.‌

Parameters Description

Parameter

Type

Description

pointsBalance

number

Customer Points

pointsValue

number

The actual value equivalent to customer points.

currency

string

Store Currency

pointsName

string

The naming of the rewarding points that appears to the customer.

"points": {
        "pointsBalance": 11500,
        "pointsValue": 115,
        "currency": "USD",
        "pointsName": "Points"
    }

Referral Object

The referral object is returned in the configurations API response body. It describes the referral program configurations.

Parameter

Type

Description

referralMethod

string

Defines how the referral program rewards your customers, Possible values:

  • "PlayerAndFriend" denotes that both the referring and the referred customer should be rewarded. The referred customer also should complete the sign up process and perform a certain action according to your configurations.

  • "PlayerOnly" denotes that only the referring customer that should be rewarded after a successful referral.

  • "PlayerAndGuest" denotes that both the referring and the referred customer should be rewarded. Referred Customer Registration is optional, but he would be rewarded after placing a successful order.

eventName

string

The name of the event which is linked to the referral action

eventMetaData

string

The event metadata which value should be monitored and checked for completing the referral.

playerReward

object

"playerReward":{

"extraReward":{

"rewardEvery":5,

"rewardType":null,

"score":2,

"point":1,

"voucher":null

},

"rewardType":"Vouchers",

"score":0,

"point":0,

"voucher":{

"voucherType":"Free Shipping",

"productId":"",

"productName":"",

"value":0

}

}

An object that defines the referring customer's reward.

The playerReward object is defined as follows:

  • extraReward: An object that defines the extra reward the referring player is granted after completing specific number of referrals. "extraReward":{

    "rewardEvery":5,

    "rewardType":null,

    "score":2,

    "point":1,

    "voucher":null

    }

    • rewardEvery:Defines the frequency upon which the referring customer is rewarded

    • rewardType : Defines the type of the reward, possible values are:

      • "Vouchers"

      • "Score&Points"

    • score: Score rewarded as an extra reward.

    • points: Points rewarded as an extra reward.

    • voucher: An object that defines the rewarded voucher.

    "voucher": {

    "voucherType":"Free Product",

    "productId":"6161866621123",

    "productName":"Antique Drawers",

    "value":250

    }

  • rewardEvery:Defines the frequency upon which the referring customer is rewarded

  • rewardType : Defines the type of the reward, possible values are:

    • "Vouchers"

    • "Score&Points"

  • score: Score rewarded as an extra reward.

  • points: Points rewarded as an extra reward.

  • voucher: An object that defines the rewarded voucher.

friendReward

object

Defines the referred customer reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred customer should also be rewarded.

The object is the same as the playerReward object excluding the extraReward.

{
   "referralMethod":"PlayerAndFriend",
   "eventName":"",
   "eventMetaData":null,
   "playerReward":{
      "extraReward":{
         "rewardEvery":5,
         "rewardType":null,
         "score":2,
         "point":1,
         "voucher":null
      },
      "rewardType":"Vouchers",
      "score":0,
      "point":0,
      "voucher":{
         "voucherType":"Free Shipping",
         "productId":"",
         "productName":"",
         "value":0
      }
   },
   "friendReward":{
      "rewardType":"Vouchers",
      "score":0,
      "point":0,
      "voucher":{
         "voucherType":"Free Product",
         "productId":"6161866621123",
         "productName":"Antique Drawers",
         "value":250
      }
   }
}

Transaction object

Describes any transaction made in your system.

Attribute

Type

Description

transactionId

string

Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.

gameballTrasnactionId

integer

Transaction ID on Gameball system.

type

string

Transaction type string. Can be one of the following:

AchievementReward

PaymentReward

Refund

Redemption

Expiry

Cancel

Migration

ManualAccumulation

DiscountCode

ManualDeduction

ManualReward

direction

string

Either "+" or "-" indicating transaction was an addition or deduction

playerUniqueId

string

Customer unique identifier used to uniquely identify the customer on Gameball.

points

integer

Number of points involved in the transaction

amount

number

Monetary amount involved in the transaction

transactionTime

string

Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.

Note: transactionTime is automatically handled when using server-side SDKs.

Example: "2019-09-19T16:14:09.895Z"

merchantName

string

Merchant name for transaction

branchName

string

Branch Name for transaction

{
  "transactionId":"trx123",
  "gameballTransactionId":"gbtrx123",
  "transactionTime":"2019-09-21T16:53:28.190Z",
  "type":"Cash Back",
  "direction":"+",
  "playerUniqueId":"1234",
  "points":500,
  "amount":10,
  "merchantName":"merchant",
  "branchName":"branch"
}

Last updated