Program Configurations

Access information on how customers can participate in campaigns, advance through tiers, and benefit from referral programs. These APIs provide the necessary data to display how customers can win

Available APIs

GET - Campaigns Configurations

https://api.gameball.co/api/v4/integrations/configurations/reward-campaigns

The API retrieves your reward campaign configurations, including both event-based and transactional campaigns. If the customerId, productSku, or collectionId query parameters are provided, the response will include the reward campaigns that are applicable for the specified customer or product.

Security: Requires apiKey header

Request

Query Parameters

customerId string Optional 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. If provided, the API filters and returns only the campaigns that can be achieved by this customer.

collectionId string Optional Unique identifier for a product collection. If provided, the API returns the transactional campaigns applicable to the specified collection.

productSku string Optional The SKU (Stock Keeping Unit) of a product. If provided, the API returns the transactional campaigns applicable to the specified product.

lang string Optional The language in which the response should be returned (e.g., en, fr). If not provided, the default language is used.

Response

application/json

The response will return a list of reward campaigns, each containing detailed information about the campaign’s rewards, availability, visibility, and other configurations.Each reward campaign object includes the following fields:

Reward Campaign Object

id number Unique identifier for the reward campaign.

name string Name of the reward campaign.

description string A brief description of the reward campaign.

isRepeatable boolean Indicates whether the campaign can be earned multiple times. Example: If set to true, a customer can earn the campaign reward each time they meet the criteria, and if set to false, the campaign can only be earned once per customer.

maxAchievement number Specifies the maximum number of times the campaign can be earned if the value of isRepeatable is true . If the value is -1, it means the campaign can be earned indefinitely. Example: A value of 3 means the customer can earn the campaign reward up to three times before it is no longer available.

type string The type of the campaign. Possible values:

  • SignUp: Reward is given when a user signs up.

  • SocialMedia: Reward is linked to social media activity.

  • ScheduledChallenge: A time-based challenge that gives rewards.

  • Spin The Wheel: Rewards are given based on a spin-the-wheel game.

  • EventBased: Reward is given based on specific customer events.

  • HighScore: Reward is given based on achieving high scores in a campaign.

  • Birthday: Reward is given for birthday-related activity.

visibility string The visibility status of the campaign. Possible values:

  • AlwaysVisible: The campaign is always visible on the widget.

  • NotVisible: The campaign is not visible to the customer on the widget.

  • VisibleIfEarned: The campaign becomes visible once the customer earns it on the widget.

icon string The URL of the campaign’s icon image. This icon visually represents the campaign and can be used in marketing materials or on the platform.

availability object

Defines the criteria determining which customers are eligible to earn this reward campaign.

availability object

minTier number The minimum customer tier order required to achieve in the campaign. Customers must meet or exceed this tier to be eligible.

Example: A value of 2 indicates that only customers in the tier with order 2 or higher can earn this campaign.

tags array A list of tags that identify the target customers eligible for the campaign. Tags can be used to group customers based on specific attributes or behaviors.

Example: ["loyal", "new_customer"] indicates that only customers tagged as "loyal" or "new_customer" are eligible for the campaign.

redirectionButtonText string

The text displayed on the redirection button within the reward campaign page on the widget. Example: "Claim Your Reward" would prompt customers to take action.Text for the redirection button.

redirectionButtonLink string

The URL that the redirection button points to. When customers click the button, they will be redirected to this link. It should lead to a relevant page that provides more information or facilitates the reward campaign achievement. Example: "https://yourwebsite.com/rewards" directs customers to a page where they can view their rewards.

activation object Defines the activation criteria for the campaign, which may include specific start and end dates.

activation object

StartDate DateTime The date and time when the campaign becomes active. This value determines when customers can begin to earn or win rewards associated with the campaign. Example: "2024-11-01T00:00:00" indicates that the campaign starts on November 1, 2024.

