Customer Campaigns Progress

Retrieve customer’s progress within Gameball’s reward campaigns, providing insights into achievements and current status in each campaign.

GET /api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress

Get Customer Campaigns Progress

cURL

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

200

[
  {
    "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>",
      "streakIntervalUnit": "Day",
      "activation": {
        "startDate": "2023-11-07T05:31:56Z",
        "endDate": "2023-11-07T05:31:56Z"
      },
      "rewards": [
        {
          "rankReward": 123,
          "walletReward": 123,
          "walletRewardFactor": 123,
          "order": 123,
          "startStep": 123,
          "endStep": 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>"
            }
          }
        }
      ]
    },
    "currentTierStep": 123,
    "nextMilestoneStep": 123,
    "stepsToNextMilestone": 123,
    "tierProgress": [
      {
        "startStep": 123,
        "isReached": true
      }
    ],
    "completedStepsCount": 123,
    "totalStepsCount": 123,
    "steps": [
      {
        "stepNumber": 123,
        "isCompleted": true,
        "name": "<string>",
        "description": "<string>",
        "completionPercentage": 123,
        "currentValue": 123,
        "targetValue": 123,
        "trigger": {
          "eventName": "<string>",
          "conditions": [
            {
              "name": "<string>",
              "operator": "Equals",
              "value": "<string>"
            }
          ]
        },
        "reward": {
          "rankReward": 123,
          "walletReward": 123,
          "walletRewardFactor": 123,
          "couponReward": {}
        }
      }
    ]
  }
]

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. For a mission, the response also lists each task in dashboard order, with its name, rules, reward, and the customer’s progress on that task.

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

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."
}

Streak campaign progress

For streak campaigns, the response includes the customer’s current streak plus step-level progress against each reward. The step unit matches streakIntervalUnit on rewardCampaignConfiguration (Day, Week, or Month).

Field	Description
currentStreak	The customer’s current consecutive streak count, in streakIntervalUnit.
highestStreak	The highest streak this customer has reached for this campaign.
currentTierStep	The startStep of the reward tier the customer is currently in.
nextMilestoneStep	The startStep of the next unreached reward tier. null if the customer has reached the last tier.
stepsToNextMilestone	Remaining steps until nextMilestoneStep.
tierProgress	One entry per reward, with that reward’s startStep and whether the customer has reached it.
rewardCampaignConfiguration.rewards	The same order, startStep, and endStep ranges returned by Campaigns Configurations.

Example: Daily streak progress

curl "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress?campaignId=2783" \
  -H "APIKey: {your_api_key}" \
  -H "secretkey: {your_secret_key}"

[
  {
    "rewardsCampaignName": "Daily Visit ",
    "rewardsCampaignId": 2783,
    "isUnlocked": true,
    "highScoreAmount": null,
    "currentStreak": 1,
    "highestStreak": 1,
    "completionPercentage": 0.0,
    "achievedCount": 1,
    "canAchieve": false,
    "rewardCampaignConfiguration": {
      "id": 2783,
      "name": "Daily Visit ",
      "type": "Streak",
      "streakIntervalUnit": "Day",
      "rewards": [
        { "order": 1, "walletReward": 0, "startStep": 1, "endStep": 6 },
        { "order": 2, "walletReward": 10, "startStep": 7, "endStep": 7 },
        { "order": 3, "walletReward": 0, "startStep": 8, "endStep": 13 },
        { "order": 4, "walletReward": 20, "startStep": 14, "endStep": 14 },
        { "order": 5, "walletReward": 0, "startStep": 15, "endStep": 20 },
        { "order": 6, "walletReward": 30, "startStep": 21, "endStep": 21 },
        { "order": 7, "walletReward": 0, "startStep": 22, "endStep": 29 },
        { "order": 8, "walletReward": 100, "startStep": 30 }
      ]
    },
    "currentTierStep": 1,
    "nextMilestoneStep": 7,
    "stepsToNextMilestone": 6,
    "tierProgress": [
      { "startStep": 1, "isReached": true },
      { "startStep": 7, "isReached": false },
      { "startStep": 8, "isReached": false },
      { "startStep": 14, "isReached": false },
      { "startStep": 15, "isReached": false },
      { "startStep": 21, "isReached": false },
      { "startStep": 22, "isReached": false },
      { "startStep": 30, "isReached": false }
    ]
  }
]

