Substitutions

Somebody ordered the value loaf, the shelf was empty, and the picker reached for the bakery one. This is how that swap is recorded, priced and told to the customer before the bag leaves.

No screen yet

Substitutions are built and tested but have no screen in the app. Recording a swap, reading the list of swaps nobody has been told about, and marking one as told all happen over the API today. The rules below are what the software does.

What a substitution is for

On a pickup or delivery order somebody else fills the basket. The shelf is empty often enough that swapping is routine — and a shop with no record of the swap finds out about it at the same moment the customer does, when the bag is opened.

Three things are deliberately not left vague: the ticket still says what was ordered, the customer does not pay for a choice they did not make, and nothing goes out until somebody has recorded how they were told.

What the customer pays

The picker could not find the item that was ordered and put something else in the bag. By default the customer is charged the lower of the two prices. They ordered a $2 loaf, the picker put in the $5 one, they pay $2. It cuts the other way too: order the $5 loaf, get the $2 one, pay $2.

A store can be set to charge the replacement's own price instead. That is a per-store setting, so the same shop treats every swap the same way rather than leaving it to whoever is picking.

The replacement line also carries the substitute's normal price alongside what was actually charged, so a report can show what honouring the lower price cost the shop.

Not always one for one

A swap can change the quantity: two 500 g bags for the 1 kg that was gone. If nobody says otherwise the replacement takes the quantity that was ordered.

What happens to the ticket

The line that was ordered is voided, not deleted, with the reason Substituted (out of stock) — or whichever reason was given. The ticket still says what the customer asked for, so the swap can be argued about with something to point at.
A new line is added for the replacement, at the price the store's rule decided, taxed as that product is taxed.
The sale's subtotal, tax and total are recalculated.

Every swap records who did it, the reason, and an optional note in words — last one was crushed.

The reasons on offer

One of: out of stock, damaged, expiring, recalled, customer request, or other. Anything else is refused rather than filed under a category nobody agreed on.

Telling the customer

A swap starts un-told. Until somebody records how the customer heard about it, it sits on a pending list — and that list is the thing that stops a bag going out with a surprise in it.

The swap is recorded. Nobody has been told yet, so it appears on the pending list.
Somebody contacts the customer — by SMS, email, in the app, or out loud at the door.
That is recorded against the swap, with which of those four it was.
It drops off the pending list.

A picker who tells the customer at the door can record the swap and the telling in one go.

The first telling is the record

A second attempt is refused — The customer has already been told about this swap. The record is of what happened, not of the most recent thing anybody typed. And the channel has to be one of the four: something nobody can evidence afterwards is rejected.

Screenshot to come: the pending list of swaps nobody has been told about, with the ordered item, the replacement and what each was priced at — once this has a screen.

The list that stops a bag leaving before the customer knows.

What it refuses to do

A walk-in sale. On a till ticket or a self-checkout the customer is standing there holding the item: void the line and scan the other thing. The refusal says so — Substitutions are for orders somebody else picks (online, delivery).
The same product. That is the same product — nothing was substituted.
The same line twice. The first swap took that line off the ticket. Changing your mind again is a new swap against the new line.
A sale that is already paid for. Once the money is taken, the path is a refund. See Refunds & returns.
A replacement that is not in the catalog. You can only put in something the shop actually sells.

Who can do what

Recording a swap and marking it told need the right to ring up a sale — the picker is building the ticket, and the price came from the store's rule rather than from their judgement, so no override right is involved. Reading the list needs the right to read sales history: whoever is checking that nothing goes out untold is reading, not repricing. See Roles & permissions.

Substitutions are a per-store add-on. Switched off for a store, every route stops answering.