EndDate DateTime? The date and time when the campaign ends. After this date, customers will no longer be able to earn this campaign . Example: "2024-11-30T23:59:59" indicates that the campaign ends on November 30, 2024, at 11:59 PM.

rewards array Details of the rewards that the customer will earn once achieving this reward campaign.

rewards object

rankReward number The score rewarded for achieving this reward campaign.

walletReward number The number of points the customer will earn upon achieving this reward campaign.

Example:If you have set up a "First Order" campaign where a customer earns 200 points as a reward for placing their first order, the walletReward value would be 200.

walletRewardFactor number The multiplier applied to the points a customer earns based on the amount they spend during this campaign. This factor is used in transactional campaigns, such as points multipliers.

Example: In a "Double Points" campaign, the walletRewardFactor would be set to 2, meaning the customer will earn twice the normal amount of points for their purchases during the campaign.

couponReward object

A coupon object that is awarded to the customer for this reward campaign.

  • couponReward.couponType string The type of coupon applied. Possible values include:

    • free_shipping

    • percentage_discount

    • fixed_discount

    • fixed_rate_discount

    • free_product

    • custom

  • couponReward.discountValue number The value of the discount provided by the coupon in case the coupon type is fixed_discount , percentage_discount or fixed_rate_discount.

  • couponReward.product.productId string The unique identifier for the product.

  • couponReward.product.productName string The name of the product.

  • couponReward.product.variantId string The unique identifier for the product variant.

  • couponReward.product.variantName string The name of the product variant.

  • coucouponRewardpon.product.productDisplayName string The display name associated with the product that configured on the dashboard based on required language.

  • couponReward.collections array A list of collection IDs that the coupon can be applied to.

  • couponReward.collections.collectionId string The unique identifier for the collection.

  • couponReward.collections.collectionName string The name for the collection.

  • couponReward.group.handle string A unique identifier used to reference the coupon group in the system.

  • couponReward.group.title string The title of the coupon group.

  • couponReward.group.url string The URL for the coupon group.

  • couponReward.group.iconPath string The path to the icon of the coupon group.

  • couponReward.group.description string A description of the coupon group.

  • couponReward.group.maxPerCustomer number The maximum number of times a customer can use the coupon.

Example: 5 indicates that each customer can redeem this coupon up to 5 times.

  • couponReward.group.startDate datetime The date when the coupons within this coupon group will become active and valid for redemption.

  • couponReward.group.expiryDate datetime The date when the coupons within this coupon group will expire and no longer be valid for redemption.

  • couponReward.group.isAvailable boolean Indicates whether the coupon group is currently available.

  • couponReward.group.isActive boolean Indicates whether the coupon group is currently active.

  • couponReward.options.name string The name of the reward rule configured on the dashboard based on required language.

  • couponReward.options.expiryAfter number The number of days after creation that the coupon will expire.

    Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

  • couponReward.options.usageLimit number The maximum number of times a single coupon can be used.

    Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

  • couponReward.options.capping number The maximum discount value a coupon can provide, regardless of the order amount.

    Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

  • couponReward.options.minOrderValue number The minimum order amount required to apply the coupon.

    Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

  • couponReward.options.codePrefix string TThe prefix that will be added to the beginning of the generated coupon code.

    Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".

  • couponReward.options.redeemInstructions string The instructions on how the customer can redeem the coupon.

    Example: "Enter the coupon code at checkout to apply the discount."

Sample Response

