Skip to main content
GET
/
api
/
v4.0
/
integrations
/
customers
/
{customerId}
/
reward-campaigns-progress
Get Customer Campaigns Progress
curl --request GET \
  --url https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>'
[
  {
    "rewardsCampaignName": "<string>",
    "rewardsCampaignId": 123,
    "isUnlocked": true,
    "highScoreAmount": 123,
    "currentStreak": 123,
    "highestStreak": 123,
    "completionPercentage": 123,
    "achievedCount": 123,
    "canAchieve": true,
    "rewardCampaignConfiguration": {
      "id": 123,
      "name": "<string>",
      "description": "<string>",
      "isRepeatable": true,
      "maxAchievement": 123,
      "type": "<string>",
      "visibility": "<string>",
      "icon": "<string>",
      "redirectionButtonText": "<string>",
      "redirectionButtonLink": "<string>",
      "widgetDetailsParameter": "<string>",
      "activation": {
        "startDate": "2023-11-07T05:31:56Z",
        "endDate": "2023-11-07T05:31:56Z"
      },
      "rewards": [
        {
          "rankReward": 123,
          "walletReward": 123,
          "walletRewardFactor": 123,
          "couponReward": {
            "couponType": "<string>",
            "discountValue": 123,
            "product": {
              "productId": "<string>",
              "productName": "<string>",
              "variantId": "<string>",
              "variantName": "<string>",
              "productDisplayName": "<string>"
            },
            "collections": [
              {
                "collectionId": "<string>",
                "collectionName": "<string>"
              }
            ],
            "group": {
              "handle": "<string>",
              "title": "<string>",
              "url": "<string>",
              "iconPath": "<string>",
              "description": "<string>",
              "maxPerCustomer": 123,
              "startDate": "2023-11-07T05:31:56Z",
              "expiryDate": "2023-11-07T05:31:56Z",
              "isAvailable": true,
              "isActive": true
            },
            "options": {
              "name": "<string>",
              "expiryAfter": 123,
              "usageLimit": 123,
              "capping": 123,
              "minOrderValue": 123,
              "codePrefix": "<string>",
              "redeemInstructions": "<string>"
            }
          }
        }
      ]
    }
  }
]
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

ConditionResult
campaignId is omittedReturns the full campaign progress list, matching the previous behavior
campaignId matches a campaign available to the customer200 OK with an array containing one item
campaignId does not exist, is not visible, or fails customer eligibility200 OK with an empty array ([])
campaignId is zero or negative422 with code 3003 and type PAYLOAD_ERROR
campaignId is non-numeric, such as campaignId=abc400 Bad Request

​
Example: Single Campaign

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

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

{
  "code": 3003,
  "type": "PAYLOAD_ERROR",
  "message": "invalid campaignid value. the campaign id must be a positive integer."
}

Authorizations

​
apikey
string
header
required
​
secretkey
string
header
required

Headers

​
lang
string

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.

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

​
campaignType
enum<string>

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.

Available options:
reward,
game
​
campaignId
integer

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.

Required range: x >= 1

Response

Customer campaigns progress retrieved successfully

​
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 | null

The highest score achieved by the customer. This value is applicable only in the context of a high score rewards campaign.

​
currentStreak
number | null

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

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.