Skip to main content

Substitutions

When a picker cannot find what the customer ordered, they can offer a replacement rather than simply reporting the item unavailable.

Click and Collect runs an open substitution policy: the picker decides. We do not maintain a fixed table of permitted swaps, because the person holding the product in a real store on a real day is better placed to judge than a rule written in advance. What we do instead is make the decision faster — the service tracks which replacements have been chosen before, at customer, store and tenant level, and offers those first.

For those suggestions to be any good, your items need to be in the system. The minimum item information can be imported through the Item Input API.

Adding a replacement​

POST /api/v1/business-units/{businessUnitId}/orders/{orderId}/lines/{lineId}/substitutions
{
  "lines": [
    {
      "itemId": "item-987",
      "description": "Own Brand Baked Beans 400g",
      "quantity": 2,
      "unitOfMeasure": "EA"
    }
  ]
}

itemId, description, quantity and unitOfMeasure are required; itemIdentifier and imageUrl are optional. More than one replacement can stand in for a single line — a customer who ordered one large jar can be given two small ones.

Removing one takes the item id in the path:

DELETE /api/v1/business-units/{businessUnitId}/orders/{orderId}/lines/{lineId}/substitutions/{itemId}

🛑 What a substitution does to the line​

The original line does not disappear, and it does not become a different line. It stays, and its status changes to record that a replacement is involved:

What happenedLine status
a replacement offered, none of the original foundSUBSTITUTED
a replacement offered and some of the original foundPARTIALLY_SUBSTITUTED

The substitution outranks the picked quantity. Once a replacement is on the line, the status describes the substitution rather than how much of the original was picked — so a substituted line is never reported as PICKED or UNAVAILABLE.

Removing the last replacement puts the line back where its picked quantity alone would have put it — PENDING, PICKED or UNAVAILABLE. Substituting is not a one-way door.

See order statuses for how these combine with the picking statuses.

What this means if you are consuming the events​

🛑 A substituted line still counts as fulfilled. SUBSTITUTED is a resolved state — the order can be completed with it, and the picker is not expected to do anything further. If you are reconciling what the customer ordered against what they received, do not treat a substituted line as a shortfall; the customer is getting something, it is simply not the item on the original line.

The original item and the replacement are both on the line, so an integration that only reads the ordered item will miss what the customer is actually receiving. Read the substitutions, not just the line.