Set the prep state of a single item

put

https://api.developers.deliveroo.com/picking/v1/orders/{order_id}/prep-state/items/{item_id}

Summary

Records the outcome of picking a single item — either fulfilled (with a prep_method of PREP_METHOD_SCAN or PREP_METHOD_MANUAL) or unfulfilled (the item could not be found). Calling this endpoint will also implicitly start picking on the order if start-picking has not already been called.

Usage scenario

After scanning an item's barcode, or manually marking it as picked, send the result via this endpoint. To mark an item as unable to be found, send PREP_STATE_UNFULFILLED.

Validation rules

prep_state must be one of PREP_STATE_FULFILLED, PREP_STATE_UNFULFILLED.
prep_method, when supplied, must be one of PREP_METHOD_SCAN, PREP_METHOD_MANUAL, PREP_METHOD_UNKNOWN.
When prep_state is PREP_STATE_FULFILLED, prep_method must be PREP_METHOD_SCAN or PREP_METHOD_MANUAL (i.e. not omitted and not PREP_METHOD_UNKNOWN).
When prep_method is PREP_METHOD_SCAN, barcode is required.
When prep_state is PREP_STATE_UNFULFILLED, omit prep_method and barcode. Sending them is accepted (no 400), but the recorded prep state for an unfulfilled item should not carry method/barcode metadata and partners should not rely on those fields being preserved.

Notes

Once an item has been amended (substituted, removed, or partially fulfilled) further prep-state writes against the original item ID return 409 ARCHIVED_ITEM. Re-key on the new (substituted) item ID instead.

Operational constraints

There's a rate limit of 1 request per order item per second (independent of the GET bucket above). If you get over the limit, you'll get a "Too many requests" error.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

order_id

string

required

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

item_id

string

required

Item identifier (DRN) for the order item. Use the id returned in the order's items[].

Body Params

Request body for PUT /picking/v1/orders/{order_id}/prep-state/items/{item_id}.

prep_state

string

enum

required

The new prep state for the item. Note this is a narrower enum than the response variant — PREP_STATE_UNKNOWN is not a valid request value and will be rejected with 400 INVALID_ARGUMENT.

Allowed:

prep_method

string

enum

How the item was picked. Required (as PREP_METHOD_SCAN or PREP_METHOD_MANUAL) when prep_state is PREP_STATE_FULFILLED. Optional otherwise.

Allowed:

barcode

string

Barcode scanned by the picker. Required when prep_method is PREP_METHOD_SCAN. Optional for PREP_METHOD_MANUAL. Should be omitted when prep_state is PREP_STATE_UNFULFILLED.

Responses

Language

Credentials

OAuth2

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Prep state was recorded.

400The request was invalid. Possible code values: INVALID_ARGUMENT — prep_state is missing or not one of the allowed values, prep_method is invalid for the given prep_state, or barcode is missing when prep_method is PREP_METHOD_SCAN.

401The 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

403The caller does not have permission to update prep state for this order. Possible code values: FORBIDDEN — permission denied by the downstream prep-state service.

404Not found. Possible code values: ITEM_NOT_FOUND — the item does not belong to this order (active or archived). ORDER_NOT_FOUND — the order does not exist.

429Too many requests. Dedicated rate limit for prep-state endpoints exceeded.