[
    {
        "id": 5858,
        "name": "Join our family 👯‍♂️",
        "description": "Welcome to the family! Check out your new reward for signing up 😉",
        "rewards": [
            {
                "rankReward": 0,
                "walletReward": 0,
                "walletRewardFactor": null,
                "couponReward": null
            }
        ],
        "isRepeatable": false,
        "maxAchievement": 1,
        "type": "SignUp",
        "visibility": "AlwaysVisible",
        "icon": "https://cdn.gameball.co/uploads/gb-library/general/signup.webp",
        "availability": {
            "minTier": 1,
            "tags": []
        },
        "redirectionButtonText": "Check Your Rewards",
        "redirectionButtonLink": "https://yourwebsite.co/rewards",
        "activation": {
            "startDate": "2024-09-01T00:00:00Z",
            "endDate": "2024-12-31T23:59:59Z"
        }
    },
    {
        "id": 6652,
        "name": "Double points",
        "description": "Earn double points on all purchases during this limited-time campaign!",
        "rewards": [
            {
                "rankReward": 0,
                "walletReward": 0,
                "walletRewardFactor": 2,
                "couponReward": null
            }
        ],
        "isRepeatable": true,
        "maxAchievement": -1,
        "type": "Reward Campaign",
        "visibility": "NotVisible",
        "icon": "https://cdn.gameball.co/uploads/gb-library/general/announcement.webp",
        "availability": {
            "minTier": 1,
            "tags": []
        },
        "redirectionButtonText": "Start Earning Double Points",
        "redirectionButtonLink": "https://yourwebsite.co/doublepoints",
        "activation": {
            "startDate": "2024-10-01T00:00:00Z",
            "endDate": "2024-10-31T23:59:59Z"
        }
    }
]

GET - Tiers Configurations

https://api.gameball.co/api/v4/integrations/configurations/tiers

This API call retrieves the tiers configuration, including the benefits and rewards associated with each tier.

Security: Requires apiKey header

Response

application/json

name string The name of the tier.

minProgress number

The minimum amount of progress a customer needs to reach this tier in the program. This represents the threshold that must be met for a customer to reach this tier.

Example: if the minProgress is set to 2000, the customer must accumulate 2000 points, referrals, or completed orders (depending on the tiering method) to reach this tier.

Possible Values:

  • Total amount spent

  • Total points earned

  • Friends referred

  • Orders completed

  • Score

Example: If the progress value is 1500 and the tiering-up method is total points earned, this means the customer has earned a total of 1500 points toward their next tier.

order number This represents the numerical order of a tier. Higher numbers indicate higher tiers.

icon string The URL for the icon associated with the tier.You can utilize this icon URL to display tier badges or indicators in your own custom interface, such as on customer profiles.

benefits array It contains a list of rewards associated with the tier, each offering specific advantages to the customer. This array includes various types of benefits.

benefits object

type string Indicates the type of benefit the customer will receive. The possible values are:

  • Custom Benefits: Offers tailored and custom rewards to offer customization for specific customer preferences or behaviors.

  • Lifetime Reward: A benefit that can be used once at any time during the customer's lifetime with Gameball, as long as they remain in this tier.

  • Loyalty Points Earning Custom Configuration:Enables customized settings for how customers earn loyalty points based on their spending amount.

  • Entry Reward: A one-time reward granted to customers upon joining this tier.

rankReward number The score rewarded for the customer as a reward.

walletReward number The number of points the customer will earn for this reward.

walletRewardFactor number This is a multiplier factor that indicates how the customer on their tier will be rewarded for each unit of currency they spend. This is returned for the benefits of type Loyalty Points Earning Custom Configuration.

Example : If a tier has a walletRewardFactor of 2, it means any customer on this tier will earn 2 loyalty points for every $1 they spend. Therefore, if the customer spends $100, they would receive 200 loyalty points as a reward.

