Allows the partner to make amendments to order items.


Allows the partner to make amendments to order items. The endpoint accepts amendments for multiple items in a single call.

Usage scenario

Site would like to make Deliveroo systems and the customer aware of substitutions to the order.
Once order is amended it can be accepted.

Walk through

After an new order is received it might turn out that site is unable to fulfill all order items and it would like to
substitute some of them. Let's assume the item ID to substitute is YYY.

Get allowed item substitutions

Call get allowed item substitutions with YYY item ID to get list of allowed
substitutions for this item. In case of a successful search a response similar to the one below will be provided:

      "substitution_id": "ZZZ",
      "plu": "1234",
      "quantity": 1,
      "category": "Fruit",
      "name": "Large Oranges 4 per pack",
      "operational_name": "Large Oranges 4 per pack",
      "price": 215
Use substitutions

Use the substitution_id attribute from the get allowed item substitutions
response as the input to make amendments request.
In our case we're substituting YYY item with ZZZ with the same quantity, so the payload will be like:

  "item_amendments": [
      "amends": {
        "id": "YYY",
        "quantity": 1
      "final_quantity": 1,
      "substitution_id": "ZZZ"

and in case of successful amendment the response will contain substituted item under a new ID.

Substituted items in the data model
  • Amended items will be moved to archived_items.
  • New ID will be generated for each amendment even if it's just reducing the quantity of an order item. To make
    another amendment newly generated ID must be used.
  • Reference to amended item will be kept under amends.
  • Reference to original order item item will be kept under original. This will cut short all intermediate
    amendment operations. It will differ from amends in case of item will be amended multiple times.
  • Reference to refactored order item will be kept under refactors.

Business constraints

  • Order has to be in the PLACED status.
  • For amended order items menu item attribute allowed_actions_if_items_are_unavailable has to contain:
    • either ITEM_REMOVAL: for removing an item, or:
    • PARTNER_CHOSEN_SUBSTITUTION: for substituting an item.

Operational constraints

  • There's a rate limit of 1 request per order per 30 seconds. If you get over the limit, you'll get "Too many requests" error.
  • It is recommended that the integrating partner batches all the amendments for an order in a single call to this endpoint in order to avoid receiving a rate limit exceeded error.
Click Try It! to start a request and see the response here!