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.

PreviousCustomer Management NextCustomer Tags

Last updated 8 days ago

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}/balance

This 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-progress

This 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

Response

application/json

current tierState Object The customer's current tier.

next tierState Object The next tier the customer can reach.

tierState object

order number This represents the numerical order of a tier. Higher numbers indicate higher tiers.

name string The name of the tier.

minProgress number

The minimum amount of progress a customer needs to reach the next tier in the program. This represents the threshold that must be met for a customer to reach this tier.

Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to advance to the next tier.

icon string The URL for the icon associated with the tier.You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles.This offers a visual representation of the customer's tier status.

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-progress

This 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

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.

rewardCampaignConfiguration object

id number Unique identifier for the reward campaign.

name string Name of the reward campaign.

description string A brief description of the reward campaign.

isRepeatable boolean Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer.

maxAchievement number Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true . If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available.

type string The type of the campaign. Possible values:

SignUp: Reward is given when a user signs up.
SocialMedia: Reward is linked to social media activity.
ScheduledChallenge: A time-based challenge that gives rewards.
Spin The Wheel: Rewards are given based on a spin-the-wheel game.
EventBased: Reward is given based on specific customer events.
HighScore: Reward is given based on achieving high scores in a campaign.
Birthday: Reward is given for birthday-related activity.

visibility string The visibility status of the campaign. Possible values:

AlwaysVisible: The campaign is always visible on the widget.
NotVisible: The campaign is not visible to the customer on the widget.
VisibleIfEarned: The campaign becomes visible once the customer earns it on the widget.

icon string The URL of the campaign’s icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform.

redirectionButtonText string

The text displayed on the redirection button within the reward campaign page on the widget. Example: "Claim Your Reward" would prompt customers to take action.Text for the redirection button.

redirectionButtonLink string

The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward redemption process. Example: "https://yourwebsite.com/rewards" directs customers to a page where they can view their rewards.

activation object Defines the activation criteria for the campaign, which may include specific start and end dates.

activation.startDate DateTime The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: "2024-11-01T00:00:00" indicates that the campaign starts on November 1, 2024.

activation.endDate DateTime? The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign . Example: "2024-11-30T23:59:59" indicates that the campaign ends on November 30, 2024, at 11:59 PM.

rewards array Details of the rewards that the customer will earn once achieving this reward campaign.

rewards.rankReward number The score rewarded for achieving this reward campaign.

rewards.walletReward number The number of points the customer will earn upon achieving this reward campaign.
Example:If you have set up a "First Order" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200.

rewards.walletRewardFactor number The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers.
Example: In a "Double Points" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign.

couponReward object

A coupon object that is awarded to the customer for this reward campaign.

couponReward.couponType string The type of coupon applied. Possible values include:
- free_shipping
- percentage_discount
- fixed_discount
- fixed_rate_discount
- free_product
- custom

couponReward.discountValue number The value of the discount provided by the coupon in case the coupon type is fixed_discount , percentage_discount or fixed_rate_discount.

couponReward.product.productId string The unique identifier for the product.

couponReward.product.productName string The name of the product.

couponReward.product.variantId string The unique identifier for the product variant.

couponReward.product.variantName string The name of the product variant.

coucouponRewardpon.product.productDisplayName string The display name associated with the product that configured on the dashboard based on required language.

couponReward.collections array A list of collection IDs that the coupon can be applied to.

couponReward.collections.collectionId string The unique identifier for the collection.

couponReward.collections.collectionName string The name for the collection.

couponReward.group.handle string A unique identifier used to reference the coupon group in the system.

couponReward.group.title string The title of the coupon group.

couponReward.group.url string The URL for the coupon group.

couponReward.group.iconPath string The path to the icon of the coupon group.

couponReward.group.description string A description of the coupon group.

couponReward.group.maxPerCustomer number The maximum number of times a customer can use the coupon.

Example: 5 indicates that each customer can redeem this coupon up to 5 times.

