Reward Configurations

Retrieve essential reward settings like cashback, redemption, and coupon configurations. These APIs help display details about how customers can earn and redeem rewards within your program.

Available APIs

GET - Cashback Configurations

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

This API call retrieves your cashback configurations, providing essential details about how cashback rewards are structured and managed in Gameball. If the customerId is provided, the API will return any special cashback rules associated with the customer’s tier, including potential bonuses or customized reward factors specific to that customer.

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 database ID, random string, email or anything that uniquely identifies the customer.

If provided, the response will return the cashback rules specific to this customer’s tier, reflecting any special configurations or bonuses this customer is eligible for based on their tier cashback rules.

Response

application/json

defaultCashbackRule Object The default cashback rule applied to all customers if no tier-specific rules are available.

defaultCashbackRule object

amountRewardThreshold number The minimum amount that must be spent by the customer to qualify for a cashback reward. Transactions below this threshold will not earn any cashback, incentivizing higher spending. Example: If the amountRewardThreshold is set to $50, a customer must spend at least $50 to be eligible for cashback rewards.

rewardWalletFactor number The factor used to calculate the amount of loyalty points added to the customer’s wallet based on the cashback amount earned from transactions. This factor determines how many points customers receive relative to the cashback they earn. Example: If a customer receives $10 in cashback and the rewardWalletFactor is 2, the customer will earn 20 loyalty points (2 times the cashback amount).

rewardRankFactor number In case your tiering-up method is based on score, this factor determines the score rewarded for each unit of currency your customer spends. It directly impacts how quickly customers can progress through tiers in your loyalty program. Example: If the rewardRankFactor is set to 2, the customer earns 2 score points for every 1 USD spent.

rewardFactor number

It is a calculated value that determines the reward a customer earns relative to their spending. It considers the following:

  • AmountRewardThreshold (Minimum Amount Required): The minimum amount a customer must spend to qualify for rewards.

  • RewardWalletFactor (Earning Rate): The factor representing how many points or cashback the customer earns for each unit of currency spent.

  • RedemptionFactor (Monetary Value of Points): The value assigned to each point, reflecting how it translates into cashback.

Formula: Reward Factor=( Amount Reward Threshold/ Reward Wallet Factor ​) ×Redemption Factor×100

Example: For instance, if:

  • Reward Wallet Factor = 10 (points earned per $1 spent)

  • Amount Reward Threshold = 50 (minimum $50 must be spent to earn rewards)

  • Redemption Factor = 0.2 (20% redemption rate)

Reward Factor=(50/10​×0.2)×100=4

This indicates that the customer earns a reward equivalent to 4% of their spending as a cashback reward when the conditions are met.

In essence, the Reward Factor represents a percentage of what the customer earns as a cashback reward based on their spendings.This helps quantify how much a customer benefits from their purchases, providing clarity on the rewards earned through your loyalty program.

tierCashbackRules array A list of tier-specific cashback rules, which override the default cashback rule for customers in a specific tier.

tierCashbackRules object

tierName string The name of the tier that has its own cashback rule.

amountRewardThreshold number The minimum amount that must be spent by the customer to qualify for a cashback reward. Transactions below this threshold will not earn any cashback, incentivizing higher spending. Example: If the amountRewardThreshold is set to $50, a customer must spend at least $50 to be eligible for cashback rewards.

rewardWalletFactor number The factor used to calculate the amount of loyalty points added to the customer’s wallet based on the cashback amount earned from transactions. This factor determines how many points customers receive relative to the cashback they earn. Example: If a customer receives $10 in cashback and the rewardWalletFactor is 2, the customer will earn 20 loyalty points (2 times the cashback amount).

rewardRankFactor number In case your tiering-up method is based on score, this factor determines the score rewarded for each unit of currency your customer spends. It directly impacts how quickly customers can progress through tiers in your loyalty program. Example: If the rewardRankFactor is set to 2, the customer earns 2 score points for every 1 USD spent.

rewardFactor number

It is a calculated value that determines the reward a customer earns relative to their spending. It considers the following:

  • AmountRewardThreshold (Minimum Amount Required): The minimum amount a customer must spend to qualify for rewards.

  • RewardWalletFactor (Earning Rate): The factor representing how many points or cashback the customer earns for each unit of currency spent.

  • RedemptionFactor (Monetary Value of Points): The value assigned to each point, reflecting how it translates into cashback.

Formula: Reward Factor=( Amount Reward Threshold/ Reward Wallet Factor ​) ×Redemption Factor×100

Example: For instance, if:

  • Reward Wallet Factor = 10 (points earned per $1 spent)

  • Amount Reward Threshold = 50 (minimum $50 must be spent to earn rewards)

  • Redemption Factor = 0.2 (20% redemption rate)

Reward Factor=(50/10​×0.2)×100=4

