> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/developers/api/reference/items/list-items.md).

# List items

> Returns a cursor-paginated list of items in the team.

Each item carries a `quantities` per-location breakdown; pass `location_ids` to scope that breakdown to specific locations. `location_ids` also filters the list to items with nonzero stock at those locations.

`GET https://rest.boxhero-app.com/v1/items`

## Authorizations

- `Authorization` (string, required): Bearer authentication header of the form `Bearer <token>`, where `<token>` is your [API token](https://www.boxhero.io/docs/developers/api/authentication.md).

## Query parameters

- `item_ids` (integer | array of integer): Filter the list to specific item ids. Pass repeatedly (`?item_ids=1&item_ids=2`) or as a single value.
- `location_ids` (integer | array of integer): Scope the `quantities` breakdown (and the `quantity` total) to specific locations, and filter the list to items with nonzero stock at those locations. When omitted, all items are listed and `quantities` covers every active location where the item has nonzero stock.
- `cursor` (integer, minimum 0, maximum 2147483647): Page cursor. Pass the `cursor` field from the previous response to fetch the next page. Omit on the first call.
- `limit` (integer, minimum 1, maximum 100): Page size. Accepts `1`–`100`; defaults to `100`.

## Responses

**200** A page of items.

- `items` (array of Item, required): Items in this page. Most resources are ordered by id ascending; transactions and orders/returns are ordered by time descending (see each list endpoint).

  - `id` (integer, minimum 0, maximum 2147483647, required): Item id.
  - `name` (string, required): Item display name.
  - `sku` (string, required): Stock Keeping Unit. Unique within the team. Every item has one; a random `SKU-XXXXXXXX` is generated when none is given on creation.
  - `barcode` (string, required): Primary barcode for the item. Empty string when not assigned.
  - `photo_url` (string, nullable, required): URL of the item's photo. `null` when no photo is set.
  - `attrs` (array of ItemAttr, required): Custom attribute values attached to the item. Manage the underlying attribute specs via `/item-attrs`.

    - `id` (integer, minimum 0, maximum 2147483647, required): Attribute spec id (see GET /item-attrs).
    - `type` (string, required): Value type of this attribute (`text`, `date`, `number`, or `barcode`). File-type attributes are app-only and are never returned here.

      Possible values: `text`, `date`, `number`, `barcode`
    - `name` (string, required): Attribute display name.
    - `value` (string | number, required): Attribute value. `text`/`date`/`barcode` are returned as strings (`date` as `YYYY-MM-DD`); `number` is returned as a number.
  - `cost` (string, required): Cost per unit, as a decimal string (range ±999,999,999.999, up to 3 decimal places). Defaults to "0" when not assigned.
  - `price` (string, required): Selling price per unit, as a decimal string (range ±999,999,999.999, up to 3 decimal places). Defaults to "0" when not assigned.
  - `quantity` (number, required): Total on-hand quantity for this item, summed across all locations. When `location_ids` is passed, summed over those locations only.
  - `quantities` (array of object, required): Per-location stock breakdown. Always present. Only locations that are not deleted and where this item has nonzero stock appear. With `location_ids` set, only the requested locations are considered. Empty array when the item has no stock at any considered location.

    - `location_id` (integer, minimum 0, maximum 2147483647, required): Location id where this stock breakdown applies.
    - `quantity` (number, required): On-hand quantity of this item at the location.
- `count` (integer, minimum 0, maximum 9007199254740991, required): Number of items in this page (`items.length`).
- `limit` (integer, minimum 0, maximum 9007199254740991, required): Page size used to build this response.
- `cursor` (integer, minimum 0, maximum 2147483647, nullable, required): Cursor to pass as `cursor` in the next request. `null` when `has_more` is `false`.
- `has_more` (boolean, required): True when another page is available. The cursor is monotonic — pass it as `cursor` on the next request to advance the page. Direction follows each resource's ordering (most resources: id ascending; transactions and orders/returns: time descending).

**400** Team is not in LOCATION mode.

- `id` (string, required): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, required): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Possible values: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, required): Human-readable summary of the error, in English.
- `correlationID` (string, required): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, required)
  - `message` (string, required)

**401** Missing, invalid, or revoked API token. `/errors/tokens/required` when no Bearer token is sent; `/errors/tokens/invalid` when the token is unknown or revoked (a revoked token may keep working for up to 60 seconds because validation results are cached).

