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.
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
customerIdstringOptional
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
defaultCashbackRuleObject
The default cashback rule applied to all customers if no tier-specific rules are available.
defaultCashbackRule object
amountRewardThresholdnumber
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.
rewardWalletFactornumber
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).
rewardRankFactornumber
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.
rewardFactornumber
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.
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.
tierCashbackRulesarray
A list of tier-specific cashback rules, which override the default cashback rule for customers in a specific tier.
tierCashbackRules object
tierNamestring
The name of the tier that has its own cashback rule.
amountRewardThresholdnumber
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.
rewardWalletFactornumber
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).
rewardRankFactornumber
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.
rewardFactornumber
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.
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.
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
customerIdstringOptional
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
idnumber
The unique identifier for the redemption rule.
pointsToRedeemnumber
The specific number of points needed for redemption. If null, the rule applies to all points.
valueOfPointnumber
The value of a single point in terms of monetary value for redemption.
ruleTypestring
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.couponTypestring
The type of coupon applied. Possible values include:
free_shipping
percentage_discount
fixed_discount
fixed_rate_discount
free_product
custom
coupon.discountValuenumber
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.productIdstring
The unique identifier for the product.
coupon.product.productNamestring
The name of the product.
coupon.product.variantIdstring
The unique identifier for the product variant.
coupon.product.variantNamestring
The name of the product variant.
coupon.product.productDisplayNamestring
The display name associated with the product that configured on the dashboard based on required language.
coupon.collectionsarray
A list of collection IDs that the coupon can be applied to.
coupon.collections.collectionIdstring
The unique identifier for the collection.
coupon.collections.collectionNamestring
The name for the collection.
coupon.group.handlestring
A unique identifier used to reference the coupon group in the system (only appears in the dashboard).
coupon.group.titlestring
The title of the coupon group.
coupon.group.urlstring
The URL for the coupon group.
coupon.group.iconPathstring
The path to the icon of the coupon group.
coupon.group.descriptionstring
A description of the coupon group.
coupon.group.maxPerCustomernumber
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.startDatedatetime
The date when the coupons within this coupon group will become active and valid for redemption.
coupon.group.expiryDatedatetime
The date when the coupons within this coupon group will expire and no longer be valid for redemption.
coupon.group.isAvailableboolean
Indicates whether the coupon group is currently available.
coupon.group.isActiveboolean
Indicates whether the coupon group is currently active.
coupon.options.namestring
The name of the redemption rule configured on the dashboard based on required language.
coupon.options.expiryAfternumber
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.usageLimitnumber
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.cappingnumber
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.minOrderValuenumber
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.codePrefixstring
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.redeemInstructionsstring
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.
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
urlstringRequired
The URL of your API endpoint where coupons are created. Gameball will send requests to this endpoint whenever a coupon needs to be generated.
methodstringRequired
The HTTP method used to send requests to the coupon creation endpoint. Allowed values are POST, PUT or GET.
queryParamsarrayOptional
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
keystringRequired
The key used in the query parameter.
valuestringRequired
The value of the query parameter.
headersarrayOptional
List of headers used in the request.
headers object
keystringRequired
The header key.
valuestringRequired
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.
payloadstringOptional
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.
{{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 :