couponReward.group.startDate datetime The date when the coupons within this coupon group will become active and valid for redemption.

couponReward.group.expiryDate datetime The date when the coupons within this coupon group will expire and no longer be valid for redemption.

couponReward.group.isAvailable boolean Indicates whether the coupon group is currently available.

couponReward.group.isActive boolean Indicates whether the coupon group is currently active.

couponReward.options.name string The name of the reward rule configured on the dashboard based on required language.

couponReward.options.expiryAfter number The number of days after creation that the coupon will expire.
Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

couponReward.options.usageLimit number The maximum number of times a single coupon can be used.
Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

couponReward.options.capping number The maximum discount value a coupon can provide, regardless of the order amount.
Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

couponReward.options.minOrderValue number The minimum order amount required to apply the coupon.
Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

couponReward.options.codePrefix string TThe prefix that will be added to the beginning of the generated coupon code.
Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".

couponReward.options.redeemInstructions string The instructions on how the customer can redeem the coupon.
Example: "Enter the coupon code at checkout to apply the discount."

[
    {
        "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}/referrals

This 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

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.

referredFriends object

customerId string Unique identifier for the referred friend.

displayName string Display name of the referred friend.

email string Email address of the referred friend.

mobileNumber string Mobile number of the referred friend.

joinDate string The date when the referred friend joined.

status string The current status of the referral:

Active: The referral was successfully completed. The referred friend has completed the required action (e.g., placing an order), and the referral is counted for the customer.
Pending: The referred friend has used the customer’s referral link but has not yet completed the required action (e.g., signing up or making a purchase) for the referral to be considered complete.

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": "johndoe@company.com",
            "mobileNumber": "+11234567890",
            "joinDate": "2023-05-01T00:00:00",
            "status": "Pending"
        },
        {
            "customerId": "cust_67890xyz",
            "displayName": "Blake Eaton",
            "email": "blake@company.com",
            "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/count

This 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

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}/activities

This 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

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.

Activity object

Response Description

activityType string The type of activity that occurred (e.g., "Balance Adjustment", "Referral"). Available Activity Types:

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.
BalanceAdjustment: Indicates that points were either rewarded or deducted manually from the customer’s balance. This type of activity occurs when the customer’s points are adjusted manually.
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.

activityDay string The day of the week when the activity took place (e.g., "Sunday").

activityDate string The date of the activity (e.g., "October 20, 2024").

activityTime string The time when the activity occurred (e.g., "19:27:33").

customerId string The unique identifier of the customer associated with the activity.

email string The email address of the customer.

phoneNumber string The customer’s phone number.

displayName string The customer’s display name.

transactionId string A unique identifier for a transaction in your system (e.g., order number or invoice number). This ID can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.It represents the transaction ID related to this activity, if applicable, such as in cases of cashback rewards, points redemption, or balance adjustments.

isManualActivity boolean Indicates whether the activity was manually triggered (true) or not (false).

Example: This will be true if the activity is a BalanceAdjustment , when you manually decide to reward the customer with points.

points number The number of points involved in the activity, such as points earned, redeemed, or adjusted.

score number The score involved in the activity, applicable in reward campaigns where the customer earns score.

Example: If the customer participates in a campaign and earns 100 score points, the activity will include the score value.

reason string This is the reason manually entered for the activity, if provided. It is typically used when performing a manual activity, such as rewarding points or rewarding a manual reward campaign for a customer.

Example: If you manually reward a customer with 100 points for their birthday, you might enter "Birthday reward" as the reason.

calculatedRedemption number The estimated monetary value based on the redemption factor configured by the client and the points involved in this activity. It reflects the potential worth of the points, even if no actual redemption was made.

actualRedemption number The actual monetary value of the redemption, if applicable. This represents the redeemed amount when the activity type is points redemption.

familyRedemptionAmount number The redemption monetary value related to the customer's family wallet, if applicable.

familyRedemptionPoints number The redemption points related to the customer's family wallet, if applicable.

paymentRewardAmount number The amount rewarded in currency from the payment reward. This value reflects the cashback reward provided to the customer.

Example: If a customer receives a cashback reward of $10, the paymentRewardAmount will be 10.

outstandingPoints number The number of points currently available from the transaction related to this activity.

Example: If a customer earned 100 points from a transaction and 20 points have since expired, the outstandingPoints would be 80, representing the points still available for the customer to use.

rewardThreshold number This represents the minimum monetary amount (X value) a customer needs to spend to receive a specific number of reward points (Y points) as cashback reward, based on the configured points settings. It defines the threshold of spending required to earn points in your loyalty program.

Example:If rewardThreshold is set to 50.0, it means for every 50 currency units (e.g., 50 USD) spent by the customer, they will earn the configured number of reward points.

currency string The currency used in the transaction (e.g., "EGP").

redemptionRewardFactor number The factor used to calculate how many points are required for a redemption. This value determines the conversion rate between points and monetary value during a redemption process.

Example: If the redemptionRewardFactor is 0.1, then for every 10 points, the customer can redeem 1 unit of currency.

campaignName string The name of the rewards campaign associated with the activity .This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded.

campaignStartDate string The start date of the rewards campaign associated with the activity.This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded.

campaignEndDate string The end date of the rewards campaign associated with the activity.This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded.

campaignEnabled boolean Indicates if the associated campaign was enabled during the activity.This field will appear for activity types that are tied to a rewards campaign such as CampaignRewarded.

tierName string The tier name of the customer duringThe name of the tier associated with the activity. This is relevant when the activity involves a tier-related event, such as:TierUpgraded, TierDowngraded, TierMigration

Example: if a customer moves from "Silver" to "Gold" in the TierUpgraded activity, "Gold" will be displayed as the associated tier name.

rewardPoints number The number of points rewarded from the activity.

rewardFactor number The reward factor used in the calculation of reward points.

isGuest string A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.

couponUsed boolean Indicates whether the coupon associated with this activity was used or not. This is a boolean value, where true means the coupon was used during the activity, and false means it was not.

Example: true if the coupon was successfully applied, false if the coupon was associated with the event but was not used.

couponType string Represents the type of coupon associated with the activity.

Example: "percentage_discount", "free_shipping", "fixed_rate_discount".

couponCode string The code of the coupon that was associated with this activity. This is the actual coupon code that was available for use during the activity.

Example: "SUMMER20".

couponGroup string Represents the group or campaign to which the coupon is linked. This could be a marketing campaign, product category, or customer segment.

Example: "Holiday Campaign", "VIP Customer Group", "Black Friday Sale".

couponProduct string The name of the product associated with the coupon, if the coupon was tied to a specific product.

Example: "Wireless Earbuds".

couponProductId number The unique ID of the product associated with the coupon. This ID helps track which specific product was related to the coupon.

Example: 123456 for "Wireless Earbuds".

productVariantName string The name of the product variant involved in the event. This would apply if the coupon or activity was specific to a certain variant of a product, such as size or color.

Example: "Wireless Earbuds - Black", "T-shirt - Large".

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": "john.doe@example.com",
            "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/count

This 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

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}/automation

This 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

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.

automation object

order number The order in which this automation appears within the campai.

name string The internal name of the automation workflow configured from the dashboard.

isUnlocked boolean Indicates whether this automation is unlocked and customer can progress within the steps.

completed boolean Indicates whether the automation has been fully completed

steps Array list of steps involved in completing the automation.

steps.type string The type of step, for example rewarding a badge or adding points.

steps.order number

The order of this step within the automation sequence.

steps.completed boolean

Indicates whether this step has been completed or not.

steps.configuration object

Configuration details for the step, such as badge name & icon.

completionPercentage number

Percentage of completion for the automation

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

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

PreviousCustomer Management NextCustomer Tags

Last updated 8 days ago

Available APIs

GET - Customer Balance

https://api.gameball.co/api/v4/integrations/customers/{customerId}/balance