---
updatedAt: 2026-05-29T16:58:21.000Z
---

# Get allowed item substitutions.

### Summary
This API endpoint allows the partners to search for the allowed item substitutions for a given order item.

### Usage scenario
Site would like to know which items should be used for substitutions.

### Business constraints
* Order has to be in the `PLACED` status.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Picking API",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.developers.deliveroo.com/",
      "description": "Production API"
    },
    {
      "url": "https://api-sandbox.developers.deliveroo.com/",
      "description": "Sandbox"
    }
  ],
  "paths": {
    "/picking/v1/orders/{order_id}/items/{order_item_id}/substitute": {
      "parameters": [
        {
          "$ref": "#/paths/~1picking~1v2~1orders~1%7Border_id%7D/parameters/0"
        },
        {
          "name": "order_item_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Related order item id in format {order_item_uuid}.",
          "example": "07fbb82a-ceb5-43ec-123f-18af89e3380a"
        },
        {
          "name": "needle",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "Search word describing the desired item(s) to be used as a substitute. If not provided, item specific recommendations will be returned. For optimal results do not use needles longer than 10 characters. Multi-word needles must use %20 as a separator",
          "example": "Mango"
        },
        {
          "name": "limit",
          "in": "query",
          "required": true,
          "schema": {
            "type": "integer",
            "minimum": 0
          },
          "description": "Number of substitutions to return",
          "example": 2
        },
        {
          "name": "quantity",
          "in": "query",
          "required": true,
          "schema": {
            "type": "integer",
            "minimum": 0
          },
          "description": "Quantity to substitute",
          "example": 1
        }
      ],
      "get": {
        "summary": "Get allowed item substitutions.",
        "description": "### Summary\nThis API endpoint allows the partners to search for the allowed item substitutions for a given order item.\n\n### Usage scenario\nSite would like to know which items should be used for substitutions.\n\n### Business constraints\n* Order has to be in the `PLACED` status.",
        "operationId": "picking-v1-get-order-substitutions",
        "tags": [
          "Endpoints V1"
        ],
        "responses": {
          "200": {
            "description": "Response with list of allowed items substitutions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "description": "A single allowed substitution candidate for an order item. Returned by `GET /picking/v1/orders/{order_id}/items/{order_item_id}/substitute`.",
                    "type": "object",
                    "properties": {
                      "substitution_id": {
                        "description": "Identifier of substitution used for amending order item.",
                        "type": "string"
                      },
                      "plu": {
                        "description": "PLU (price lookup code) of the substitution item.",
                        "type": "string"
                      },
                      "quantity": {
                        "description": "Quantity of items that can be used for substitution.",
                        "type": "integer",
                        "minimum": 0
                      },
                      "category": {
                        "description": "Category name of the substitution item.",
                        "type": "string"
                      },
                      "name": {
                        "description": "Name of the substitution item.",
                        "type": "string"
                      },
                      "operational_name": {
                        "description": "Operational name the site uses in-house for the substitution item.",
                        "type": "string"
                      },
                      "price": {
                        "description": "Price in minor units of the currency.",
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "required": [
                      "substitution_id",
                      "plu",
                      "quantity",
                      "category",
                      "name",
                      "operational_name",
                      "price"
                    ]
                  }
                }
              }
            },
            "links": {
              "address": {
                "operationId": "picking-v1-amend-order",
                "parameters": {
                  "order_id": "$request.path.order_id"
                }
              }
            }
          },
          "400": {
            "description": "The request didn't work, often because a required parameter is missing or the content-type hasn't been set e.g. an incorrect JSON request",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "bad_request",
                    "message": "invalid request"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            },
            "headers": {}
          },
          "401": {
            "description": "The request didn't work because the combination of your API key and API token doesn't exist in our system or your integration has been disabled",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "basic auth not provided"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            },
            "headers": {}
          },
          "404": {
            "description": "Order with that ID was not found in our systems.",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Unknown order with id: gb:07fbb82a-ceb5-43ec-911f-18af89e3380a"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            },
            "headers": {}
          },
          "429": {
            "description": "Too many requests. Rate limit of 2 request / second / 1 order is exceeded",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "too_many_requests",
                    "message": "api calls have exceeded the RPS limit"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/paths/~1picking~1v2~1orders~1%7Border_id%7D/get/responses/429/headers/Retry-After"
              }
            }
          },
          "500": {
            "description": "Something went wrong on our end. You'll have to try again later once we've fixed it.",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "internal_server_error",
                    "message": "Internal server error"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            }
          }
        }
      }
    },
    "/picking/v1/webhooks": {
      "get": {
        "summary": "Retrieve Picking API webhook configuration (Integrator)",
        "description": "### Summary\nThis API endpoint allows integrators to retrieve their Picking API Webhook configuration.\n---\n**NOTE**\nThis endpoint should only be used by Middleware providers, integrated with Deliveroo. Before proceeding, please confirm with your dedicated Technical Integration Manager to confirm if this is the correct endpoint to be implemented, as per your config set up.\n---\n\n### Usage scenario\nThe partner or the integrator would like to know the current configuration.\n\n### Business constraints\n*None*\n\n### Operational constraints\n*None*",
        "operationId": "picking-v1-get-webhook-configuration",
        "tags": [
          "Webhook URL Configuration"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/put/requestBody/content/application~1json/schema"
                },
                "example": {
                  "picking_status_url": "https://example.com/webhook",
                  "has_unique_webhook_urls": false
                }
              }
            }
          },
          "401": {
            "description": "The request didn't work because the combination of your API key and API token doesn't exist in our system or your integration has been disabled",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "basic auth not provided"
                  }
                },
                "schema": {
                  "description": "Error.",
                  "type": "object",
                  "properties": {
                    "error": {
                      "description": "Error body",
                      "type": "object",
                      "properties": {
                        "code": {
                          "description": "HTTP status code description.",
                          "type": "string"
                        },
                        "message": {
                          "description": "Details about the error.",
                          "type": "string"
                        },
                        "details": {
                          "description": "Individual error messages. Present on validation errors.",
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "errors": {
                          "description": "Structured error details with machine-readable codes. Present on validation errors when item-level detail is available.",
                          "type": "array",
                          "items": {
                            "description": "Structured detail for a single validation error.",
                            "type": "object",
                            "properties": {
                              "code": {
                                "description": "Machine-readable error code identifying the type of validation failure.",
                                "type": "string",
                                "enum": [
                                  "duplicate_amendment",
                                  "item_not_in_order",
                                  "missing_final_quantity",
                                  "invalid_final_quantity",
                                  "item_already_amended",
                                  "amendment_not_allowed",
                                  "invalid_order_status"
                                ]
                              },
                              "item_id": {
                                "description": "The order item ID that the error relates to. Omitted for non-item-level errors.",
                                "type": "string"
                              },
                              "message": {
                                "description": "Human-readable description of the error.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message"
                            ]
                          }
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            },
            "headers": {}
          },
          "500": {
            "description": "Something went wrong on our end. You'll have to try again later once we've fixed it.",
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "internal_server_error",
                    "message": "Internal server error"
                  }
                },
                "schema": {
                  "$ref": "#/paths/~1picking~1v1~1webhooks/get/responses/401/content/application~1json/schema"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2-Production": {
        "type": "oauth2",
        "description": "OAuth for Production",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://deliveroo-api.auth.eu-west-1.amazoncognito.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "OAuth2-Production": []
    }
  ]
}
```