Bonus System (Bonus Points)
The bonus system adds gamification to the sales process, following patterns known from other online shop systems: customers collect points for the turnover they generate, and once enough points are collected they can claim a reward.
The rules are defined per bonus campaign:
- Points are earned for generated turnover (number of items or sum);
point_pricetells how much turnover earns one point. - A campaign may count only specific items — regional items only (
item_regio), or items of a given group, subgroup or rubric (item_group,item_subgroup,item_rubric;0means no restriction). - A campaign may be time limited (
ddate_from/ddate_until, based on delivery dates). - A campaign may be limited to certain customer groups, and it may require the customer
to actively opt in (
customer_must_apply). - A campaign can offer several rewards at different point thresholds (something for 100 points, something else for 200 points).
- A reward is either an item present (
itemid) or a discount (discount), optionally granted for a limited period (discount_period). - After a reward was granted, point counting deducts or may restart from 0.
Point assignment and reward processing happen asynchronously in the back office — the API's job is to display the current state, and to submit the customer's opt-in and claim requests. Plan your UI around that (see Claiming a reward).
1. List the available campaigns
/api/system/bonus/list2 returns the
BonusCampaign objects. It works without
authentication, but then only campaigns that are not limited by customer group are
returned. When called authenticated, only the campaigns available to that customer are
shown. (/api/system/bonus/list is the older version without infourl.)
A campaign may carry an infourl, a page of the business explaining the campaign. Offer it
as a "more info" link that opens in a new tab; without one, the description is the place
for the details (the std shops fold it out under "Mehr Infos" in the cart banner).
Use this e.g. for a public marketing page ("collect points, get rewards") or a teaser for guests.
2. Show the customer's campaigns, points and rewards
The authenticated user profile /api/user32 contains the bonus data for the logged-in customer:
- the BonusCampaign list — campaigns available to this customer,
- the BonusReward list — one entry per reward, linked to
its campaign via
bid, - the BonusDiscount list — discounts that were granted
through bonus rewards. They are emitted as a separate type so you can distinguish
them from the customer's regular discounts; a reward references its discount by id
(
BonusReward.discount).
The interesting per-reward fields:
current_points— the customer's current point balance,points— points needed for this reward,state— progress towards the reward in percent; it can exceed 100%, meaning the reward is claimable,redemption_status—truewhile a claim is submitted but not yet confirmed by the back office (see below),redemption_count— how often the customer already redeemed (claimed) this reward, including a claim that is still pending. Available from BonusReward v4 (/api/user32); use it e.g. for "already redeemed 2x" labels. Rejected redemptions are not counted. On a system that does not keep a redemption history yet, redemptions of more than 80 days ago are not covered by this count.last_redemption/last_redemption_state— when the customer redeemed this reward the last time and what became of it:0requested (the back office has not processed it yet,redemption_statusistrue),1processed,2rejected by the back office,-1never redeemed. Available from BonusReward v5 (/api/user38); use it for "redeemed on ..., being processed" / "last redeemed on ..." / "could not be granted" lines.has_image— iftrue, a reward image can be fetched through the image proxy with typebr(e.g.br.px?bs.i=<reward id>).
Note that the profile data is refreshed on login — a point balance shown there updates live during the session only after an order or after a bonus claim activity. In that case, refresh the date from the user call.
3. Opt into a campaign
If a campaign has customer_must_apply = true, the customer participates only after
applying. Offer a "participate" button (typically in the profile / discounts section)
and call /api/client/applybonus with the bonus_id.
The call requires an authenticated customer.
Campaigns without customer_must_apply need no action — eligible customers
participate automatically.
4. Claim a reward
Once state reaches 100% for a reward, the customer may claim it via
/api/client/claimbonus with bonus_id and
reward_id. Without reward_id the claim is for the campaign's reward valid today with the
lowest points (for a campaign with a single reward, that one).
Things not to forget:
-
Check the result, not the HTTP status.
claimbonusandapplybonusanswer HTTP 200 also when they refuse; theBonusResultrow'sresultisokor the error id (not_enough_points,pending, ...). -
Claiming is asynchronous. The claim is queued for the back office; until it is confirmed there, the reward's
redemption_statusstaystrue. Tell the customer that the reward is "being processed" rather than pretending immediate delivery. -
While a claim is pending, a repeated claim for the same reward is rejected with the
pendingerror — hide or disable the claim button in that state. -
Handle the
not_enough_pointserror: another device/session may have claimed in the meantime, or the displayed balance was stale. -
Only offer a reward inside its own period (
start_ddate/end_ddate, both optional, inclusive). Outside of it the claim is rejected withnot_current. -
Once confirmed, a granted discount shows up with the customer's discounts (see the BonusDiscount list above) and applies to future orders; an item present is added to a delivery by the back office.
Setting points (admin)
/api/admin/setbonus lets an admin replace a
customer's point balance for a campaign (bonus_id, cid, points) — useful for development,
support cases, goodwill points or migrations. Admin role required.
Ideas
- Show a progress bar per reward ("only 10 more points until your reward!") computed
from
points,current_pointsandstate— incentive information is the main frontend value of this feature. - Show the available campaigns with name and description in the profile / discounts
section, together with the opt-in button for
customer_must_applycampaigns. - Estimate and display "this order will earn about X points" in the cart, using the
campaign's
point_price,movand item filters on the current cart content. Treat it as an estimate — the authoritative point calculation happens in the back office. - Highlight items that count towards a running campaign (e.g. a badge on regional items
when a
item_regiocampaign runs).
Related
- understanding-object-relation — how the compact response format and object references work
- item-details — displaying items, e.g. an item offered as a reward