Remove Orders from a Route

Bulk-remove orders from a single route. The orders drop back to unrouted (their status returns to OPEN); they are not moved to another route. This is a partial-success bulk operation returning { orders, errors } (the same envelope as POST /orders): one un-removable order never fails the rest of the batch.

The route id is given in the path (/routes/{id}/remove-orders) and scopes the whole call — every order must be on that route. Each order is identified by id (depot-scoped, preferred) and/or order_number — at least one is required per entry; if both are given they must resolve to the same order. An order that is not on the given route is reported as NOT_ON_ROUTE.

orders and errors are NOT mutually exclusive. orders lists every order that resolved to a real record, each with the stops it was taken off ({ id, route: { id } }) — an empty stops array means nothing was removed from it. errors is a parallel list of problems; an order that exists but could not be removed (e.g. it is on a dispatched route, or not on the given route) appears in BOTH orders (with empty stops) and errors. An order reference that does not resolve at all (ORDER_NOT_FOUND) appears only in errors.

Each errors entry is a { name, description, details } envelope where name is the failure reason and details carries at least the id / order_number. Failure names include ORDER_NOT_FOUND, ID_NUMBER_MISMATCH, NOT_ON_ROUTE, ROUTE_DISPATCHED, ORDER_COMPLETED, STOP_REBUILD_FAILED, STALE_VISIT and REMOVAL_FAILED. By default orders on dispatched (live) routes are reported as ROUTE_DISPATCHED; set settings.allow_dispatched to true to edit live routes.

Set settings.reoptimize to true to re-sequence each affected route after the removal. This runs synchronously — the request blocks until each affected route has been solved and applied, so it can take seconds to minutes. The removal is applied first and the affected route is then re-sequenced. A reoptimised order is returned in orders with the stops it was taken off, the same as a normal removal. If the removal itself fails the order is reported with REMOVAL_FAILED (as in a non-reoptimise call); if only the re-sequencing step fails after the order was already removed, the order still counts as removed (returned in orders) and the re-sequencing failure is not surfaced per order.

Multi-order (consolidated) stops are handled per stop: if every order on the stop is being removed the whole stop is deleted, otherwise the stop is kept and rebuilt with just the remaining orders (the removed order drops to OPEN, the others are unaffected). In the rare case the remaining orders cannot be re-consolidated into a single stop, that order is reported with STOP_REBUILD_FAILED and the stop is left untouched.