Parameter

Type

Description

rewardFactor

number

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

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

amountRewardThreshold

integer

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

rewardWalletFactor

integer

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

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

rewardRankFactor

integer

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

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

Parameter

Type

Description

id

integer

Unique identifier for the challenge.

name

string

Challenge Name

description

string

Challenge Description

rankReward

integer

Awarded rank upon challenge completion

walletReward

integer

Awarded points upon challenge completion

repeatable

boolean

A flag that indicates whether the challenge is repeatable or not.

maxAchievement

integer

An integer that defines how many times a player can achieve that challenge.

type

string

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

SocialMedia

ScheduledChallenge

EventBased

HighScore

Birthday

Anniversary

visibility

string

Defines the visibility of the challenge. Possible values are:

• "AlwaysVisibile"

• "NotVisible"

• "VisibleIfEarned"

icon

string

The icon's URL of the challenge.

availability

object

"availability":{

"minLevel": 4,

"tags": ["VIP"]

}

An object that describes challenge availability to players.

• minLevel : Minimum required level for the player to be eligible to the achieve the challenge.

• tags: Array of tags for which the challenge is available.

Event Name

Key

Value

buy

product_id

a123456

​

price

30

​

product_category

fashion

​

product_tags

men & new_collection

Parameter

Type

Description

displayName

string

Player's display name.

playerUniqueId

string

Unique identifier for a player at Gameball.

progress

integer

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

rank

integer

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

levelName

string

Level Name.

Example: "Bronze"

levelIcon

string

Level's icon URL.

Parameter

Type

Description

minProgress

integer

The required score to reach the level.

order

integer

Level Order

icon

string

icon URL of the level.

name

string

Level 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 level.

• walletReward : Points rewarded upon reaching that level.

• levelDiscount: The discount amount that the level 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 level.

Attribute

Type

Description

productId

string

The ID of the product that the line item belongs to

sku

string

The item's SKU (stock keeping unit).

title

string

The title of the product.

category

array

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

Example:["natural","cosmetics"]

collection

array

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

Example:["14313","4343"]

tags

array

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

Example:["VIP", "Elite"]

weight

number

Item weight. Must be positive.

vendor

string

The name of the item's supplier.

Example:"nike"

Parameter

Type

Description

uniqueId

string

Merchant unique id or code

name

string

Merchant name

branch

string

Optional branch information

branch.uniqueId

string

Branch unique id or code

branch.name

string

Branch name

Attribute

Type

Description

notificationId

string

Unique Identifier for a notification

title

string

Notification Title

body

string

Notification Body

isRead

boolean

Indicates whether the notification is read or not.

createdAt

string

Notification's creation date, as an ISO8601 timestamp.

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

lang

string

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

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

Example: "en", "fr".

icon

string

Notification's icon URL.

Parameter

Type

Description

scoreBalance

string

Player Score

scoreName

string

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

Parameter

Type

Description

displayName

string

Player's display name

firstName

string

Player's first name

lastName

string

Player's last name

gender

string

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

email

string

Player's email

dateOfBirth

string

Player's date of birth

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

joinDate

string

Player join date at your system.

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

tags

string

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

Example: "VIP,Platinum"

community

string

Describe which community a player belongs to.

custom

object

Key value pairs of any extra player attributes.

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

Parameter

Type

Description

pointsBalance

number

Player Points

pointsValue

number

The actual value equivalent to player points.

currency

string

Store Currency

pointsName

string

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

Parameter

Type

Description

referralMethod

string

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

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

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

• "PlayerAndGuest" denotes that both the referring and the referred player should be rewarded. Referred Player 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 player'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 player 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 player 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 player reward configurations in case the referralMethod is "PlayerAndFriend" meaning that the referred player should also be rewarded.

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

Attribute

Type

Description

transactionId

string

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

gameballTrasnactionId

integer

Transaction ID on Gameball system.

type

string

Transaction type string. Can be one of the following:

AchievementReward

PaymentReward

Refund

Redemption

Expiry

Cancel

Migration

ManualAccumulation

DiscountCode

ManualDeduction

ManualReward

direction

string

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

playerUniqueId

string

Player unique identifier used to uniquely identify the player 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