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 .

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.

  • rewards.couponReward.couponType string The type of coupon provided to the customer (e.g., discount type, free shipping). Possible Values :

    • Free Shipping

    • Free Product

    • Fixed Percentage

    • Fixed Amount

    • Custom

Example: A coupon type of "Free Shipping" indicates that the coupon rewarded to the customer is of type free shipping.

  • rewards.couponReward.discountValue number The value of the discount provided by the coupon. Example: If a customer receives a coupon with a couponType of "fixed amount" and a discountValue of 50, they can apply it to their next purchase, reducing the total amount by $50.

  • rewards.couponReward.minOrderValue number The minimum order value required to use the coupon. Example: A coupon that specifies a minOrderValue of 100 means the customer must spend at least $100 to apply the coupon.

  • rewards.couponReward.options.expiryAfter string The time after which the coupon expires. Example: If a coupon expires on 2024-12-31T23:59:59Z, the customer must use it before that date to receive the discount.

  • rewards.couponReward.options.usageLimit number The total number of times this coupon can be used. Example: A coupon with a usageLimit of 1 can only be used by the customer once, requiring them to choose their purchase carefully.

  • rewards.couponReward.options.usedCount number The number of times the coupon has already been used. Example: If the usedCount is 0, it indicates that the customer has not yet used the coupon.

  • rewards.couponReward.options.capping number Maximum discount or value cap of the coupon. Example: A coupon with a capping of 500 means the maximum discount the customer can receive is $500.

  • rewards.couponReward.options.combinesWith.orderDiscounts boolean Indicates if the coupon can combine with order discounts. Example: IforderDiscounts is true, the customer can use it alongside other order discounts for additional savings.

  • rewards.couponReward.options.combinesWith.productDiscounts boolean Indicates if the coupon can combine with product discounts. Example: If productDiscounts is false, customers must choose between applying the coupon or a product-specific discount.

  • rewards.couponReward.options.combinesWith.shippingDiscounts boolean Indicates if the coupon can combine with shipping discounts. Example: If shippingDiscounts is true, the customer may receive both a discount on the product and free shipping.

  • rewards.couponReward.options.productId string The unique identifier of the product associated with the coupon. Example: If the coupon references productId "PROD12345", the customer can use it specifically for that product.

  • rewards.couponReward.options.productUrl string URL of the product associated with the coupon. Example: A product URL like https://store.example.com/product/12345 allows customers to click through directly to the product page.

  • rewards.couponReward.options.productName string The name of the product associated with the coupon. Example: If the coupon is tied to the product productName "Smartphone", customers can easily identify the item the coupon applies to.

  • rewards.couponReward.options.variantId string The variant ID of the product associated with the coupon. Example: A variant ID of VARIANT123 indicates that the coupon can only be used for that specific product variant.

  • rewards.couponReward.options.variantName string The name of the product variant associated with the coupon. Example: If the coupon refers to the variant name Black 128GB, it is valid only for that specific option of the product.

  • rewards.couponReward.options.productDisplayName string Display name of the product associated with the coupon. Example: productDisplayName "Smartphone 2024 Edition" serves as the recognizable name for the product.

  • rewards.couponReward.options.couponPrefix string The prefix for the coupon code, if applicable. Example: A coupon prefix of SUMMER indicates that the coupon is part of a seasonal promotion.

  • rewards.couponReward.options.collections Array An array of collections associated with the coupon. Example: If the coupon applies to collections ["Summer Collection", "New Arrivals"], customers can use it on any product from these collections.

  • rewards.couponReward.options.productDisplayNames Array A list of product display names associated with the coupon. Example: ["Smartphone 2024", "Laptop Pro"] provides recognizable names of the products eligible for the coupon.

  • rewards.couponReward.options.hasCollections boolean Indicates whether the coupon applies to collections. Example: If hasCollections is true, customers can use the coupon on specific collections of products.

  • rewards.couponReward.options.platforms Array Platforms on which the coupon can be redeemed (e.g., web, mobile). Example: If the coupon is valid on both web and mobile, customers can apply it in either context.

  • rewards.couponReward.options.redeemInstructions Array Instructions on how to redeem the coupon, if available. Example: Instructions such as ["Apply at checkout", "Valid in-store and online"] help guide customers on how to use the coupon.

  • rewards.couponReward.options.instructions string Additional instructions related to the coupon. Example: If the coupon has instructions stating Valid only on weekends, customers need to be aware of the restrictions.

  • rewards.couponReward.options.source string The source or origin of the coupon. Example: source "Email Campaign" indicates that the coupon was received through an email marketing effort.

  • rewards.couponReward.options.couponName string The name of the coupon for internal tracking or display purposes. Example: couponName is"Black Friday Discount" serves as a clear identifier for the promotion.

[
    {
        "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

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