← API Index

Cart autosave with your own API client

"Ordering couldn't be more convenient – better than one-click!" A customer who fills a cart and then forgets to press Order still gets their delivery: the shop saves the cart in the background and, once the customer has opted in, submits it as a regular order. This skill explains what your client has to do to offer the same behaviour the standard JS shop has.

How it works

Two switches must both be on:

  1. Shop-wide: the shop operator enables cart autosave in the admin area. You cannot read this setting directly; see below how to detect it.
  2. Per customer: the customer opts in, in the standard shop with a profile checkbox worded roughly "If I forget to submit the cart, it should be saved automatically (I will receive an order e-mail)". The opt-in is the autosave field of the user data and is set with api/setprofile (autosave=1).

With both switches on, every cart save your client sends is written straight into an order: the first storable save creates a new order for the selected delivery date, every following save changes that same order. Without the customer opt-in, the same call still saves the cart in the server session (a backup that survives page reloads), but no order is created.

Order confirmation mails for autosaved orders are not sent on every save. They are sent once, when the session ends: on logout or when the session times out (75 minutes of inactivity for a logged-on customer). A manual submit through the regular order calls sends its mail immediately, as always.

If the last save of a session could not order the cart (see the result codes below), the customer receives a notice at the session timeout instead: "your cart was not ordered automatically, because …", with the delivery date, the order stop and a link to the order. No notice is sent after an explicit logout, because the customer confirmed dropping the cart there. The cart itself is kept and offered again at the next logon.

The calls

Reading the result

SaveCartResult tells you what happened:

result oid Meaning
modified 0 Cart saved in the session only. Either autosave is not active for this customer (autosave is false), the cart cannot be stored yet (see below), or this was the very first save of a brand-new cart — the server creates its session cart on that first call and stores it on the next one.
stored order id The cart is now this order. Remember the id.
below_mbw, too_late, locked, exceeded, … 0 The cart was saved in the session but could not be turned into an order right now: minimum order value not reached, order stop passed, order locked by the back office, order limit exceeded, and so on. These are the same codes the order calls use. Treat them as "not stored yet", not as errors to show.

autosave in the result is the effective state (shop switch and customer opt-in). It is the reliable way to detect whether autosave is on for this customer, and a good trigger for showing the opt-in checkbox or a hint in your UI.

Keeping your client in sync

Once a save answers stored, your local cart is that order. Store the returned oid with the cart and from then on:

The server protects against the obvious mistake: a neworder for a cart that autosave already stored is routed to that order instead of creating a second one for the same date. Do not rely on this as your primary mechanism — a client that keeps oid sends the right call in the first place, and only that keeps the customer's view (order number, mail) consistent.

Timing

The standard shop sends a save 20 seconds after the last cart change, restarting the timer on every change (debounce). Sending on every keystroke is unnecessary load; sending only on page leave loses carts when the app is killed. Twenty seconds is a proven middle ground.

Use the reset parameter when the customer has reverted their cart to the state of the loaded order (nothing to change anymore): the positions are still saved, but the server marks the cart as unmodified again so that it is not treated as a pending change at the end of the session.

Do not forget

Ideas