Favourites and individual offers
Most customers of a delivery shop buy the same things again and again, plus a few new ones. The fastest way to a full cart is therefore not the menu but a short, personal list: what I marked, what I usually take, what is due again. The standard shop bundles this in its favourites area. This skill explains its parts and how to offer the same with the API.
The favourites area of the standard shop
The favourites page ("Meine Merkliste") is reached from the heart in the status bar. Above the list, four buttons switch between personal views; the one shown is highlighted:
| Button | Shows | For whom | With the API |
|---|---|---|---|
| Deine Favoriten | everything the customer marked with a heart | logged-on customers with favourites | api/dates + add/drop calls, see below |
| Nicht vergessen | items the customer buys regularly, most due first for the selected delivery date | logged-on customers who have ordered before | api/client/reorderhints |
| Oft in deinen Bestellungen | the items most often in the customer's own orders | logged-on customers who have ordered before | api/client/frequentitems |
| Was andere bestellen | the shop's bestsellers of the last weeks | everybody, also guests | api/bestsellers |
Each button is only shown where it leads to something: a customer without orders gets no "Nicht vergessen", a guest only "Was andere bestellen". With an empty favourites list the page explains the heart and offers the other lists instead. If you want the whole area as it is, embed the shop component, see use-js-components.
Favourites
A Favourite is a reference, not a copy:
| Field | Meaning |
|---|---|
entityType |
Item, Group, SubGroup, Rubric, Assortment, AssortmentGroup or Article |
entityId |
id of that entity |
entityName |
the name at the time it was marked; use it as a fallback label |
Favourites belong to a logged-on customer. Guests have none, and adding one as a guest is refused. A customer can keep up to 300 favourites; beyond that, adding answers with an error.
| Call | Use |
|---|---|
| api/dates | Loads the favourites together with the customer's dates, subscriptions and pauses. You probably load it anyway for the date selection. |
| api/client/addfavourite | Marks an entity: iid (the id), entity (the type) and name (the current display name, kept as fallback). |
| api/client/dropfavourite | Removes it again: iid and entity. |
Both changing calls answer with the same object lists as api/dates, including the updated favourites. Replace
your local list with that answer instead of loading again.
Errors: not_auth (no logged-on customer: offer the logon instead of the heart), parameter_error (id or type
missing), error (could not be added, e.g. the limit is reached).
The heart on item tiles
- Mark every item tile whose id is in the favourites of type
Item, and let a click toggle add / drop. - Send
namewith the add call, so the fallback label stays meaningful. - Hide the heart for guests, or turn it into a logon prompt.
- Reload the favourites after logon and logout. On a shared device, never show the previous customer's list.
"Nicht vergessen": regular items due again
api/client/reorderhints predicts, from the customer's own order history, which of the items they buy regularly are due with the selected delivery date. The answer is a list of ReorderHint in display order, most due first:
status:due(due with this delivery) orupcoming(bought regularly, not due yet). Show due items first or mark them; you may leave outupcomingones in a small box.usual_amountwithunit_id: the amount the customer usually orders. Prefill it, so one click adds the usual quantity instead of the default amount.
The server already leaves out what makes no sense to suggest: items already in the order for that date, items
that are not available, items that come with a subscription or box anyway, and items the customer stopped buying.
Always pass the selected delivery date as ddate (days since 1.1.2007); without it, today is used, which gives a
different answer than the date the customer orders for. The server only knows orders already stored — items the
customer just put into the cart but has not ordered yet are still listed, so hide those on your side. A customer
needs at least two deliveries with the same item before it shows up; new customers get an empty list.
The standard shop also uses the list in the cart: one button "Möhren hinzufügen?" offers the first item of the list that is not in the cart yet and adds it in the usual amount; after the click, the next one is offered. Keep such a nudge to one item at a time — a long list next to the checkout distracts from finishing the order.
Let the customer switch such suggestions off for good. The standard cart has an "x" on the suggestion; it calls
api/client/nudge1 (off=1, or off=0 to switch them on again), and the profile
settings offer the same as a checkbox. The state is nonudge in the user data: when it is
true, show no suggestions in the cart. The lists themselves stay available.
Rankings: "Oft in deinen Bestellungen" and "Was andere bestellen"
Both answer with a list of RankedItem — an item id and its rank, best first:
- api/client/frequentitems: the logged-on customer's most ordered items (up to 70). Refused for guests. It looks at all orders, so it also lists items the customer has not bought for a while — good for "buy again", but use "Nicht vergessen" when you want what is due now.
- api/bestsellers: the shop's 100 most ordered items of the last weeks. The same for every visitor, so you may cache it (the answer allows 10 minutes). Use it for guests, new customers and empty lists.
Items that are not offered are left out of both. Neither depends on the delivery date; the availability for the selected date comes with the items call, see below.
From references to tiles
Favourites, reorder hints and rankings only carry ids. To show them:
- Items: load all of them with one api/items call, passing the ids comma separated in
i. The answer has everything a normal item tile needs (price, unit, images, availability, alternative units). See item-details and images-for-items-and-groups. Keep the order of reorder hints and rankings, it is the point of the list; the items call returns its own order. - Menu levels (
Group,SubGroup,Rubric,Assortment,AssortmentGroup): look them up in the api/navigation data, which your shop loads for its menu anyway, and show them as links to that level. Boxes are described by api/assortment. - Articles: show
entityNameas a link to your content page for that article.
Item availability depends on the delivery date selected in the session — the same favourite can be orderable on one date and not on another. Select the date first, see Delivery Date Selection.
Favourites that are currently not available
A favourite stays on the list when its item cannot be ordered at the moment. Two cases:
- The item is not offered right now: the items call does not return it at all.
- The item is returned, but tells you it cannot be ordered for the selected date: see
available,saleLeft(0 = sold out) and the order and delivery periods in Item.
Do not silently drop such favourites from view. Show them with their entityName (or the item tile), marked as
currently not available, with a way to remove them. Customers keep seasonal favourites on purpose — the
strawberry heart from last summer is a reason to come back. An item that is removed from the range for good
disappears from the favourites by itself.
Don't forget
- These lists are personal data: load them only for the logged-on customer and do not cache them beyond the session.
- Offer, don't push: the lists should help the customer complete the order, not sell something unrelated. Keep them short and leave out what is already in the cart.
- Adding and dropping favourites are events you can receive by webhook ("favourite added" / "favourite removed" in the event list), e.g. to feed a CRM; see use_webhooks.
- The standard shop shows favourites on the profile too; see profile-display.
Ideas
- A personal start area for returning customers: next delivery date and order deadline, then "Nicht vergessen", then the favourites link.
- "Add all to cart": one button that puts every available favourite or every due item into the cart, with the usual amount.
- Remind before the order deadline (mail or push) with the due items, linking back to the list.
- Group a long favourites list by category, like the shop menu.
- Point out favourites that are on special offer or available again for the selected date.