v4.0

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

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.

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

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 .

Sample Response

[
    {
        "rewardsCampaignName": "Third Order Campaign 🛍️",
        "rewardsCampaignId": 5859,
        "isUnlocked": true,
        "highScoreAmount": null,
        "currentStreak": null,
        "highestStreak": null,
        "completionPercentage": 33.0,
        "achievedCount": 0
    },
    {
        "rewardsCampaignName": "Birthday Reward 🎉",
        "rewardsCampaignId": 5860,
        "isUnlocked": true,
        "highScoreAmount": null,
        "currentStreak": null,
        "highestStreak": null,
        "completionPercentage": 100.0,
        "achievedCount": 1
    }
]

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

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.

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

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

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.

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

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
}

PreviousCustomer ManagementNextCustomer Tags

Last updated