This indicates that the customer earns a reward equivalent to 4% of their spending as a cashback reward when the conditions are met.

In essence, the Reward Factor represents a percentage of what the customer earns as a cashback reward based on their spendings.This helps quantify how much a customer benefits from their purchases, providing clarity on the rewards earned through your loyalty program.

Sample Response

{
    "defaultCashbackRule": {
        "rewardFactor": 10.0,
        "amountRewardThreshold": 1.0,
        "rewardWalletFactor": 1.0,
        "rewardRankFactor": 1.0
    },
    "tierCashbackRules": [
        {
            "tierName": "Gold",
            "rewardFactor": 0.0,
            "amountRewardThreshold": 1.0,
            "rewardWalletFactor": 20.0,
            "rewardRankFactor": 1.0
        }
    ]
}

GET - Redemption Configurations

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

This API retrieves the configurations and rules associated with how customers can redeem points for discounts, coupons, or other rewards.

Security: Requires apikey and secretkey headers.

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 will return redemption configurations that match the customer based on various criteria, such as RFM , tiers, segments and specific customer attributes. This approach ensures that the redemption options are personalized and relevant to each customer's unique profile and engagement history.

Response

application/json

redemptionFactor number

This factor indicates the value of each loyalty point in terms of currency, defining how many currency units can be obtained by redeeming points.

Example: If the redemptionFactor is set to 0.1,this means that a customer can redeem 10 points for 1 USD.

redemptionRules array

A list of redemption rules that define how points can be redeemed for discounts and coupons.

Defines the rules for redeeming points, including points required, value of points, applicable coupons, and eligibility criteria.

Example: a redemption rule may allow points to be redeemed for a free product, free shipping, percentage-based discounts, or fixed-amount discounts.

redemptionRules object

id number The unique identifier for the redemption rule.

pointsToRedeem number The specific number of points needed for redemption. If null, the rule applies to all points.

valueOfPoint number The value of a single point in terms of monetary value for redemption.

ruleType string The type of rule governing the redemption. Possible values include:

  • free_shipping_settings

  • percentage_discount_settings

  • free_product_settings

  • fixed_rate_settings

coupon object

Defines the coupon associated with the redemption rule, if applicable.

  • 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.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 (only appears in the dashboard).

  • 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 redemption 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 The 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."

image string

A URL or file path for an image representing the redemption rule.

creationDate datetime

The date when the redemption rule was created.

isActive boolean

Indicates whether the redemption rule is currently active and can be used to generate new coupons or not.

  • true → The rule is active, and new coupons can be created and redeemed.

  • false → The rule is inactive, meaning no new coupons can be generated. However, previously created coupons will still be valid and can be redeemed.

Example: If isActive is false, customers cannot create new coupons, but any coupons generated before the rule became inactive can still be used.

Sample Response


{
  "redemptionFactor": 0.1,
  "redemptionRules": [
    {
      "id": 2138,
      "pointsToRedeem": 100,
      "valueOfPoint": 25.0,
      "ruleType": "percentage_discount_settings",
      "coupon": {
        "couponType": "percentage_discount",
        "discountValue": 25.0,
        "product": null,
        "collections": [
          {
            "collectionId": "455218036961",
            "collectionName": "Automated Collection"
          }
        ],
        "options": {
          "name": "Redemption Rule Name",
          "expiryAfter": 14,
          "usageLimit": 2,
          "capping": 50,
          "minOrderValue": 150.0,
          "combinesWith": {
            "orderDiscounts": true,
            "productDiscounts": true,
            "shippingDiscounts": true
          },
          "codePrefix": "SUMMER",
          "platforms": [],
          "redeemInstructions": "Enter the coupon code at checkout to apply the discount."
        }
      },
      "image": "https://s3.us-east-2.amazonaws.com/gameball.stg.uploads/uploads%2fClient_2933%2f936f65d8-e06d-4e28-b423-b5282999801bgameball.webp",
      "creationDate": "2025-02-10T10:12:16.783408",
      "isActive": true
  ]
}

GET - Coupon Configurations

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

This API call retrieves your coupon configurations, including details about how coupons are structured, authenticated, and mapped within Gameball.

Security: Requires apikey and secretkey headers.

Response

application/json

url string The URL where the coupon configuration is applied.

method string The HTTP method used for the coupon configuration process (e.g., POST, PUT or GET).

queryParams array List of query parameters used in the request.

queryParams object

key string The key used in the query parameter.

value string The value of the query parameter.

headers array List of headers used in the request.

headers object

key string The header key.

value string The header value.

payload string The request payload format or template.

couponMapping object A dictionary mapping coupon types to specific keys in your system.

enableFreeProduct boolean Indicates whether free product coupons are enabled.

enableFixedRate boolean Indicates whether fixed-rate discount coupons are enabled.

enableFreeShipping boolean Indicates whether free shipping coupons are enabled.

enablePercentage boolean Indicates whether percentage-based discount coupons are enabled.

platforms array List of platforms for which the coupon configurations are applied.

platforms object

displayName string The display name of the platform.

value string The internal value used for the platform.

Sample Response

{
  "url": "https://api.mywebsite.com/coupons",
  "method": "POST",
  "queryParams": [
    {
      "key": "appId",
      "value": "12345"
    }
  ],
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer token"
    }
  ],
  "payload": "{ \"couponCode\": \"DISCOUNT10\" }",
  "couponMapping": {
    "fixed": "fixed_discount",
    "percentage": "percentage_discount",
    "freeProduct": "free_product",
    "freeShipping": "free_delivery"
  },
  "enableFreeProduct": true,
  "enableFixedRate": true,
  "enableFreeShipping": true,
  "enablePercentage": true
}

