---
title: "Use the reviewed order mutation contract"
description: "Define safe Driver order updates across authorization, locks, reasons, media, location, grouped partiality, follow-ons, and idempotency."
canonical: https://docs.ordering.co/docs/developers/driver-app/order-mutation-contract/
---

# Use the reviewed order mutation contract

Driver order mutation is a server-authorized state transition, not a button press or client-side status assignment. One-order and grouped updates, assignment decisions, media, location, reasons, ETA, queue effects, and follow-ons must remain separate.

Navigation, a toast, a returned order, an image preview, a location check, a socket event, or a member aggregate does not confirm a durable order change.

## Availability

Mutation controls are conditional on order/request type, current returned state, Driver ownership, project configuration, permissions, connectivity, loading, locks, assignment context, and visible requirements.

Control visibility is only a client gate. The service must independently authorize the Driver, order/assignment relationship, target transition, lock, concurrency, required reason, media, and location.

## Prerequisites

- Bind actor identity to the authenticated session.
- Read the current order/assignment revision immediately before mutation.
- Use a typed transition command rather than a generic client status value.
- Define required reason/comment, ETA, image, location and configuration per transition.
- Supply an idempotency/concurrency strategy and an observable result receipt.
- For groups, identify every member and expected per-member result explicitly.

## Responsibility boundaries

| Owner                   | Responsibility                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| Driver App UI           | Present eligible-looking controls, requirements, loading, and errors without claiming authority      |
| Client controller       | Build one typed intent, preserve uncertain state, and avoid blind retry                              |
| Order API               | Authenticate, authorize ownership, lock, validate transition and inputs, and produce durable receipt |
| Assignment API          | Own accept/reject assignment decisions separately from order status                                  |
| Media/location services | Validate/store only after authorization with cleanup on failure                                      |
| Group coordinator       | Return one result per member; never hide partial outcomes                                            |
| Follow-on services      | History, messages, reports, queue, logistics, sockets, notifications, mail, webhooks, jobs, plugins  |
| Dispatcher/operator     | Reconcile uncertain, competing, or partial outcomes                                                  |

## Inputs and result

One-order inputs can include intended transition, reason/comment, ETA, delivery position, location candidate, image, and order revision. Requirements vary by transition/configuration; no complete old-to-new graph is accepted from the client alone.

The result contract must distinguish:

- request rejected before any effect;
- order write accepted;
- media/location write accepted or cleaned up;
- follow-ons complete, partial, or failed;
- current returned order revision; and
- safe retry/duplicate classification.

Grouped mutation is a collection of independently authorized member updates. Current client aggregation can return null for failed members and obscure partial success. A safe contract returns explicit per-member receipts and does not claim atomic rollback.

## Security and privacy

- Authorize before image upload, location write, or order mutation.
- Validate finite coordinates, freshness, mock policy, target, timestamp and purpose server-side.
- Trim and validate meaningful reasons/comments; do not accept whitespace as policy evidence.
- Keep media, location, order, participant, token, lock and provider details out of public logs/evidence.
- Do not treat a client PIN, image, permission gate, or local location checklist as server authorization.

## Limits and failure states

| State                    | Required interpretation                                            |
| ------------------------ | ------------------------------------------------------------------ |
| Control visible/enabled  | Client candidate only                                              |
| Requirements modal       | Local precheck only                                                |
| Request loading          | Outcome unresolved; no retry                                       |
| Returned error           | Earlier media/location/follow-on effects may still require cleanup |
| Returned order           | Order response only, not all follow-ons                            |
| Navigation/toast         | Client presentation only                                           |
| Group mixed/null results | Partial member outcomes                                            |
| Socket/push              | Transport hint, not durable receipt                                |
| Force/recovery form      | Conditional client branch, not guaranteed server contract          |

Current source does not establish exactly-once mutation, complete idempotency, atomic media/location/order/follow-ons, group rollback, or deployed success.

## Troubleshooting

### A control is visible but the service rejects it

Treat UI and server validation as separate. Refresh the authorized order once and reconcile ownership/lock/configuration; do not bypass the gate.

### A request times out or navigation changes

Do not repeat. Query the current order/assignment revision and require an idempotency/result receipt before deciding whether a retry is safe.

### One group member differs

Record every member result and reconcile independently. Do not report group success from aggregate navigation or a subset of cards.

### Media or location succeeded before an order error

Run the approved cleanup/reconciliation path. Do not assume rollback; report the order, media and location stages separately.

### A force form appears

Treat it as conditional recovery, not proof the server emitted the expected typed condition. Require an explicit reviewed error contract.

**Related guides:** [Use the logistic request contract](https://docs.ordering.co/docs/developers/driver-app/logistic-request-contract/) · [Use the reviewed maps contract](https://docs.ordering.co/docs/developers/driver-app/maps-contract/) · [Accept a delivery request](https://docs.ordering.co/docs/products/driver-app/orders/accept-a-delivery/)