# orders query · in the family [Order](/reference/order/) ## What it does The order list — each entry is a customer order. The caller's org-group family's ACTIVE LISTING of Orders — doomed records DROP from listings. PAGINATED: `limit` clamps to \[1, 200], default 100; `nextToken` = the prior page's cursor, verbatim — opaque + tenant-bound (a malformed or foreign token → VALIDATION/INVALID). Walk until `nextToken` is null (a page may hold fewer than `limit` — doomed drop per page). STRUCTURED FILTER + SORT: `filter` = AND across clauses, OR within a clause's values; `sort` = one declared field, asc/desc. The declared Order roster: `caption` (text) · `status` (enum) · `organizationId` (ref) · `channel` (enum) · `orderType` (enum) · `currency` (text) · `logicalFacilityId` (ref) · `paymentState` (enum) · `fulfillmentState` (enum) · `recognitionState` (enum) · `taxJurisdictionId` (ref) · `validUntil` (date) · `termEndsAt` (date) · `subtotalMinor` (money) · `discountTotalMinor` (money) · `taxTotalMinor` (money) · `totalMinor` (money) · `tenderedNetMinor` (money) · `tipTotalMinor` (money) · `createdAt` (date) · `updatedAt` (date). An illegal filter/sort refuses VALIDATION/INVALID NAMING the exact problem (an unknown field teaches the roster). A filtered/sorted read evaluates the WHOLE family server-side, returns the EXACT `matchCount`, and its `nextToken` binds to THE ONE filter+sort that minted it — replaying it under a different filter/sort refuses. Absent both, the unfiltered lane is unchanged (`matchCount` null). ## What happens Reads only — changes nothing. ## Who may call it Capability area: **Reading your records** — Looking up and listing the records of your organization. - Owner - System Administrator - Manager - Associate Manager - Sales Associate - Cashier - An API key whose scope allows `api:orders` ## Arguments | Name | Type | Required | Notes | | --- | --- | --- | --- | | `filter` | [FilterInput](/types/FilterInput/) | no | Which records to answer — clauses over the family’s filterable fields (the FilterInput type and the paging guide carry the grammar). | | `sort` | [SortInput](/types/SortInput/) | no | The order to answer in — one declared field and a direction (the SortInput type carries the grammar). | | `limit` | [Int](/types/#scalars) | no | How many records to answer at most; a page may hold fewer. | | `nextToken` | [String](/types/#scalars) | no | The cursor from the previous page, passed back exactly as received. | ## Returns [OrderPage](/types/OrderPage/) `OrderPage!` — One page of the orders listing — the records + the opaque resume cursor. This is a page: `items` holds the records and `nextToken` the cursor for the next page — pass it back verbatim until it is null. See [paging](/guides/paging-and-the-cursor-grammar/). ## Example request ```graphql query ExampleOrders($filter: FilterInput) { orders(filter: $filter) { items { id sysId type caption status parentId rootId createdAt updatedAt revisionNum revision organizationId channel orderType validUntil termEndsAt convertedOrderId sourceDocumentId reorderOfOrderId logicalFacilityId currency exemptionCertificateId paymentState fulfillmentState recognitionState taxJurisdictionId subtotalMinor discountTotalMinor taxTotalMinor totalMinor fulfillmentFeeMinor fulfillmentFeeTaxMinor tenderedNetMinor tipTotalMinor paymentIds refundIds disputeIds invoiceIds couponIds sourcingSagaId commissionAgentUserIds affiliateId } nextToken matchCount } } ``` Variables: ```json { "filter": { "clauses": [ { "field": "caption", "op": "contains", "values": [ "Blue" ] } ] } } ``` ## Example response ```json { "data": { "orders": { "items": [ { "id": "01900000-0000-7000-8000-37386ae00000", "sysId": "SO-EXMP-0000-000F", "type": "Order", "caption": "Blue jeans", "status": "open", "parentId": "01900000-0000-7000-8000-065235280000", "rootId": "01900000-0000-7000-8000-a093dd800000", "createdAt": "2027-01-31T00:00:00.000Z", "updatedAt": "2027-01-31T00:00:00.000Z", "revisionNum": 1, "revision": "01900000-0000-7000-8000-b7960e180000", "organizationId": "01900000-0000-7000-8000-44b781470000", "channel": "pos", "orderType": "sale", "validUntil": "", "termEndsAt": "2027-01-31T00:00:00.000Z", "convertedOrderId": "01900000-0000-7000-8000-b1563ac60000", "sourceDocumentId": "01900000-0000-7000-8000-8fd6a7c40000", "reorderOfOrderId": "01900000-0000-7000-8000-5533d5a60000", "logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000", "currency": "USD", "exemptionCertificateId": "01900000-0000-7000-8000-6c082e160000", "paymentState": "", "fulfillmentState": "", "recognitionState": "", "taxJurisdictionId": "01900000-0000-7000-8000-3a64e3820000", "subtotalMinor": 1, "discountTotalMinor": 1, "taxTotalMinor": 1, "totalMinor": 1, "fulfillmentFeeMinor": 1, "fulfillmentFeeTaxMinor": 1, "tenderedNetMinor": 1, "tipTotalMinor": 1, "paymentIds": [ "01900000-0000-7000-8000-f1636a750000" ], "refundIds": [ "01900000-0000-7000-8000-a5d2e2d30000" ], "disputeIds": [ "01900000-0000-7000-8000-d72df27f0000" ], "invoiceIds": [ "01900000-0000-7000-8000-0a4b14ba0000" ], "couponIds": [ "01900000-0000-7000-8000-6a9b05ef0000" ], "sourcingSagaId": "01900000-0000-7000-8000-2dfe37aa0000", "commissionAgentUserIds": [ "01900000-0000-7000-8000-7aaf99300000" ], "affiliateId": "01900000-0000-7000-8000-ab1bc9b90000" } ], "nextToken": "", "matchCount": 1 } }, "extensions": { "at": { "callId": "01EXAMPLE-CALL-ID", "version": { "requested": null, "serviced": { "name": "genesis", "number": 0 } } } } } ``` ## Errors this call can answer - `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/)) - `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/)) - `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/)) - `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))