couponReward object A coupon object that is awarded to the customer.

  • couponReward.couponType string The type of coupon applied. Possible values include:

    • free_shipping

    • percentage_discount

    • fixed_discount

    • fixed_rate_discount

    • free_product

    • custom

  • couponReward.discountValue number The value of the discount provided by the coupon in case the coupon type is fixed_discount , percentage_discount or fixed_rate_discount.

  • couponReward.product.productId string The unique identifier for the product.

  • couponReward.product.productName string The name of the product.

  • couponReward.product.variantId string The unique identifier for the product variant.

  • couponReward.product.variantName string The name of the product variant.

  • coucouponRewardpon.product.productDisplayName string The display name associated with the product that configured on the dashboard based on required language.

  • couponReward.collections array A list of collection IDs that the coupon can be applied to.

  • couponReward.collections.collectionId string The unique identifier for the collection.

  • couponReward.collections.collectionName string The name for the collection.

  • couponReward.group.handle string A unique identifier used to reference the coupon group in the system.

  • couponReward.group.title string The title of the coupon group.

  • couponReward.group.url string The URL for the coupon group.

  • couponReward.group.iconPath string The path to the icon of the coupon group.

  • couponReward.group.description string A description of the coupon group.

  • couponReward.group.maxPerCustomer number The maximum number of times a customer can use the coupon.

Example: 5 indicates that each customer can redeem this coupon up to 5 times.

  • couponReward.group.startDate datetime The date when the coupons within this coupon group will become active and valid for redemption.

  • couponReward.group.expiryDate datetime The date when the coupons within this coupon group will expire and no longer be valid for redemption.

  • couponReward.group.isAvailable boolean Indicates whether the coupon group is currently available.

  • couponReward.group.isActive boolean Indicates whether the coupon group is currently active.

  • couponReward.options.name string The name of the reward rule configured on the dashboard based on required language.

  • couponReward.options.expiryAfter number The number of days after creation that the coupon will expire.

    Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

  • couponReward.options.usageLimit number The maximum number of times a single coupon can be used.

    Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

  • couponReward.options.capping number The maximum discount value a coupon can provide, regardless of the order amount.

    Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

  • couponReward.options.minOrderValue number The minimum order amount required to apply the coupon.

    Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

  • couponReward.options.codePrefix string TThe prefix that will be added to the beginning of the generated coupon code.

    Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".

  • couponReward.options.redeemInstructions string The instructions on how the customer can redeem the coupon.

    Example: "Enter the coupon code at checkout to apply the discount."

Sample Response

[
    {
        "name": "Basic",
        "minProgress": 0,
        "order": 1,
        "icon": "https://cdn.gameball.co/uploads/gb-library/levels-icons/level-a1.webp",
        "benefits": []
    },
    {
        "name": "Gold",
        "minProgress": 190,
        "order": 2,
        "icon": "level-a1",
        "benefits": [
            {
                "type": "Custom Benefits",
                "description": "Golden membership",
                "hyperLink": "https://mywebsite.com/benefits",
                "rankReward": 0,
                "walletReward": 0
            },
            {
                "type": "Entry Reward",
                "rankReward": 0,
                "walletReward": 3000,
            },
            {
                "type": "Loyalty Points Earning Custom Configuration",
                "rewardWalletFactor": 3.0
            }
        ]
    }
]

GET - Referrals Configurations

https://api.gameball.co/api/v4/integrations/configurations/referrals

This API retrieves the referral configuration, including customer and friend rewards, as well as metadata related to the events that trigger referral rewards.

Security: Requires apiKey header

Response

application/json

referralMethod string This specifies who will receive the referral reward when a successful referral is made.

Possible values:

  • CustomerOnly: Only the customer making the referral will receive the reward. The referred friend will not receive any reward.

  • CustomerAndFriend: Both the customer making the referral and the referred friend will receive rewards, encouraging mutual benefit.

eventName string This describes the event that will trigger the referral reward.

Example : if the eventName is set to place_order, the referral reward will be granted when the referred friend completes an order after using the referral link. Other events can also be configured to trigger the reward, depending on your system’s setup.

eventMetaData Object Contains additional metadata about the event that triggers the referral.

eventMetaData object

  • name string The name of the event metadata.

  • operator string The operator used for event metadata (e.g., equals, greater_than).

  • value string The value associated with the event metadata.

friendReward Object The reward details given to the referred friend as part of the referral program.

friendReward object