In this example the customer is on day 1 of a daily streak:

• currentStreak is 1 and currentTierStep is 1 (the days 1–6 range)
• nextMilestoneStep is 7 (the 10-point reward)
• stepsToNextMilestone is 6
• Only the first tierProgress entry has isReached: true

Mission task progress

For mission campaigns, the response includes each task so a custom loyalty page can show a checklist, such as finished tasks ticked and “1 of 3 tasks done” at the top. Tasks are returned in dashboard order. stepNumber starts at 1.

rewardsCampaignName, rewardsCampaignId, isUnlocked, completionPercentage, achievedCount, and canAchieve are unchanged. completionPercentage is still the mission’s overall progress. completedStepsCount and totalStepsCount are the task counts behind that percentage.

Field	Description
completedStepsCount	Tasks the customer has finished.
totalStepsCount	Tasks in the mission.
steps	One object per task, in dashboard order.
steps[].stepNumber	Task position. Starts at 1.
steps[].isCompleted	true once the customer finishes the task.
steps[].name	Task name. Returned in the language from the lang header when that header is sent.
steps[].description	Task description. Returned in the language from the lang header when that header is sent.
steps[].completionPercentage	0 until the task is completed, then 100. A partial value, such as 30, is returned only for an AccumulativeTotal task.
steps[].currentValue	0 until the task is completed, then equal to targetValue. A partial value, such as 300, is returned only for an AccumulativeTotal task.
steps[].targetValue	1 for a standard task. For an AccumulativeTotal task, the total configured on the rule, such as 1000.
steps[].trigger.eventName	Event that completes the task, such as place_order.
steps[].trigger.conditions	Rules on that event. Omitted when the task has no rules.
steps[].trigger.conditions[].name	Event property, such as total_price.
steps[].trigger.conditions[].operator	Rule operator. See the operator table below.
steps[].trigger.conditions[].value	Rule value. Always a string. Between uses "min,max".
steps[].reward	Reward for finishing the task. Omitted when the task has no reward.
steps[].reward.walletReward	Points awarded for finishing the task.
steps[].reward.rankReward	Rank points awarded for finishing the task.
steps[].reward.walletRewardFactor	Points multiplier. null when the reward is not a multiplier.
steps[].reward.couponReward	Coupon awarded for finishing the task. null when the reward is not a coupon. Uses the same coupon fields as rewardCampaignConfiguration.rewards[].couponReward.

Partial progress: AccumulativeTotal is the only operator that reports progress before the task is finished. After orders totaling 300 toward a target of 1,000, currentValue is 300 and completionPercentage is 30. Every other task stays at 0 until the customer finishes it. Then currentValue equals targetValue and completionPercentage is 100.

What Accumulative total counts: It adds up a numeric event property across events, such as order value. It does not count how many times an event occurred. A task such as “place 3 orders” is not supported.

Completion window: When a mission’s completion window ends and progress resets, task progress resets too. completedStepsCount returns to 0, and each task returns isCompleted: false, currentValue: 0, and completionPercentage: 0.

Rule operators

steps[].trigger.conditions[].operator is one of the following. value is always a string. Between takes "min,max". IsEmpty and IsNotEmpty do not take a value.