PUT - Update Coupon Configurations

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

This API call updates your coupon configurations, allowing you to modify details about how coupons are structured, authenticated, and mapped within Gameball.

Security: Requires apikey and secretkey headers.

Request

Body

application/json

url string Required The URL of your API endpoint where coupons are created. Gameball will send requests to this endpoint whenever a coupon needs to be generated.

method string Required The HTTP method used to send requests to the coupon creation endpoint. Allowed values are POST, PUT or GET.

queryParams array Optional List of query parameters used in the request. Those that will be appended to the URL endpoint. These are used to pass specific parameters required by your coupon system as part of the URL itself, often for identification, filtering, or configuration purposes. Each query parameter is defined by a key-value pair, allowing you to tailor requests based on requirements in your API.

queryParams object

key string Required The key used in the query parameter.

value string Required The value of the query parameter.

headers array Optional List of headers used in the request.

headers object

key string Required The header key.

value string Required The header value.

Example:

[
  {
    "Key": "X-Client-Version",
    "Value": "1.0"
  }
]

In this example,TheX-Client-Version may specify the client version for API versioning or tracking.

payload string Optional This specifies the structure of the JSON body Gameball will send to your endpoint when creating a coupon. Since different systems may use varying parameter names and structures, you can customize this payload to align with your system's requirements.

You should define the JSON payload with placeholders that Gameball will replace with actual data when sending the request.

Example:

{
  "customerId": "{{playerUniqueId}}",
  "amount": "{{value}}",
  "code": "{{code}}"
}

In this setup:

  • {{playerUniqueId}}: Placeholder for the customer's ID .

  • {{value}}: Placeholder for the coupon’s discount value.

  • {{code}}: Placeholder for the generated coupon code.

The attribute names inside curly brackets represents coupon attributes in Gameball, these names are fixed, these name are mapped to their respective attributes in your coupon system, for example, If a customer with id CUS_12345 redeems a coupon worth 50 EGP with the code 50EGPOFF, Gameball backend will replace the keys inside each curly brackets {{}} with actual values so the payload sent after replacing attribute values based each attribute name should looks like :

{
  "customerId": "CUS_12345",
  "amount": "50",
  "code": "50EGPOFF"
}

If you changed the name of 'customerId' attribute to id , then the payload configuration should updated and look like this

{
 "id": "{{playerUniqueId}}",
 "amount":"{{value}}"
 "code": "{{code}}",
}

This allows Gameball to dynamically generate and send requests based on your configurations.

couponMapping object Optional A dictionary mapping coupon attributes to specific keys in your system.

couponMapping object

fixed string Optional The internal naming for the fixed discount codes in your system.

percentage string Optional The internal naming for the percentage discount codes in your system.

freeProduct string Optional The internal naming for the free product discount codes in your system.

freeShipping string Optional The internal naming for the free shipping discount codes in your system.

enableFreeProduct boolean Indicates whether free product coupons are enabled.

enableFixedRate boolean Indicates whether fixed-rate discount coupons are enabled.

enableFreeShipping boolean Indicates whether free shipping coupons are enabled.

enablePercentage boolean Indicates whether percentage-based discount coupons are enabled.

platforms array Optional List of platforms for which the coupon configurations are applied in your system.

platforms object

displayName string Required The display name of the platform.

value string Required The internal value used for the platform.

Sample Request

{
  "url": "https://api.mywebsite.com/coupons",
  "method": "POST",
  "queryParams": [
    {
      "key": "appId",
      "value": "12345"
    }
  ],
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer token"
    }
  ],
  "payload": "{ \"couponCode\": \"DISCOUNT10\" }",
  "couponMapping": {
    "fixed": "fixed_discount",
    "percentage": "percentage_discount",
    "freeProduct": "free_product",
    "freeShipping": "free_delivery"
  },
  "enableFreeProduct": true,
  "enableFixedRate": true,
  "enableFreeShipping": true,
  "enablePercentage": true
}
PreviousConfigurationsNextProgram Configurations

Last updated