Cashback Configurations
Retrieve cashback configuration settings for the loyalty program.
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. IfcustomerId is provided, the response is narrowed to the rules and campaigns that apply to that customer. See Filtering by customer.
What the response contains
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:-
Pick the base rate. Use the customer’s tier rule from
tierCashbackRules, ordefaultCashbackRuleif their tier has none. The line earns only ifdefaultCashbackRule.eligibilityallows it:All: every line earns.Include: only lines that matchconditionsearn.Exclude: every line earns except those that matchconditions.
IncludeandExclude, shipping always earns.excludeShippingAndFeesandexcludeTaxesremove those amounts from what earns. -
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. -
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 byrankMultiplier. If several campaigns match, the one with the highest multiplier applies.
Custom rule rewards per tier
A custom rule has one entry inrewards per tier it was configured for:
- A reward with
tierName: nullapplies 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
nullreward for it.
Multiplier brackets
A campaign’smultiplier is either Flat or Brackets:
Flat: one multiplier, invalue.Brackets: the multiplier depends on the order value named inbasedOn, for exampletotalPrice. Each bracket is{ from, to, multiplier }, andto: nullmeans no upper limit.
- Both bounds are inclusive. A bracket matches when
from <= value <= to, orvalue >= fromwhentoisnull. - On a shared bound, the higher multiplier wins. A value equal to one bracket’s
toand the next bracket’sfrommatches both, and the higher multiplier applies. - A value outside every bracket gets no multiplier from that campaign. The order earns at its normal rate.
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:
logicalOperatorisnullwhen the list has a single condition.audienceOperatorisnullwhenaudienceis empty or has a single entry. An emptyaudiencemeans every customer.
Filtering by customer
When you passcustomerId:
defaultCashbackRule is the same with or without customerId.
Campaign name and description are returned in the language of the lang header.Headers
Query Parameters
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
Cashback configurations retrieved successfully
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.