---
updatedAt: 2026-08-30T18:01:10.000Z
agentTools:
  projectIndex: https://developers.deliverect.com/v2.0-retail/llms.txt
---

# How to handle item availability actions

## Overview

In submitting an order, the customer's preference for actions to take if items are unavailable can be set as below example;

```json Item Unavailable Example
{
    "items": [
        {
            "plu": "COLA1",
            "name": "Coca Cola",
            "price": 450,
            "quantity": 1,
            "itemUnavailableActions": [
                "ITEM_AMENDMENT",
                "ITEM_REMOVE",
                "ITEM_SUBSTITUTION",
                "CANCEL_ORDER",
                "ITEM_SUBSTITUTION_CATALOG"
            ]
        }
    ]
}
```

## Substitution Preference

| Action                       | Meaning                                                                  |
| :--------------------------- | :----------------------------------------------------------------------- |
| `ITEM_AMENDMENT`             | Change the quantity of the item or remove it                             |
| `ITEM_REMOVE`                | Remove the item from the order                                           |
| `ITEM_SUBSTITUTION`          | Allow the item to be replaced with any other item                        |
| `CANCEL_ORDER`               | Cancel the entire order                                                  |
| `ITEM_SUBSTITUTION_CUSTOMER` | Replace the item by another preselected item by the customer (see below) |
| `ITEM_SUBSTITUTION_CATALOG`  | Allow the item to be replaced with another item                          |

## Substitution Preference

Where`ITEM_SUBSTITUTION_CUSTOMER` is selected, this should be accompanied by an array `substituteCandidate`   that is a list of items the customer has selected as appropriate substitutions.

```json substituteCandidate
{
    "items": [
        {
            "plu": "COLA1",
            "name": "Coca Cola",
            "price": 450,
            "quantity": 1,
            "itemUnavailableActions": [
                "ITEM_SUBSTITUTION_CUSTOMER"
            ],
            "substituteCandidate": [
                {
                    "plu": "LEM1",
                    "name": "Lemonade",
                    "quantity": 1,
                    "price": 450
                },
                {
                    "plu": "PEP1",
                    "name": "Pepsi",
                    "quantity": 1,
                    "price": 450
                }
            ]
        }
    ]
}
```

## Substitute Preference Glossary

Please note that all the fields marked with ( (<span style={{ color: "red" }}> \* </span>) ) will be required

| Parameter                                                                | Meaning                                                                                                                                                                                                       | Type       |
| :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------- |
| items.`plu`<span style={{ color: "red" }}> \* </span>                    | Unique reference for the product                                                                                                                                                                              | string     |
| items.`name`<span style={{ color: "red" }}> \* </span>                   | Item name                                                                                                                                                                                                     | string     |
| items.`price`<span style={{ color: "red" }}> \* </span>                  | Price of the item with 2 decimal digit precision e.g. $1.00 is set as 100                                                                                                                                     | integer    |
| items.`quantity`<span style={{ color: "red" }}> \* </span>               | Item quantity                                                                                                                                                                                                 | integer    |
| items.`itemUnavailableActions`<span style={{ color: "red" }}> \* </span> | The customer's preference for actions to take if items are unavailable (see [Substitution Preference](https://developers.deliverect.com/page/retail-orders-item-unavailable-actions#substitution-preference)) | enum array |
| substituteCandidate.`plu`<span style={{ color: "red" }}> \* </span>      | Unique reference for a substituted product                                                                                                                                                                    | string     |
| substituteCandidate.`name`<span style={{ color: "red" }}> \* </span>     | Name of a substituted product                                                                                                                                                                                 | string     |
| substituteCandidate.`quantity`                                           | Specifying the quantity of substituted items accepted is optional                                                                                                                                             | integer    |
| substituteCandidate.`price`                                              | The price of the substituted item with 2 decimal digit precision e.g. $1.00 is set as 100                                                                                                                     | integer    |