---
title: "Use the reviewed order query contract"
description: "Define Driver order list/detail reads across filters, status tabs, pagination, grouping, logistics separation, events, and currentness."
canonical: https://docs.ordering.co/docs/developers/driver-app/order-query-contract/
---

# Use the reviewed order query contract

Driver order queries produce scoped pages and details, not a complete or atomic operational snapshot. Tab state, filters, pagination, local grouping, summaries, socket events, and logistics assignment reads are separate layers.

A card, count, empty view, group, summary, sort position, or refreshed detail does not prove currentness or completeness.

## Availability

Authenticated Driver order list/detail reads are available through **Orders** and registered detail routes. The service scopes Driver queries to the current Driver and applies requested filters/pagination.

Logistics assignment requests use a separate assignment-query contract. They must not be merged into ordinary order query semantics merely because the App presents them in the Orders area.

## Prerequisites

- Derive Driver identity from the authenticated session.
- Use typed, allowlisted filter/sort/page inputs with bounded page size.
- Define requested relations/fields purpose-minimally.
- Distinguish first page, load more, refresh, cross-status search, detail read, socket/event update, and local grouping.
- Preserve one revision/cursor contract if currentness across pages matters.

## Responsibility boundaries

| Owner                  | Responsibility                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------- |
| Order API              | Driver scope, filters, sort, pagination, relation projection, detail authorization |
| Client list controller | Tab/page/filter/loading/error state and deduplication                              |
| Client formatter       | Plain/grouped transformations and presentation sorting                             |
| Filter dependencies    | Countries/cities/config controls as separate reads                                 |
| Socket/event layer     | Incremental hints requiring authorization and revision reconciliation              |
| Logistics API          | Assignment request list/detail, not ordinary orders                                |
| Summary UI             | Derived display only; not earnings, payout, accounting, or query authority         |

## Inputs and result

Supported query dimensions can include order status group, order/external identifier search, city/business, delivery type, date range, timing category, page, page size, and sort. Availability varies by UI/configuration.

Results must distinguish loading, populated page, empty page, error, additional page, refreshed page, grouped presentation, detail, and event-updated local state. An empty page is not “no orders,” and concatenated pages/events are not one snapshot without a revision contract.

Cross-status search clears the current tab-status filter and can use separate pagination/summary presentation. Opening its city selector can automatically start a countries/cities dependency read before Search.

Grouping is a local transformation of returned orders/keys. It is not a user- selectable server grouping rule or authorization boundary. Missing/malformed keys and mixed member states require explicit handling.

## Security and privacy

- Enforce Driver self-scope for every list/detail/event refresh.
- Allowlist filters/sorts/relations; cap page size and reject malformed values.
- Return purpose-minimal order, business, customer, location, payment, message, and assignment fields.
- Never expose raw IDs, contacts, addresses, coordinates, tokens, query payloads, room names, or private errors in public evidence.
- Reauthorize socket/event-triggered detail reads; never trust event payload as the current order.

## Limits and failure states

| State                     | Required interpretation                             |
| ------------------------- | --------------------------------------------------- |
| Loading skeleton          | Read unresolved                                     |
| Card/page                 | Current returned/local page only                    |
| Empty                     | No row in this result/page/filter                   |
| Load more                 | Another reported page, not complete snapshot        |
| Filtered summary          | Derived cross-status display                        |
| Group card                | Local transformation, member outcomes separate      |
| Socket move/insert/remove | Incremental local update, not durable/current proof |
| Detail                    | Authorized read plus related mount dependencies     |
| Logistics card            | Separate assignment query contract                  |

No complete count, stable ordering across events, snapshot isolation, exactly-once socket update, exhaustive grouping, payout meaning, or deployed currentness is established.

## Troubleshooting

### Results look stale or incomplete

Separate tab/filter/page/socket state. Refresh once and compare the returned revision; do not loop reads as a currentness test.

### An empty page appears

Check filter/page/status context and errors. Do not infer no order exists or broaden scope without authorization.

### Duplicate or moved cards appear

Pagination deduplication and socket events can interleave. Reconcile by order revision, not visual position.

### A group contains mixed states

Treat each member independently. Local grouping does not guarantee common status, ownership, eligibility, or atomic outcome.

### Logistics and ordinary orders differ

Use the logistics request contract for assignment reads/decisions. Do not force ordinary order filters or grouping rules onto assignment requests.

**Related guides:** [Find delivery requests](https://docs.ordering.co/docs/products/driver-app/orders/find-deliveries/) · [Filter and prioritize requests](https://docs.ordering.co/docs/products/driver-app/orders/filter-and-prioritize/) · [Use the logistic request contract](https://docs.ordering.co/docs/developers/driver-app/logistic-request-contract/)