Customer Campaigns Progress
Retrieve customer’s progress within Gameball’s reward campaigns, providing insights into achievements and current status in each campaign.
v4.1.
Filter by Campaign ID
Use the optionalcampaignId 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
Example: Single Campaign
Example: Campaign ID and Type
Example: Invalid Campaign ID
Streak campaign progress
For streak campaigns, the response includes the customer’s current streak plus step-level progress against each reward. The step unit matchesstreakIntervalUnit on rewardCampaignConfiguration (Day, Week, or Month).
Example: Daily streak progress
currentStreakis1andcurrentTierStepis1(the days 1–6 range)nextMilestoneStepis7(the 10-point reward)stepsToNextMilestoneis6- Only the first
tierProgressentry hasisReached: 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.
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.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.
Example: Mission with three tasks
The response is still a JSON array. WithcampaignId set, the array contains one mission. highScoreAmount, streak fields, and rewardCampaignConfiguration are unchanged and left out of this example.
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:
Headers
Path Parameters
Query Parameters
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.
reward, game 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.
x >= 1Response
Customer campaigns progress retrieved successfully