- `id` (string, required): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, required): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Possible values: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, required): Human-readable summary of the error, in English.
- `correlationID` (string, required): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, required)
  - `message` (string, required)

**429** Rate limit exceeded. Limits are per team and shared by all of the team's API tokens: 5 requests per second and 300 requests per minute. The `RateLimit` and `X-RateLimit-*` headers reflect the per-minute window; check them and `Retry-After` before retrying. This status is also returned when the client IP exceeds 30 failed authentication attempts within 60 seconds, even if the token is valid.

- `id` (string, required): Unique exception id (`ex_` followed by 32 lowercase hex chars, no dashes — e.g. `ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a`). Quote this in support tickets so we can find the request in our logs.
- `type` (string, required): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Possible values: `/errors/not-found`, `/errors/invalid-request`, `/errors/invalid-team-mode`, `/errors/tokens/invalid`, `/errors/tokens/required`, `/errors/too-many-requests`, `/errors/core/usage-limit-exceeded`, `/errors/core/forbidden`, `/errors/core/unhandled`, `/errors/unhandled`
- `title` (string, required): Human-readable summary of the error, in English.
- `correlationID` (string, required): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. A client-supplied `X-Correlation-Id` request header (at most 128 chars of `A-Z a-z 0-9 . _ : / = -`) is echoed back here and in the response header; a missing or invalid value is silently replaced with a generated `rq_…` id.
- `instance` (string): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix. Absent on unknown-path `404` and unexpected `500` responses.
- `code` (string): Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. `not-available-for-api-token` on 403). Use this for fine-grained branching after dispatching on `type`.
- `errors` (array of object): Field-level error details. Present on request-validation `/errors/invalid-request` (400) responses. Absent on malformed-JSON `400`, `413` body-too-large, and most errors mapped from BoxHero core (which include it only when core supplies an array; this can include `403`). Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

  - `path` (array of string | number, required)
  - `message` (string, required)

Request

**cURL**

```bash
curl --request GET \
  --url 'https://rest.boxhero-app.com/v1/items' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN"
```

**JavaScript**

```javascript
const response = await fetch("https://rest.boxhero-app.com/v1/items", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
  },
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://rest.boxhero-app.com/v1/items",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
)
data = response.json()
```

**HTTP**

```http
GET /v1/items HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
```

Response

**200**

```json
{
  "items": [
    {
      "id": 14290445,
      "name": "Finish Setting Powder",
      "sku": "SKU-12345678",
      "barcode": "2097678335587",
      "photo_url": "https://your.image-server.com/item_image.png",
      "attrs": [
        {
          "id": 485697,
          "type": "text",
          "name": "Brand",
          "value": "Acme Beauty"
        },
        {
          "id": 413101,
          "type": "date",
          "name": "Expiration Date",
          "value": "2026-12-31"
        },
        {
          "id": 485086,
          "type": "number",
          "name": "Minimum Stock",
          "value": 20
        }
      ],
      "cost": "8.5",
      "price": "19.99",
      "quantity": 152,
      "quantities": [
        {
          "location_id": 47041,
          "quantity": 120
        },
        {
          "location_id": 47043,
          "quantity": 32
        }
      ]
    },
    {
      "id": 14290446,
      "name": "Hydrating Face Toner",
      "sku": "SKU-12345679",
      "barcode": "2097678335588",
      "photo_url": null,
      "attrs": [
        {
          "id": 485697,
          "type": "text",
          "name": "Brand",
          "value": "Acme Beauty"
        },
        {
          "id": 485086,
          "type": "number",
          "name": "Minimum Stock",
          "value": 15
        }
      ],
      "cost": "5.25",
      "price": "12.5",
      "quantity": 318,
      "quantities": [
        {
          "location_id": 47041,
          "quantity": 300
        },
        {
          "location_id": 47042,
          "quantity": 18
        }
      ]
    }
  ],
  "count": 2,
  "limit": 100,
  "cursor": 14290446,
  "has_more": false
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-team-mode",
  "title": "This API is only available in Location mode. For Basic or Unit mode, please contact support.",
  "instance": "/items"
}
```

**401**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "instance": "/items",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}
```

**429**

```json
{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/items",
  "retryAfter": 60
}
```