Operator	Label	Field type	Value
Equals	Equals	Number, text	A number or text
NotEquals	Is not	Number, text	A number or text
EqualsOrGreater	Equals Or Greater	Number	A number
GreaterThan	Greater than	Number	A number
LessThan	Less than	Number	A number
LessThanOrEqual	Less than or equal	Number	A number
Between	Between	Number	"min,max"
DifferentValues	Different Values	Number	A number
AccumulativeTotal	Accumulative total	Number	The total to reach
Contains	Contains	Text	Text
NotContains	Does not contain	Text	Text
StartsWith	Starts with	Text	Text
EndsWith	Ends with	Text	Text
IsEmpty	Is empty	Text	None
IsNotEmpty	Is not empty	Text	None

Example: Mission with three tasks

The response is still a JSON array. With campaignId set, the array contains one mission. highScoreAmount, streak fields, and rewardCampaignConfiguration are unchanged and left out of this example.

curl "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress?campaignId=12640" \
  -H "APIKey: {your_api_key}" \
  -H "secretkey: {your_secret_key}" \
  -H "lang: en"

[
  {
    "rewardsCampaignName": "WI25272 Mission A",
    "rewardsCampaignId": 12640,
    "isUnlocked": true,
    "completionPercentage": 33.333,
    "achievedCount": 0,
    "canAchieve": true,
    "completedStepsCount": 1,
    "totalStepsCount": 3,
    "steps": [
      {
        "stepNumber": 1,
        "isCompleted": true,
        "name": "Order above 100",
        "description": "Place one order of 100 or more",
        "completionPercentage": 100.0,
        "currentValue": 1,
        "targetValue": 1,
        "trigger": {
          "eventName": "place_order",
          "conditions": [
            { "name": "total_price", "operator": "EqualsOrGreater", "value": "100" }
          ]
        },
        "reward": {
          "rankReward": 0,
          "walletReward": 10,
          "walletRewardFactor": null,
          "couponReward": null
        }
      },
      {
        "stepNumber": 2,
        "isCompleted": false,
        "name": "Big order",
        "description": "One order of 500 or more with at least 3 items",
        "completionPercentage": 0.0,
        "currentValue": 0,
        "targetValue": 1,
        "trigger": {
          "eventName": "place_order",
          "conditions": [
            { "name": "total_price", "operator": "EqualsOrGreater", "value": "500" },
            { "name": "total_items", "operator": "EqualsOrGreater", "value": "3" }
          ]
        },
        "reward": {
          "rankReward": 0,
          "walletReward": 20,
          "walletRewardFactor": null,
          "couponReward": null
        }
      },
      {
        "stepNumber": 3,
        "isCompleted": false,
        "name": "View a product",
        "description": "Open any product page",
        "completionPercentage": 0.0,
        "currentValue": 0,
        "targetValue": 1,
        "trigger": {
          "eventName": "view_product_page"
        }
      }
    ]
  }
]

In this example the customer has finished 1 of 3 tasks, so completionPercentage is 33.333. Task 3 has no rules and no reward, so conditions and reward are omitted.

An AccumulativeTotal task that has accumulated 300 of a 1,000 target looks like this:

{
  "stepNumber": 1,
  "isCompleted": false,
  "completionPercentage": 30.0,
  "currentValue": 300,
  "targetValue": 1000,
  "trigger": {
    "eventName": "place_order",
    "conditions": [
      { "name": "total_price", "operator": "AccumulativeTotal", "value": "1000" }
    ]
  }
}

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

200

application/json

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

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.

Show child attributes

currentTierStep · number | null

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

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

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

Per-tier progress for a streak campaign. One entry per reward, using that reward's startStep. Returned only for streak campaigns.

Show child attributes

completedStepsCount · integer | null

The number of mission tasks the customer has finished. Returned for mission campaigns. Use with totalStepsCount to show progress such as 1 of 3 tasks done.

totalStepsCount · integer | null

The number of tasks in the mission. Returned for mission campaigns.

steps · object[] | null

Mission tasks in dashboard order, starting at stepNumber 1. Returned for mission campaigns. One entry per task. When a mission completion window ends and progress resets, every task in this array resets as well.

Show child attributes