Customer Progress
Retrieve customer progress across modules like tier, points, and referrals. Use these APIs to display customer progress within your app or system, offering insights into their journey.
Available APIs
GET - Customer Balance
https://api.gameball.co/api/v4/integrations/customers/{customerId}/balanceThis API retrieves a customer's current points balance within Gameball, including redeemable points and their monetary equivalent. It provides detailed balance information, such as total, available, and pending points, along with upcoming expirations.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
totalPointsBalance number
The total number of points the customer has, including pending points.
totalPointsValue number
The total monetary value of the customer's points, including pending points.
availablePointsBalance number
The number of points that are currently active and available for use (excludes pending points).
availablePointsValue number
The monetary value of the points that are currently active and available for use (excludes pending points).
pendingPoints number
The points earned by the customer that are temporarily on hold during the return window configured for your account. These points will remain in a pending status until the return period expires, ensuring that the points are not used or redeemed until it is confirmed that the transaction is final and not subject to returns or cancellations.
Example: If a customer places an order and earns 100 points, and your account is configured with a 14-day return window, these 100 points will remain pending for 14 days. During this time, the customer cannot use or redeem the points. After the 14-day window expires and the order is confirmed as final, the 100 points will become available for the customer to use.
pendingPointsValue number
The monetary value of the pending points.
currency string
The currency in which the points value is calculated.
pointsName string
The name of the points used in your loyalty program that appears to customers. This is the term your customers will see when they earn or redeem points.
Example: If your loyalty program rewards customers with "Stars" instead of generic "Points", the value of pointsName could be "Stars".
nextExpiringPointsAmount number
The amount of points that are set to expire next.Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.
nextExpiringPointsValue number
The monetary value of the points that are set to expire next.Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.
nextExpiringPointsDate string
The date when the next set of points will expire.Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.
totalEarnedPoints number
The total number of points that the customer has earned over their entire lifetime within the Gameball program. This includes all points accumulated from various activities like cashback rewards, referrals, or rewards campaigns.
Sample Response
{
"totalPointsBalance": 1500,
"totalPointsValue": 75.0,
"availablePointsBalance": 1200,
"availablePointsValue": 60.0,
"pendingPoints": 300,
"pendingPointsValue": 15.0,
"currency": "USD",
"pointsName": "Reward Points",
"nextExpiringPointsAmount": 200,
"nextExpiringPointsValue": 10.0,
"nextExpiringPointsDate": "2024-12-01T00:00:00",
"totalEarnedPoints": 2500
}GET - Customer Tier Progress
https://api.gameball.co/api/v4/integrations/customers/{customerId}/tier-progressThis API provides an overview of a customer’s current tier and progression within Gameball’s loyalty program. By retrieving the customer’s current tier, progress level, and next tier details, this endpoint offers a clear view of their advancement within the tier structure.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
current tierState Object
The customer's current tier.
next tierState Object
The next tier the customer can reach.
progress number
The current progress of the customer toward the next tier, reflecting their activity and engagement within the program. This value is calculated based on the client’s chosen tiering-up method, indicating how close the customer is to advancing to a higher tier.
Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier.
Possible Values:
Total amount spent
Total points earned
Friends referred
Orders completed
Score
Sample Response
{
"current": {
"order": 1,
"name": "Basic",
"minProgress": 0,
"icon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp"
},
"next": {
"order": 2,
"name": "Gold",
"minProgress": 190,
"icon": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads/gb-library/levels-icons/level-a1.webp"
},
"progress": 50
}GET - Customer Campaigns Progress
https://api.gameball.co/api/v4/integrations/customers/{customerId}/reward-campaigns-progressThis API retrieves a customer’s progress within Gameball’s reward campaigns, providing insights into their achievements and current status in each campaign. By accessing completion percentages and unlock statuses, you can track how customers are engaging with various reward opportunities.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
rewardsCampaignName string
The name of the rewards campaign.
rewardsCampaignId number
The unique ID of the rewards campaign.
isUnlocked boolean
Indicates if the customer has unlocked the campaign.
highScoreAmount number
The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign.
currentStreak number
The current number of consecutive days the customer has visited the website. This value is applicable only in the context of a streak (daily visit) rewards campaign.
highestStreak number
The maximum number of consecutive days the customer has visited the website. This value is also applicable only in the context of a streak (daily visit) rewards campaign.
completionPercentage number
The percentage of the campaign the customer has completed. For example, in a second-order campaign where the customer must make 2 orders, if they have only placed 1 order, the completion percentage will be 50%.
achievedCount number
The number of times the customer has achieved the campaign .
canAchieveboolean
A flag that determines whether the customer is currently eligible to participate in and achieve the this reward campaign. It provides a quick indication of the customer's ability to meet the campaign's conditions based on their current status.
rewardCampaignConfigurationobject
This object provides a comprehensive description of a reward campaign, including its identification details, activation criteria, visibility settings, and reward specifics. It outlines how the campaign operates, its eligibility requirements, and the type of rewards offered.
[
{
"rewardsCampaignName": "Third Order Campaign 🛍️",
"rewardsCampaignId": 5859,
"isUnlocked": true,
"highScoreAmount": null,
"currentStreak": null,
"highestStreak": null,
"completionPercentage": 33.0,
"achievedCount": 0,
"canAchieve":true,
"rewardCampaignConfiguration": {
"id": 5859,
"name": "Third Order 🛍️",
"description": "Complete your third order to earn some special rewards!",
"rewards": [
{
"rankReward": 0,
"walletReward": 0,
"walletRewardFactor": null,
"couponReward": null
}
],
"isRepeatable": false,
"maxAchievement": 1,
"type": "EventBased",
"visibility": "AlwaysVisible",
"icon": "https://cdn.gameball.co/uploads/gb-library/general/signup.webp",
"redirectionButtonText": "Check Your Rewards",
"redirectionButtonLink": "https://yourwebsite.co/rewards",
"activation": {
"startDate": "2024-09-01T00:00:00Z",
"endDate": "2024-12-31T23:59:59Z"
}
},
{
"rewardsCampaignName": "Birthday Reward 🎉",
"rewardsCampaignId": 5860,
"isUnlocked": true,
"highScoreAmount": null,
"currentStreak": null,
"highestStreak": null,
"completionPercentage": 100.0,
"achievedCount": 1,
"canAchieve":false,
"rewardCampaignConfiguration": {
"id": 5860,
"name": "Happy Birthday! 🎂",
"description": "It's your birthday and it's time to celebrate! This reward is a special gift on your special day 🥳",
"rewards": [
{
"rankReward": 0,
"walletReward": 0,
"walletRewardFactor": null,
"couponReward": {
"couponType": "Free Shipping"
}
}
],
"isRepeatable": false,
"maxAchievement": 1,
"type": "Birthday",
"visibility": "Always Visible",
"icon": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads/gb-library/general/birthday.png",
"redirectionButtonText": null,
"redirectionButtonLink": null,
"activation": null
}
}
]GET - Customer Referrals
https://api.gameball.co/api/v4/integrations/customers/{customerId}/referralsThis API retrieves a list of customers referred by a specified customer in Gameball, including each referral’s join date and current status within the referral program.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Query Parameters
startAfter long Optional
Specifies the page will start after which Gameball customer id. Defaults to 0.
limit integer Optional
Specifies the number of friends to return per page. Defaults to 50, with a maximum limit of 200 transactions per page.
Response
application/json
referredFriends array
A list of friends referred by the customer.
count number
The total number of friends on the current page.
hasMore boolean
Indicating whether there are additional friends to be fetched beyond the current page.
Sample Response
{
"referredFriends": [
{
"customerId": "cust_12345abc",
"displayName": "John Doe",
"email": "[email protected]",
"mobileNumber": "+11234567890",
"joinDate": "2023-05-01T00:00:00",
"status": "Pending"
},
{
"customerId": "cust_67890xyz",
"displayName": "Blake Eaton",
"email": "[email protected]",
"mobileNumber": "+11234567891",
"joinDate": "2023-06-15T00:00:00",
"status": "Active"
}
],
"count": 2,
"hasMore": true
}GET - Customer Referrals Count
https://api.gameball.co/api/v4/integrations/customers/{customerId}/referrals/countThis API retrieves the total count of customers referred by a specified customer in Gameball, providing the number of completed and pending referrals.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Response
application/json
count number
The total number of friends referred by the customer available in Gameball system.
totalPending number
The total number of referred friends who have joined but not yet completed the referral criteria in the Gameball system.
totalActive number
The total number of referred friends who have successfully completed the referral criteria in the Gameball system.
Sample Response
{
"count": 15,
"totalPending": 5,
"totalActive": 10,
}GET - Customer Activities
https://api.gameball.co/api/v4/integrations/customers/{customerId}/activitiesThis API retrieves a log of customer activities within Gameball, identified by customerId. The logs detail various actions, such as tier changes, campaign rewards, referrals, redemptions, and more. Specific activity types can be filtered, including events like TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing comprehensive visibility into each customer’s engagement history.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Query Parameters
startAfter long Optional
Specifies the page will start after which activity id. Defaults to 0.
limit integer Optional
Specifies the number of activities to return per page. Defaults to 50, with a maximum limit of 200 transactions per page.
activityType string Optional
Filters activities by a specific type, such as :
TierUpgraded: Indicates that the customer has been upgraded to a new tier.TierDowngraded: Indicates that the customer has been downgraded to a lower tier.TierMigration: Represents the migration of the customer's tier.CampaignRewarded: Signifies that the customer received a reward from a campaign.SuccessfulAction: Denotes successful progress by the customer in a campaign.Referral: Indicates that the customer referred a friend.Referred: The referee received a reward for being referred by the customer.ReferralBonusReward: Represents a bonus reward given for a referral.PaymentReward: Signifies that the customer received a cashback reward.Refund: Points were refunded back to the customer.Redemption: Points were redeemed by the customer.Cancel: A cashback transaction was canceled.Expiry: Indicates that points have expired.Migration: Represents a migration activity that occurred.Lifetime: Refers to activities related to lifetime coupons.Automation: Activity performed by an automation campaign.
Response
application/json
activities array
An array of activity records for the customer.
count number
The total number of activities on the current page.
hasMore boolean
Indicating whether there are additional logs to be fetched beyond the current page.
Sample Response
{
"activities": [
{
"activityId": 123456,
"activityType": "Cashback Rewarded",
"activityDay": "Friday",
"activityDate": "October 11, 2024",
"activityTime": "18:51:29",
"customerId": "cust_abc123",
"email": "[email protected]",
"transactionId": "TXN987654321",
"isManualActivity": false,
"points": 150,
"score": 0,
"calculatedRedemption": null,
"actualRedemption": null,
"rewardPoints": 150,
"currency": "USD",
"paymentRewardAmount": 15.00
}
],
"count": 1,
"hasMore": true
}GET - Customer Activities Count
https://api.gameball.co/api/v4/integrations/customers/{customerId}/activities/countThis API retrieves the total count of customer activities within Gameball, identified by customerId. It allows for filtering by specific activity types, such as TierUpgraded, CampaignRewarded, ReferralBonusReward, and PaymentReward, providing the number of activities matching the specified criteria without returning detailed activity logs.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Query Parameters
activityType string Optional
Filters activities by a specific type, such as :
TierUpgraded: Indicates that the customer has been upgraded to a new tier.TierDowngraded: Indicates that the customer has been downgraded to a lower tier.TierMigration: Represents the migration of the customer's tier.CampaignRewarded: Signifies that the customer received a reward from a campaign.SuccessfulAction: Denotes successful progress by the customer in a campaign.Referral: Indicates that the customer referred a friend.Referred: The referee received a reward for being referred by the customer.ReferralBonusReward: Represents a bonus reward given for a referral.PaymentReward: Signifies that the customer received a cashback reward.Refund: Points were refunded back to the customer.Redemption: Points were redeemed by the customer.Cancel: A cashback transaction was canceled.Expiry: Indicates that points have expired.Migration: Represents a migration activity that occurred.Lifetime: Refers to activities related to lifetime coupons.Automation: Activity performed by an automation campaign.
Response
application/json
count number
The total number of activities available in Gameball system.
Sample Response
{
"count": 240
}GET - Customer Automation Campaigns
https://api.gameball.co/api/v4/integrations/customers/{customerId}/automationThis API retrieves the available automation campaigns for the customer, identified by customerId. The response includes details of campaigns currently active and applicable to the customer, such as onboarding journeys, engagement triggers, or milestone-based campaigns. Specific campaign types can be filtered, including campaigns like Welcome Campaigns, Ramadan Campaign, and Custom Automations, offering a comprehensive view of personalized campaigns available for the customer.
Security: Requires apikey header.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
Query Parameters
campaignType string Optional
Filters automation steps by a specific type, such as
mission: return steps for mission-based campaigns. (default)all: return all automation steps and details.
Response
application/json
campaigns Array
A list of campaigns containing automation workflows.
campaigns.automation Array
A list of automation workflows within a campaign.
campaigns.automationCount number
Total number of automations available within this campaign.
count number
The total number of automation campaigns available in Gameball system.
Sample Response
{
"campaigns": [
{
"automation": [
{
"order": 1,
"name": "Level 1",
"isUnlocked": true,
"completed": false,
"steps": [
{
"type": "reward_badge",
"order": 1,
"completed": false,
"configuration": {
"name": "1st Order",
"description": "500 USD",
"icon": "http://cdn.gameball.co/uploads/gb-library/general/order-01.webp"
}
},
{
"type": "add_points",
"order": 2,
"completed": false,
"configuration": {
"points": "500"
}
}
],
"completionPercentage": 0
}
],
"automationCount": 1
}
],
"count": 1
}GET - Customer Action Streak Progress
https://api.gameball.co/api/v4/integrations/customers/{customerId}/action-streak/{challengeId}This API retrieves the progress of a specific customer within a particular Action Streak challenge in Gameball. It returns how many steps the customer has completed, how many times they’ve earned the challenge reward, and whether they are eligible to continue.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
customerId string Required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
challengeIdinteger Required
Unique identifier of the Action Streak challenge to retrieve progress for.
Response
application/json
Response Variables
numberOfCompletedSteps number
The number of steps completed by the customer in the current challenge cycle.
numberOfTimesEarned number
The total number of times the customer has successfully completed the challenge.
canAchieveAgain boolean
Indicates whether the customer is currently eligible to continue the challenge.
remainingTries number
The number of remaining allowed completions within the current time interval. A value of -1 means unlimited attempts.
challengeEndDate string
The end date of the challenge in the client’s local timezone.
rewardName string
The name of the reward as defined in the client’s configured language. Only included if the customer has received a reward from this campaign before.
couponName string
The name or value of the discount coupon assigned (if applicable). Only included if the customer has received a coupon for this campaign before.
Sample Response
{
"numberOfCompletedSteps": 3,
"numberOfTimesEarned": 1,
"canAchieveAgain": true,
"remainingTries": 2,
"challengeEndDate": "2025-06-01T23:59:59",
"rewardName": "10% Discount",
"couponName": "SAVE10"
}Last updated