Allows the partner to make amendments to order items.

Summary

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.

Substitute with a partner catalogue product ID

Partners that choose the replacement themselves (for example from their own product catalogue)
can pass substitution_external_id instead of calling substitute search. The value is the
partner's own catalogue product ID and must be sent as a string, since leading zeros are
significant:

{
  "item_amendments": [
    {
      "amends": {
        "id": "YYY",
        "quantity": 1
      },
      "final_quantity": 1,
      "substitution_external_id": "05059697384226"
    },
  ]
}

The same rules apply as for substitution_id: the whole order line is replaced with the same
quantity, and allowed_actions_if_items_are_unavailable must contain
PARTNER_CHOSEN_SUBSTITUTION. Provide either substitution_id or substitution_external_id;
a request containing both is rejected. Unlike substitution_id, both amends.quantity and
final_quantity are required and must equal the ordered quantity.

ℹ️

Available on request: substitution by catalogue product ID is enabled per partner.

Contact your account manager to discuss enabling this feature for your brand. Until it is
enabled, requests containing substitution_external_id are rejected with
400 SUBSTITUTION_EXTERNAL_ID_NOT_ALLOWED.

Errors specific to substitution_external_id

If any amendment in the request cannot be resolved, the whole request is rejected and no
amendment is applied: a substitution is never turned into a removal.

StatuscodeMeaningRetry?
400SUBSTITUTION_EXTERNAL_ID_NOT_ALLOWEDSubstitution by catalogue product ID is not enabled for your brand.No
400SUBSTITUTION_EXTERNAL_ID_NOT_FOUNDOne or more IDs are not in the site's catalogue. The message lists them.No, correct the ID
400bad_requestInvalid request, for example both substitution_id and substitution_external_id on one amendment, an empty ID, quantities that do not equal the ordered quantity, or too many distinct IDs in one request.No
503SUBSTITUTION_EXTERNAL_ID_CHECK_UNAVAILABLEWhether the feature is enabled for your brand could not be checked.Yes
503SUBSTITUTION_RESOLVER_UNAVAILABLECatalogue product IDs could not be resolved at the moment.Yes
503SUBSTITUTION_REPLACEMENT_NOT_RESOLVEDThe ID is in the catalogue but has no menu item for the site yet.Yes
500internal_server_errorUnexpected error on our side.Later
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 2 requests per order per second. If you get over the limit, you'll get "Too many requests" error.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

Related order id in format {market}:{order_uuid}.

Body Params

Order amendments specification.

item_amendments
array of objects
required

Array of item amendments

item_amendments*
Responses

Language
Credentials
OAuth2
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json