Skip to main content
GET
cURL

Cashback Configurations

This API returns everything that decides how many points a customer earns on an order: the default earning rule and which order lines it covers, tier rules, custom rules, and points multiplier campaigns. Use it to show customers what an order will earn before they place it. If customerId is provided, the response is narrowed to the rules and campaigns that apply to that customer. See Filtering by customer.
Security: Requires apikey header.

What the response contains

Every rate (default, tier, and each custom rule reward) uses the same four fields. A customer earns rewardWalletFactor points for every amountRewardThreshold spent, and rewardFactor is that rate expressed as a percentage of the amount spent.

How an order line earns points

Gameball works out the points for each order line in three steps:
  1. Pick the base rate. Use the customer’s tier rule from tierCashbackRules, or defaultCashbackRule if their tier has none. The line earns only if defaultCashbackRule.eligibility allows it:
    • All: every line earns.
    • Include: only lines that match conditions earn.
    • Exclude: every line earns except those that match conditions.
    Under Include and Exclude, shipping always earns. excludeShippingAndFees and excludeTaxes remove those amounts from what earns.
  2. Apply a custom rule. If the line matches a rule in customCashbackRules, the rule’s reward for the customer’s tier replaces the base rate. If several rules match, the one that earns the most applies.
  3. Apply a multiplier campaign. If the line matches a campaign in pointsMultiplierCampaigns, the line’s points are multiplied by the campaign’s multiplier, and its score by rankMultiplier. If several campaigns match, the one with the highest multiplier applies.

Custom rule rewards per tier

A custom rule has one entry in rewards per tier it was configured for:
  • A reward with tierName: null applies to every tier that has no reward of its own on that rule.
  • A reward with a tier name applies only to that tier, and overrides the null reward for it.
Here, Gold customers earn 3 points per 1 spent on matching lines, and customers in every other tier earn 2.

Multiplier brackets

A campaign’s multiplier is either Flat or Brackets:
  • Flat: one multiplier, in value.
  • Brackets: the multiplier depends on the order value named in basedOn, for example totalPrice. Each bracket is { from, to, multiplier }, and to: null means no upper limit.
Brackets follow these rules:
  • Both bounds are inclusive. A bracket matches when from <= value <= to, or value >= from when to is null.
  • On a shared bound, the higher multiplier wins. A value equal to one bracket’s to and the next bracket’s from matches both, and the higher multiplier applies.
  • A value outside every bracket gets no multiplier from that campaign. The order earns at its normal rate.
For example, with these brackets on totalPrice:

Conditions and operators

conditions (on eligibility, custom rules, and campaigns) use the field names you send in the Order API payload. Line-item fields start with lineItems., for example lineItems.sku, lineItems.collection or lineItems.category. Other fields include totalPrice, channel, merchant.uniqueId and extra.<key>. values is a list of alternatives: a condition matches if the field matches any one of them. logicalOperator (on a condition) and audienceOperator (on a campaign) are always AND or OR. Both are null when there’s nothing to combine:
  • logicalOperator is null when the list has a single condition.
  • audienceOperator is null when audience is empty or has a single entry. An empty audience means every customer.

Filtering by customer

When you pass customerId: defaultCashbackRule is the same with or without customerId. Campaign name and description are returned in the language of the lang header.

Authorizations

apikey
string
header
required

Headers

lang
string

Language code for campaign names and descriptions, for example en or ar. Falls back to the default language when a campaign has no translation.

Query Parameters

customerId
string

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: tierCashbackRules holds only the customer's tier; customCashbackRules holds only rules that reward the customer's tier, each with the single reward that applies to them; pointsMultiplierCampaigns holds only the campaigns the customer can currently achieve.

Response

200 - application/json

Cashback configurations retrieved successfully

defaultCashbackRule
object

The program's default earning rule. It applies to every customer whose tier has no rule of its own in tierCashbackRules.

tierCashbackRules
object[]

Tier-specific earning rules. A customer in a listed tier earns with that tier's rule instead of defaultCashbackRule. With customerId, only the customer's tier is returned.

customCashbackRules
object[]

Custom earning rules. When an order line matches a rule's conditions, the rule's reward replaces the default or tier rate for that line. If several rules match a line, the one that earns the most applies.

pointsMultiplierCampaigns
object[]

Points multiplier campaigns. A campaign multiplies the points an order line earns under its default, tier or custom rule. If several campaigns match a line, the one with the highest multiplier applies. Without customerId, every multiplier campaign is returned with its isActive and activation. With customerId, only the campaigns that customer can currently achieve are returned, as in the Campaigns configuration API.