# ordersByConsumer

query · in the family [Reading your records](/reference/reading-your-records/)

## What it does

All the orders one customer has placed, newest first — their buying history.

One customer's orders, newest first, in pages — a customer outside your group refuses NOT_FOUND.

## Before you call

A bearer session from an API key (see [Authentication and key hygiene](/guides/authentication-and-key-hygiene/)) or a signed-in user.

Capability area: **Reading your records** — Looking up and listing the records of your organization.

Roles that may call it:

- Owner
- System Administrator
- Manager
- Associate Manager
- Sales Associate
- An API key whose scope allows `api:ordersByConsumer`

## What happens

Reads only.

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `consumerId` | [ID](/types/#scalars) `ID!` | yes |  |
| `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 ExampleOrdersByConsumer($consumerId: ID!, $limit: Int) {
  ordersByConsumer(consumerId: $consumerId, limit: $limit) {
    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
    matchCountExact
  }
}
```

Variables:

```json
{
  "consumerId": "01900000-0000-7000-8000-3cbb3ce90000",
  "limit": 1
}
```

## Example response

```json
{
  "data": {
    "ordersByConsumer": {
      "items": [
        {
          "id": "01900000-0000-7000-8000-18e782370000",
          "sysId": "SO-EXMP-0000-000F",
          "type": "Order",
          "caption": "Blue jeans",
          "status": "open",
          "parentId": "01900000-0000-7000-8000-10c08c590000",
          "rootId": "01900000-0000-7000-8000-a1295a650000",
          "createdAt": "2027-01-31T00:00:00.000Z",
          "updatedAt": "2027-01-31T00:00:00.000Z",
          "revisionNum": 1,
          "revision": "01900000-0000-7000-8000-53c6eea90000",
          "organizationId": "01900000-0000-7000-8000-1971e30a0000",
          "channel": "pos",
          "orderType": "sale",
          "validUntil": "<valid until>",
          "termEndsAt": "2027-01-31T00:00:00.000Z",
          "convertedOrderId": "01900000-0000-7000-8000-989e22cb0000",
          "sourceDocumentId": "01900000-0000-7000-8000-6c7148310000",
          "reorderOfOrderId": "01900000-0000-7000-8000-88fd3fab0000",
          "logicalFacilityId": "01900000-0000-7000-8000-10c08c590000",
          "currency": "USD",
          "exemptionCertificateId": "01900000-0000-7000-8000-b793be5b0000",
          "paymentState": "<payment state>",
          "fulfillmentState": "<fulfillment state>",
          "recognitionState": "<recognition state>",
          "taxJurisdictionId": "01900000-0000-7000-8000-33d0df4f0000",
          "subtotalMinor": 1250,
          "discountTotalMinor": 0,
          "taxTotalMinor": 0,
          "totalMinor": 1250,
          "fulfillmentFeeMinor": 1250,
          "fulfillmentFeeTaxMinor": 1250,
          "tenderedNetMinor": 1250,
          "tipTotalMinor": 0,
          "paymentIds": [
            "01900000-0000-7000-8000-20f641110000"
          ],
          "refundIds": [
            "01900000-0000-7000-8000-7900117f0000"
          ],
          "disputeIds": [
            "01900000-0000-7000-8000-c8f04d1b0000"
          ],
          "invoiceIds": [
            "01900000-0000-7000-8000-71ec87b00000"
          ],
          "couponIds": [
            "01900000-0000-7000-8000-d554478b0000"
          ],
          "sourcingSagaId": "01900000-0000-7000-8000-70f7ad270000",
          "commissionAgentUserIds": [
            "01900000-0000-7000-8000-8bb1c91e0000"
          ],
          "affiliateId": "01900000-0000-7000-8000-c6e63db40000"
        }
      ],
      "nextToken": "<the cursor from the previous page>",
      "matchCount": 1,
      "matchCountExact": true
    }
  },
  "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. Retry: no. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. Retry: no. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. Retry: no. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. Retry: yes. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. Retry: no. ([NOT_FOUND](/errors/NOT_FOUND/))

---

© 2026 1001636023 Ontario Inc., operating as AlmondTill/G3N. All rights reserved. Use of this documentation is subject to the Terms of Service at https://www.almondtill.com/terms.