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

const options = {method: 'GET', headers: {apikey: '<api-key>', secretkey: '<api-key>'}};

fetch('https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress"

headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "apikey: <api-key>",
    "secretkey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.get("https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .asString();

[
  {
    "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
      }
    ]
  }
]

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

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

const options = {method: 'GET', headers: {apikey: '<api-key>', secretkey: '<api-key>'}};

fetch('https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress"

headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
var response = await client.GetAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "apikey: <api-key>",
    "secretkey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.get("https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/reward-campaigns-progress")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .asString();

[
  {
    "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
      }
    ]
  }
]

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

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

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

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

API documentation

Webhooks

Customer Campaigns Progress

Filter by Campaign ID

Validation

Example: Single Campaign

Example: Campaign ID and Type

Example: Invalid Campaign ID

Streak campaign progress

Example: Daily streak progress

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Filter by Campaign ID

​Validation

​Example: Single Campaign

​Example: Campaign ID and Type

​Example: Invalid Campaign ID

​Streak campaign progress

​Example: Daily streak progress

Authorizations

Headers

Path Parameters

Query Parameters

Response

Filter by Campaign ID

Validation

Example: Single Campaign

Example: Campaign ID and Type

Example: Invalid Campaign ID

Streak campaign progress

Example: Daily streak progress