← API Index

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

"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:

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:

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:

  1. 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.
  2. 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.
  3. Articles: show entityName as 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:

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

Ideas