> ## Documentation Index > Fetch the complete documentation index at: https://docs.gameball.co/llms.txt > Use this file to discover all available pages before exploring further. # Customer Campaigns Progress > Retrieve customer's progress within Gameball's reward campaigns, providing insights into achievements and current status in each campaign. 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. This endpoint is also available on `v4.1`. **Security**: Requires **apikey** and **secretkey** headers. ### Filter by Campaign ID Use the optional `campaignId` query parameter to return progress for a single campaign instead of retrieving the full campaign list. The value must be a positive integer and should match the campaign ID returned in `rewardsCampaignId` or `rewardCampaignConfiguration.id`. When `campaignId` is provided, the response is still a JSON array. A matching campaign returns an array with one item. If the campaign does not exist, is not visible to the customer, or the customer is not eligible for it, the endpoint returns `200 OK` with an empty array (`[]`), not `404`. You can combine `campaignId` with `campaignType`. When both filters are provided, both must match. For example, `?campaignId=123&campaignType=game` returns the campaign only if campaign `123` is also a game campaign; otherwise, the response is an empty array. ### Validation | Condition | Result | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `campaignId` is omitted | Returns the full campaign progress list, matching the previous behavior | | `campaignId` matches a campaign available to the customer | `200 OK` with an array containing one item | | `campaignId` does not exist, is not visible, or fails customer eligibility | `200 OK` with an empty array (`[]`) | | `campaignId` is zero or negative | `422` with code `3003` and type `PAYLOAD_ERROR` | | `campaignId` is non-numeric, such as `campaignId=abc` | `400 Bad Request` | ### Example: Single Campaign ```bash theme={null} curl "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress?campaignId=6151" \ -H "APIKey: {your_api_key}" \ -H "secretkey: {your_secret_key}" ``` Example response: ```json theme={null} [ { "rewardsCampaignName": "First Order", "rewardsCampaignId": 6151, "isUnlocked": true, "highScoreAmount": null, "currentStreak": null, "highestStreak": null, "completionPercentage": 0.0, "achievedCount": 0, "canAchieve": true, "rewardCampaignConfiguration": { "...": "unchanged existing schema" } } ] ``` ### Example: Campaign ID and Type ```bash theme={null} curl "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress?campaignId=9732&campaignType=game" \ -H "APIKey: {your_api_key}" \ -H "secretkey: {your_secret_key}" ``` ### Example: Invalid Campaign ID ```json theme={null} { "code": 3003, "type": "PAYLOAD_ERROR", "message": "invalid campaignid value. the campaign id must be a positive integer." } ``` ## OpenAPI ````yaml GET /api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress openapi: 3.1.0 info: title: Gameball API description: >- Gameball REST API v4.0 - Complete API reference for integrating loyalty, gamification, and customer engagement features version: 4.0.0 servers: - url: https://api.gameball.co security: - bearerAuth: [] paths: /api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress: get: summary: Get Customer Campaigns Progress description: >- 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. operationId: getCustomerCampaignsProgress parameters: - name: customerId in: path required: true description: >- 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. schema: type: string - name: lang in: header description: >- If the lang header is provided, the response will be returned in the specified language (e.g., en for English, fr for French). If this header is not included, the system will use the default language. required: false schema: type: string - name: campaignType in: query required: false schema: type: string enum: - reward - game description: >- Filter campaigns by type. Use `reward` to return only reward-type campaigns (points multipliers, missions, spending milestones, streaks, etc.), or `game` for game-type campaigns (Spin the Wheel, Slot Machine, Quiz, Scratch & Win, Match Cards, etc.). Omit to return all campaigns. Any other value results in a validation error. - name: campaignId in: query required: false schema: type: integer minimum: 1 description: >- Filter the response to a single campaign by its ID. When provided, the response array contains at most one item: the matching campaign's progress, or an empty array if the campaign does not exist or is not available to this customer. Must be a positive integer. Use the campaign ID returned in rewardsCampaignId or rewardCampaignConfiguration.id. Can be combined with campaignType, in which case both filters apply. responses: '200': description: Customer campaigns progress retrieved successfully content: application/json: schema: $ref: '#/components/schemas/CustomerCampaignsProgressResponse' '400': description: >- Bad request. Returned when campaignId is non-numeric, such as campaignId=abc. '422': description: Unprocessable entity. Returned when campaignId is zero or negative. content: application/json: schema: type: object properties: code: type: integer example: 3003 type: type: string example: PAYLOAD_ERROR message: type: string example: >- invalid campaignid value. the campaign id must be a positive integer. example: code: 3003 type: PAYLOAD_ERROR message: >- invalid campaignid value. the campaign id must be a positive integer. security: - apiKey: [] secretKey: [] components: schemas: CustomerCampaignsProgressResponse: type: array items: type: object properties: rewardsCampaignName: type: string description: The name of the rewards campaign. rewardsCampaignId: type: number description: The unique ID of the rewards campaign. isUnlocked: type: boolean description: Indicates if the customer has unlocked the campaign. highScoreAmount: type: - number - 'null' description: >- The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign. currentStreak: type: - number - 'null' description: >- 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: type: - number - 'null' description: >- 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: type: number description: >- 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: type: number description: The number of times the customer has achieved the campaign. canAchieve: type: boolean description: >- 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: type: object description: Comprehensive description of the reward campaign configuration. properties: id: type: number description: Unique identifier for the reward campaign. name: type: string description: Name of the reward campaign. description: type: - string - 'null' description: A brief description of the reward campaign. isRepeatable: type: boolean description: >- 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: type: number description: >- 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: type: string description: >- 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: type: string description: >- 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: type: - string - 'null' description: >- 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: type: - string - 'null' description: >- 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: type: - string - 'null' description: >- 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: type: - string - 'null' description: >- 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: type: - object - 'null' properties: startDate: type: - string - 'null' format: date-time description: >- 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: type: - string - 'null' format: date-time description: >- 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: type: array items: type: object properties: rankReward: type: number description: The score rewarded for achieving this reward campaign. walletReward: type: number description: >- 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: type: - number - 'null' description: >- 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: type: - object - 'null' properties: couponType: type: - string - 'null' description: >- The type of coupon applied. Possible values include: free_shipping, percentage_discount, fixed_discount, fixed_rate_discount, free_product, custom. discountValue: type: - number - 'null' description: >- The value of the discount provided by the coupon in case the coupon type is fixed_discount, percentage_discount or fixed_rate_discount. product: type: - object - 'null' properties: productId: type: - string - 'null' productName: type: - string - 'null' variantId: type: - string - 'null' variantName: type: - string - 'null' productDisplayName: type: - string - 'null' collections: type: - array - 'null' description: >- A list of collection IDs that the coupon can be applied to. items: type: object properties: collectionId: type: - string - 'null' description: The unique identifier for the collection. collectionName: type: - string - 'null' description: The name for the collection. group: type: - object - 'null' properties: handle: type: - string - 'null' description: >- A unique identifier used to reference the coupon group in the system. title: type: - string - 'null' description: The title of the coupon group. url: type: - string - 'null' description: The URL for the coupon group. iconPath: type: - string - 'null' description: The path to the icon of the coupon group. description: type: - string - 'null' description: A description of the coupon group. maxPerCustomer: type: - number - 'null' description: >- 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: type: - string - 'null' format: date-time description: >- The date when the coupons within this coupon group will become active and valid for redemption. expiryDate: type: - string - 'null' format: date-time description: >- The date when the coupons within this coupon group will expire and no longer be valid for redemption. isAvailable: type: - boolean - 'null' description: >- Indicates whether the coupon group is currently available. isActive: type: - boolean - 'null' description: >- Indicates whether the coupon group is currently active. options: type: - object - 'null' properties: name: type: - string - 'null' description: >- The name of the reward rule configured on the dashboard based on required language. expiryAfter: type: - number - 'null' description: >- 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: type: - number - 'null' description: >- 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: type: - number - 'null' description: >- 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: type: - number - 'null' description: >- 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: type: - string - 'null' description: >- 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: type: - string - 'null' description: >- The instructions on how the customer can redeem the coupon. Example: "Enter the coupon code at checkout to apply the discount." securitySchemes: bearerAuth: type: http scheme: bearer apiKey: type: apiKey in: header name: apikey secretKey: type: apiKey in: header name: secretkey ````