score number The score awarded to the referred friend.

point number The points awarded to the referred friend.

coupon object A coupon object that is awarded to the referred friend.

  • coupon.couponType string The type of coupon applied. Possible values include:

    • free_shipping

    • percentage_discount

    • fixed_discount

    • fixed_rate_discount

    • free_product

    • custom

  • coupon.discountValue number The value of the discount provided by the coupon in case the coupon type is fixed_discount , percentage_discount or fixed_rate_discount.

  • coupon.product.productId string The unique identifier for the product.

  • coupon.Reward.product.productName string The name of the product.

  • coupon.product.variantId string The unique identifier for the product variant.

  • coupon.product.variantName string The name of the product variant.

  • coupon.product.productDisplayName string The display name associated with the product that configured on the dashboard based on required language.

  • coupon.collections array A list of collection IDs that the coupon can be applied to.

  • coupon.collections.collectionId string The unique identifier for the collection.

  • coupon.collections.collectionName string The name for the collection.

  • coupon.group.handle string A unique identifier used to reference the coupon group in the system.

  • coupon.group.title string The title of the coupon group.

  • coupon.group.url string The URL for the coupon group.

  • coupon.group.iconPath string The path to the icon of the coupon group.

  • coupon.group.description string A description of the coupon group.

  • coupon.group.maxPerCustomer number The maximum number of times a customer can use the coupon.

Example: 5 indicates that each customer can redeem this coupon up to 5 times.

  • coupon.group.startDate datetime The date when the coupons within this coupon group will become active and valid for redemption.

  • coupon.group.expiryDate datetime The date when the coupons within this coupon group will expire and no longer be valid for redemption.

  • coupon.group.isAvailable boolean Indicates whether the coupon group is currently available.

  • coupon.group.isActive boolean Indicates whether the coupon group is currently active.

  • coupon.options.name string The name of the reward rule configured on the dashboard based on required language.

  • coupon.options.expiryAfter number The number of days after creation that the coupon will expire.

    Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

  • coupon.options.usageLimit number The maximum number of times a single coupon can be used.

    Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

  • coupon.options.capping number The maximum discount value a coupon can provide, regardless of the order amount.

    Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

  • coupon.options.minOrderValue number The minimum order amount required to apply the coupon.

    Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

  • coupon.options.codePrefix string TThe prefix that will be added to the beginning of the generated coupon code.

    Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".

  • coupon.options.redeemInstructions string The instructions on how the customer can redeem the coupon.

    Example: "Enter the coupon code at checkout to apply the discount."

customerReward Object The reward details given to the customer as part of the referral program.

customerReward object

score number The score awarded to the customer.

point number The points awarded to the customer.

coupon object A coupon object that is awarded to the customer.

  • coupon.couponType string The type of coupon applied. Possible values include:

    • free_shipping

    • percentage_discount

    • fixed_discount

    • fixed_rate_discount

    • free_product

    • custom

  • coupon.discountValue number The value of the discount provided by the coupon in case the coupon type is fixed_discount , percentage_discount or fixed_rate_discount.

  • coupon.product.productId string The unique identifier for the product.

  • coupon.Reward.product.productName string The name of the product.

  • coupon.product.variantId string The unique identifier for the product variant.

  • coupon.product.variantName string The name of the product variant.

  • coupon.product.productDisplayName string The display name associated with the product that configured on the dashboard based on required language.

  • coupon.collections array A list of collection IDs that the coupon can be applied to.

  • coupon.collections.collectionId string The unique identifier for the collection.

  • coupon.collections.collectionName string The name for the collection.

  • coupon.group.handle string A unique identifier used to reference the coupon group in the system.

  • coupon.group.title string The title of the coupon group.

  • coupon.group.url string The URL for the coupon group.

  • coupon.group.iconPath string The path to the icon of the coupon group.

  • coupon.group.description string A description of the coupon group.

  • coupon.group.maxPerCustomer number The maximum number of times a customer can use the coupon.

