Get Customer Campaigns Progress

Changed on

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.

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

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress
  • Auth: API key in header apikey and API key in header secretkey

Path parameters

customerIdstring 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'reward' | 'game'

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.

campaignIdinteger

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.

Headers

langstring

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.

Response

Customer campaigns progress retrieved successfully

rewardsCampaignNamestring

The name of the rewards campaign.

rewardsCampaignIdnumber

The unique ID of the rewards campaign.

isUnlockedboolean

Indicates if the customer has unlocked the campaign.

highScoreAmountnumber nullable

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

currentStreaknumber nullable

The customer's current consecutive streak count. Returned only for streak campaigns. The unit matches streakIntervalUnit on the campaign configuration (Day, Week, or Month).

highestStreaknumber nullable

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

completionPercentagenumber

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

achievedCountnumber

The number of times the customer has achieved the campaign.

canAchieveboolean

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.

currentTierStepnumber nullable

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.

nextMilestoneStepnumber nullable

The startStep of the next unreached reward tier. Returned only for streak campaigns. Null if the customer has already reached the last tier.

stepsToNextMilestonenumber nullable

The number of remaining streak steps until nextMilestoneStep. Returned only for streak campaigns. Example: with currentStreak 1 and nextMilestoneStep 7, stepsToNextMilestone is 6.

Changes

  • 747ba4697269Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 1528367d52c8Revision changes
    • info

      added the new optional query request parameter campaignId

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status