# stockRecords

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

## What it does

The stock balances — what you own, where, in which bucket.

One InventoryItem StockRecord shard rows — where its stock sits in bins (zero rows = everything un-binned). Requires authentication; a cross-tenant/missing id reads as an empty list; a doomed item keeps READABLE shards.

## What happens

Reads only.

## Who may call it

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

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

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `inventoryItemId` | [ID](/types/#scalars) `ID!` | yes | No further notes. |

## Returns

[StockRecord](/types/StockRecord/) `[StockRecord!]!` — One StockRecord bin/lot SHARD of an InventoryItem: NOT a construct — sysId-less and FSM-less, existing only where stock has landed in a bin (zero records = everything un-binned, the small-merchant case). Carries ONLY the three LOCATABLE buckets (reserved is a claim overlay, in_transit is not physically here — both stay on the item caches); quantities are NON-NEGATIVE (a relocate refuses driving a record negative — CONFLICT/INSUFFICIENT_STOCK). The DERIVED un-binned pool = item caches minus the record sums (see verifyInventoryItem). Records persist at zero; a zeroed record does NOT block its bin (the moved-or-zeroed rule).

## Example request

```graphql
query ExampleStockRecords($inventoryItemId: ID!) {
  stockRecords(inventoryItemId: $inventoryItemId) {
    inventoryItemId
    binId
    lotCode
    lotExpiresAt
    onHandQty
    damagedQty
    heldQty
    createdAt
    updatedAt
    revisionNum
  }
}
```

Variables:

```json
{
  "inventoryItemId": "01900000-0000-7000-8000-9307d9650000"
}
```

## Example response

```json
{
  "data": {
    "stockRecords": [
      {
        "inventoryItemId": "01900000-0000-7000-8000-9307d9650000",
        "binId": "01900000-0000-7000-8000-20867aa30000",
        "lotCode": "BJ-001",
        "lotExpiresAt": "2027-01-31T00:00:00.000Z",
        "onHandQty": "<on hand qty>",
        "damagedQty": "<damaged qty>",
        "heldQty": "<held qty>",
        "createdAt": "2027-01-31T00:00:00.000Z",
        "updatedAt": "2027-01-31T00:00:00.000Z",
        "revisionNum": 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/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))