Example: 5 indicates that each customer can redeem this coupon up to 5 times.

  • coupon.group.startDate datetime The date when the coupons within this coupon group will become active and valid for redemption.

  • coupon.group.expiryDate datetime The date when the coupons within this coupon group will expire and no longer be valid for redemption.

  • coupon.group.isAvailable boolean Indicates whether the coupon group is currently available.

  • coupon.group.isActive boolean Indicates whether the coupon group is currently active.

  • coupon.options.name string The name of the reward rule configured on the dashboard based on required language.

  • coupon.options.expiryAfter number The number of days after creation that the coupon will expire.

    Example: If a coupon expires after 14 days, the customer must use it within that period to receive the discount.

  • coupon.options.usageLimit number The maximum number of times a single coupon can be used.

    Example: If a coupon has a usage limit of 5, it can be redeemed up to 5 times before it becomes invalid.

  • coupon.options.capping number The maximum discount value a coupon can provide, regardless of the order amount.

    Example: If a coupon offers 20% off with a capping of $50, the discount will not exceed $50, even if 20% of the order total is higher.

  • coupon.options.minOrderValue number The minimum order amount required to apply the coupon.

    Example: If a coupon has a minimum order value of $100, the customer must spend at least $100 to use the discount.

  • coupon.options.codePrefix string TThe prefix that will be added to the beginning of the generated coupon code.

    Example: If the prefix is "SUMMER", the generated coupon codes might look like "SUMMER12345" or "SUMMERDISCOUNT".

  • coupon.options.redeemInstructions string The instructions on how the customer can redeem the coupon.

    Example: "Enter the coupon code at checkout to apply the discount."

extraReward Object It contains all the details of the reward (like the friendReward Object) that will be awarded to the customer as a a bonus on top of the regular reward) for every X friend referred.

  • extraReward.forEvery number This defines the number of friends a customer needs to refer in order to earn the extraReward. For example, if the value of forEvery is set to 5, the customer will receive the extra reward for every 5 friends they successfully refer. This acts as a bonus on top of the regular reward, incentivizing more referrals.

Sample Response

{
    "referralMethod": "CustomerAndFriend",
    "eventName": "place_order",
    "eventMetaData": {
        "name": "number_of_products",
        "operator": "equals",
        "value": "3"
    },
    "customerReward": {
        "extraReward": {
            "forEvery": 3,
            "score": 0,
            "point": 500,
            "coupon": null
        },
        "score": 0,
        "point": 200,
        "coupon":null
        
    },
    "friendReward": {
        "score": 0,
        "point": 0,
        "coupon": {
            "couponType": "Percentage",
            "discountValue": 10.0,
            "minOrderValue": 50.0,
            "product": "Any",
            "collections": ["Summer Collection", "Spring Sale"],
            "options": {
                "expiryAfter": "2025-12-31",
                "usageLimit": 1,
                "usedCount": 0,
                "capping": 100,
                "minOrderValue": 50.0,
                "combinesWith": {
                    "orderDiscounts": true,
                    "productDiscounts": false,
                    "shippingDiscounts": true
                },
                "productId": "ABC123",
                "productUrl": "https://example.com/product/ABC123",
                "productName": "Sample Product",
                "variantId": "VAR456",
                "variantName": "Red",
                "productDisplayName": "Sample Product - Red",
                "couponPrefix": "SUMMER",
                "collections": ["Featured", "Best Sellers"],
                "productDisplayNames": ["Sample Product"],
                "hasCollections": true,
                "platforms": ["Web", "Mobile"],
                "redeemInstructions": ["Apply at checkout"],
                "instructions": "Use this coupon code at checkout to avail the discount.",
                "source": "Referral Program",
                "couponName": "SUMMER10"
            }
        }
    }
}
PreviousReward ConfigurationsNextWidget Configuration

Last updated