--- title: "Get Customer Campaigns Progress" method: GET path: "/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress" --- # Get Customer Campaigns Progress `GET /api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress` ## Request - Base URL: `https://api.gameball.co` - URL: `https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress` - Auth: API key in header `apikey` and API key in header `secretkey` 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. ## Path parameters - `customerId` string, required ## Query parameters - `campaignType` 'reward' | 'game' - `campaignId` integer ## Headers - `lang` string ## Response `200` Customer campaigns progress retrieved successfully - object[] - `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, nullable: The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign. - `currentStreak` number, nullable: The customer's current consecutive streak count. Returned only for streak campaigns. The unit matches streakIntervalUnit on the campaign configuration (Day, Week, or Month). - `highestStreak` number, nullable: The highest consecutive streak count this customer has reached for this campaign. Returned only for streak campaigns. The unit matches streakIntervalUnit on the campaign configuration (Day, Week, or Month). - `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. - `canAchieve` boolean: A flag that determines whether the customer is currently eligible to participate in and achieve this reward campaign. It provides a quick indication of the customer's ability to meet the campaign's conditions based on their current status. - `rewardCampaignConfiguration` object: Comprehensive description of the reward campaign configuration. - `id` number: Unique identifier for the reward campaign. - `name` string: Name of the reward campaign. - `description` string, nullable: 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), Streak (Reward is given for consecutive actions over a Day, Week, or Month interval). - `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, nullable: 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, nullable: 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. - `redirectionButtonLink` string, nullable: 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. - `widgetDetailsParameter` string, nullable: This value is used with the openDetails parameter to open the widget for a specific campaign. The value is generated based on the campaign type and campaign ID. You could always use this parameter to trigger the widget on a specific page that you want. This parameter is only required if you are drawing your own UI but still want to display the UI of specific campaigns through the widget. In mobile apps, you can programmatically control the Gameball widget using our SDKs by passing the openDetails parameter with the appropriate value to navigate to different sections. Examples: details_reward_campaign_{reward_campaign_id} (Opens a standard reward campaign), details_wheel_{reward_campaign_id} (Opens a specific wheel campaign), details_scratch_{reward_campaign_id} (Opens a scratch card campaign), details_match_{reward_campaign_id} (Opens a match game campaign). - `streakIntervalUnit` 'Day' | 'Week' | 'Month', nullable: The unit used to count streak steps. Returned only for streak campaigns. Each step in startStep and endStep is measured in this unit: Day (consecutive days), Week (consecutive weeks), or Month (consecutive months). - `activation` object, nullable - `startDate` string, date-time, nullable: 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. - `endDate` string, date-time, nullable: 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` object[] - `rankReward` number: The score rewarded for achieving this reward campaign. - `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. - `walletRewardFactor` number, nullable: 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. - `order` number: The display order of this reward tier, starting at 1. Returned for streak campaigns where a campaign has multiple sequential reward ranges. - `startStep` number: The first streak step at which this reward applies. The step unit matches streakIntervalUnit (Day, Week, or Month). Example: startStep 7 with streakIntervalUnit Day means this reward starts on day 7 of the streak. - `endStep` number, nullable: The last streak step at which this reward applies. Omitted or null on the final open-ended tier, which applies from startStep onward. Example: startStep 1 and endStep 6 covers days 1 through 6 of a daily streak. - `couponReward` object, nullable - `couponType` string, nullable: The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom. - `discountValue` number, nullable: The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. - `product` object, nullable - `productId` string, nullable - `productName` string, nullable - `variantId` string, nullable - `variantName` string, nullable - `productDisplayName` string, nullable - `collections` object[], nullable: A list of collection IDs that the coupon can be applied to. - `collectionId` string, nullable: The unique identifier for the collection. - `collectionName` string, nullable: The name for the collection. - `group` object, nullable - `handle` string, nullable: A unique identifier used to reference the coupon group in the system. - `title` string, nullable: The title of the coupon group. - `url` string, nullable: The URL for the coupon group. - `iconPath` string, nullable: The path to the icon of the coupon group. - `description` string, nullable: A description of the coupon group. - `maxPerCustomer` number, nullable: 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. - `startDate` string, date-time, nullable: The date when the coupons within this coupon group will become active and valid for redemption. - `expiryDate` string, date-time, nullable: The date when the coupons within this coupon group will expire and no longer be valid for redemption. - `isAvailable` boolean, nullable: Indicates whether the coupon group is currently available. - `isActive` boolean, nullable: Indicates whether the coupon group is currently active. - `options` object, nullable - `name` string, nullable: The name of the reward rule configured on the dashboard based on required language. - `expiryAfter` number, nullable: 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. - `usageLimit` number, nullable: 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. - `capping` number, nullable: 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. - `minOrderValue` number, nullable: 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. - `codePrefix` string, nullable: The 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". - `redeemInstructions` string, nullable: The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount." - `currentTierStep` number, nullable: The startStep of the reward tier the customer is currently in. Returned only for streak campaigns. Example: if the customer is on day 1 of a daily streak whose first reward covers steps 1–6, currentTierStep is 1. - `nextMilestoneStep` number, nullable: The startStep of the next unreached reward tier. Returned only for streak campaigns. Null if the customer has already reached the last tier. - `stepsToNextMilestone` number, nullable: The number of remaining streak steps until nextMilestoneStep. Returned only for streak campaigns. Example: with currentStreak 1 and nextMilestoneStep 7, stepsToNextMilestone is 6. - `tierProgress` object[], nullable: Per-tier progress for a streak campaign. One entry per reward, using that reward's startStep. Returned only for streak campaigns. - `startStep` number: The startStep of this reward tier. Matches startStep on the corresponding item in rewards. - `isReached` boolean: Whether the customer has reached this reward tier. true when currentStreak is greater than or equal to this startStep. ## Other responses - `400`: Bad request. Returned when campaignId is non-numeric, such as campaignId=abc. - `422`: Unprocessable entity. Returned when campaignId is zero or negative. ## Changes - **2026-08-30** `747ba4697269`: 8 info - added the optional property `items/currentTierStep` to the response with the `200` status - added the optional property `items/nextMilestoneStep` to the response with the `200` status - added the optional property `items/rewardCampaignConfiguration/rewards/items/endStep` to the response with the `200` status - added the optional property `items/rewardCampaignConfiguration/rewards/items/order` to the response with the `200` status - …4 more - **2026-06-07** `1528367d52c8`: 3 info - added the new optional `query` request parameter `campaignId` - added the non-success response with the status `400` - added the non-success response with the status `422` - **2026-05-24** `bfc83e46a025`: 1 info - added the new optional `query` request parameter `campaignType` - **2026-03-30** `a38b379b77d4`: 1 info - added the new optional `header` request parameter `lang` - **2025-12-17** `d43ca6bdac5a`: 3 info - the endpoint scheme security `apiKey AND secretKey` was added to the API - the endpoint scheme security `apiKey` was removed from the API - the endpoint scheme security `secretKey` was removed from the API [Operation history](https://skmtc.dev/gameballers/apis/gameball-api/changes/api/v4.0/integrations/customers/:customerId/reward-campaigns-progress/get.md) --- [API](https://skmtc.dev/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.dev/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gameballers/apis/gameball-api/revisions/57b08ba96257?raw)