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

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 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, nullable — 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.
  - `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).
    - `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).
    - `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.
      - `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."

## 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.

---

[API](https://skmtc.net/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.net/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gameballers/gameball-api/versions/2e4a8bfe2291/schema)