← API Index

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:

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 interesting per-reward fields:

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:

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