v4.0 (Beta)

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

  • general_settings

startDate datetime The date when the rule becomes active.

endDate datetime The date when the rule expires.

availableTo object

Indicates which customers are eligible to use this redemption rule based on their tier and associated tags.

  • availableTo.tier.id number The unique identifier for the tier that this redemption rule applies to.

  • availableTo.tier.name string The name of the tier that this redemption rule applies to.

  • availableTo.tags array A list of tags associated with the eligibility for this redemption rule.

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

    • free_product

    • fixed_rate_discount

    • 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.minOrderValue number The minimum order value required to use the coupon.

  • 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.productDisplayNames array A list of display names associated with the product.

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

  • coupon.applicableTo.productIds array A list of product IDs that the coupon can be applied to.

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

howToRedeem string

Instructions or information on how to redeem the points for this rule.

Example: "To redeem, enter the coupon code at checkout to apply your discount."

creationDate datetime

The date when the redemption rule was created.

Sample Response


{
  "redemptionFactor": 0.1,
  "redemptionRules": [
    {
      "id": 2138,
      "pointsToRedeem": 100,
      "valueOfPoint": 0.1,
      "ruleType": "fixed_rate_settings",
      "startDate": "2024-10-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z",
      "coupon": {
        "couponType": "fixed_rate_discount",
        "discountValue": 10.0,
        "minOrderValue": 50.0,
        "product": null,
        "applicableTo": {
          "collections": ["electronics", "accessories"],
          "productIds": ["prod_123456", "prod_654321"]
        },
        "group":null
      },
      "availableTo": {
        "tier": {
          "tierId": 5,
          "tierName": "Gold"
        },
        "tags": ["loyal_customer", "frequent_buyer"]
      },
      "howToRedeem": "Apply the coupon code 'HOLIDAY10' at checkout to receive your discount.",
      "creationDate": "2024-09-22T18:48:30.970282"
    }
  ]
}

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 header

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

contentType string The content type of the request (e.g., application/json).

authentication object Authentication details required to access the coupon configuration.

authentication object

type string The type of authentication used (e.g., Basic, Token).

username string Username used for basic authentication.

password string Password used for basic authentication.

token string Token used for authentication if applicable.

values array A collection of additional authentication values.

queryParams array List of query parameters used in the request.

queryParams object

type string The type of query parameter (e.g., string, integer).

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

type string The type of header (e.g., string, integer).

key string The header key.

value string The header value.

payload string The request payload format or template.

couponMapping object A dictionary mapping coupon attributes 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://yourwebsite.co/coupons",
    "method": "POST",
    "contentType": "application/json",
    "authentication": {
        "type": "Basic",
        "username": "admin",
        "password": "password",
        "token": null,
        "values": []
    },
    "queryParams": [
        {
            "type": "string",
            "key": "customerId",
            "value": "12345"
        }
    ],
    "headers": [
        {
            "type": "string",
            "key": "Authorization",
            "value": "Bearer token"
        }
    ],
    "payload": "{ \"couponCode\": \"DISCOUNT10\" }",
    "couponMapping": {
        "discount": "percentage",
        "minOrderValue": "100"
    },
    "enableFreeProduct": true,
    "enableFixedRate": false,
    "enableFreeShipping": true,
    "enablePercentage": true,
    "platforms": [
        {
            "displayName": "Shopify",
            "value": "shopify"
        },
        {
            "displayName": "WooCommerce",
            "value": "woocommerce"
        }
    ]
}

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. Common values are POST or PUT.

contentType string Required The content type of the request that your server is expecting the request to be sent in (e.g., application/json).

authentication object Optional Contains the authentication details required to access the coupon API. This can be set to support different authentication types, such as Basic or Bearer token.

authentication object

type string Optional The type of authentication used (e.g., Basic, Token).

username string Optional Username used for authentication.

password string Optional Password used for authentication.

token string Optional Token used for authentication if applicable.

values array Optional A collection of additional authentication values.

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

type string Required The type of query parameter (e.g., string, integer).

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

type string Required The type of header (e.g., string, integer).

key string Required The header key.

value string Required The header value.

Example:

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

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

payload object 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.

payload object

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

enableFreeProduct boolean Optional Indicates whether free product coupons are enabled in your system.

enableFixedRate boolean Optional Indicates whether fixed-rate discount coupons are enabled in your system.

enableFreeShipping boolean Optional Indicates whether free shipping coupons are enabled in your system.

enablePercentage boolean Optional Indicates whether percentage-based discount coupons are enabled in your system.

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.gameball.co/coupons",
  "method": "POST",
  "contentType": "application/json",
  "authentication": {
    "type": "Basic",
    "username": "admin",
    "password": "password",
    "token": null,
    "values": []
  },
  "queryParams": [
    {
      "type": "string",
      "key": "customerId",
      "value": "12345"
    }
  ],
  "headers": [
    {
      "type": "string",
      "key": "Authorization",
      "value": "Bearer token"
    }
  ],
  "payload": "{ \"couponCode\": \"DISCOUNT10\" }",
  "couponMapping": {
    "discount": "percentage",
    "minOrderValue": "100"
  },
  "enableFreeProduct": true,
  "enableFixedRate": false,
  "enableFreeShipping": true,
  "enablePercentage": true,
  "platforms": [
    {
      "displayName": "Shopify",
      "value": "shopify"
    },
    {
      "displayName": "WooCommerce",
      "value": "woocommerce"
    }
  ]
}
PreviousConfigurationsNextProgram Configurations

Last updated