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

The API call retrieves the customer's current points balance available for redemption along with the corresponding equivalent amount.

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

The API call retrieves the tier progress of the customer identified by customerId. This provides insights into the customer's current tier status and progress toward the next tier.

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

The API call retrieves the reward campaign progress of the customer identified by customerId. This allows tracking the customer's achievements and progress within the reward campaigns.

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 .

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

The API call retrieves the list of customers referred by a customer identified by customerId. This allows for tracking referral activity and customer engagement within the referral program.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

Query Parameters

page number Optional Specifies which page of results to return. Defaults to 1.

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 number of referrals returned in the current response.

total number The total number of referrals made by the customer.

totalPending number he total number of referrals that are still pending completion. This value represents the count of referred friends who have not yet fulfilled the necessary actions for the referral to be successfully credited to the customer.

totalActive number The total number of referrals that have been completed.

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,
    "total": 2,
    "totalPending": 1,
    "totalActive": 1
}

GET - Customer Activities

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

The API call retrieves the activity logs of the customer identified by customerId. This enables tracking and reviewing the customer's actions and interactions within the system.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

Query Parameters

pageNo number Optional Specifies which page of results to return. Defaults to 1.

pageSize number Optional Specifies the number of activities to return per page. Defaults to 12.

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

pageNo number The current page number of the response.

pageSize number The number of activities returned in the response.

count number The total number of activities on the current page.

data 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".

Sample Response

{
    "pageNo": 1,
    "pageSize": 12,
    "count": 1,
    "data": [
        {
            "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
        }
    ]
}

PreviousCustomer Management NextCustomer Tags

Last updated 5 days ago