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:
- Shop-wide: the shop operator enables cart autosave in the admin area. You cannot read this setting directly; see below how to detect it.
- 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
autosavefield 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
- api/logon — autosave is for authenticated customers only; never send cart saves for guests.
- api/settour — select the delivery date first. Autosave needs a date in the session to know which delivery the order is for. See Delivery Date Selection.
- api/savecart — the save itself. Post the complete cart (every position, not a delta) with the same position parameters the order calls use. The answer is one SaveCartResult.
- api/neworder / api/changeorder — the explicit submit when the customer presses Order; see "keeping your client in sync".
- api/user and api/setprofile — read and set the customer's opt-in.
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:
- send further saves as before — they change that order;
- when the customer presses Order, submit with api/changeorder
and
oid, not withneworder; - show the order number and an "order will be changed" wording instead of "new order", as the standard shop does.
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
- Consent. Autosave places orders without a final click. Only switch the customer opt-in on after an explicit, understandable choice by the customer, and make it just as easy to switch off. Tell the customer that a confirmation mail will follow.
- One cart per delivery date. Changing the delivery date with
settourstarts a new cart; a cart autosaved for the previous date stays an order for that date. - Minimum order value and order stop. A small cart is saved but not ordered (
below_mbw). If the customer never completes it, nothing is ordered — consider a reminder in your UI. - Payment methods. Orders paid through a payment provider (PayPal, Wero) need the customer's
fresh consent for every change in amount. Autosave does not touch such orders; the save answers
modifiedand the change is applied only on the next explicit submit. - Mails at session end. If your client never calls
logout, the confirmation mail arrives only after the session timeout. Call api/logout when the customer leaves. But do not log out a session whose last save was not stored if you want the customer to get the "not ordered" notice: that one is sent on timeout only. - Guests. Never autosave for unauthenticated sessions; the call is refused (
not_auth).
Ideas
- Show a subtle "saved as order 12345" badge after the first
storedresult, so the customer learns that leaving the page is safe. - Offer the opt-in right after a customer lost a cart once (e.g. logged on again with a stale cart).
- In a kiosk or voice client, treat
storedas the end of the conversation and read back the order number. - Combine with webhooks: a webhook on new orders lets your back office see autosaved orders the moment they are created, long before the session-end mail.
Related
- Feed orders into the system — the explicit order calls.
- Delivery Date Selection — why the date must be set first.
- Use the API — sessions, formats (
oo-rf=jsongives named fields) and error handling.