> 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/es/developers/api/reference/items/get-item.md).

# Get an item

> Returns a single item by id.

The response includes a `quantities` per-location breakdown alongside the rolled-up `quantity`; pass `location_ids` to scope the breakdown to specific locations.

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

## Autorización

- `Authorization` (string, obligatorio): Encabezado de autenticación Bearer con el formato `Bearer <token>`, donde `<token>` es tu [token de API](https://www.boxhero.io/docs/es/developers/api/authentication).

## Parámetros de ruta

- `item_id` (integer, minimum 0, maximum 2147483647, obligatorio)

## Parámetros de consulta

- `location_ids` (integer | array of integer): Scope the `quantities` breakdown to specific locations. When present, the response carries one `quantities` entry per requested location. When omitted, `quantities` still appears but only for active locations where the item has nonzero stock.

## Respuestas

**200** The requested item.

- `item` (Item, obligatorio): An item — the smallest unit of inventory tracked by BoxHero. Each item carries an SKU, barcode, cost, selling price, on-hand quantity, and any custom attributes you have defined.

  - `id` (integer, minimum 0, maximum 2147483647, obligatorio): Item id.
  - `name` (string, obligatorio): Item display name.
  - `sku` (string, obligatorio): Stock Keeping Unit. Unique within the team when set. Empty string when not assigned.
  - `barcode` (string, obligatorio): Primary barcode for the item. Empty string when not assigned.
  - `photo_url` (string, nullable, obligatorio): URL of the item's photo. `null` when no photo is set.
  - `attrs` (array of ItemAttr, obligatorio): Custom attribute values attached to the item. Manage the underlying attribute specs via `/item-attrs`.

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

      Valores posibles: `text`, `date`, `number`, `barcode`
    - `name` (string, obligatorio): Attribute display name.
    - `value` (string | number, obligatorio): Attribute value. `text`/`date`/`barcode` are returned as strings (`date` as `YYYY-MM-DD`); `number` is returned as a number.
  - `cost` (string, obligatorio): 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, obligatorio): 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, obligatorio): Total on-hand quantity for this item, summed across all locations.
  - `quantities` (array of object, obligatorio): Per-location stock breakdown. Always present. With `location_ids` set, one entry per requested location. Without `location_ids`, one entry per active location where this item has nonzero stock (empty array when the item is out of stock everywhere).

    - `location_id` (integer, minimum 0, maximum 2147483647, obligatorio): Location id where this stock breakdown applies.
    - `quantity` (number, obligatorio): On-hand quantity of this item at the location.

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

- `id` (string, obligatorio): 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, obligatorio): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Valores posibles: `/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, obligatorio): Human-readable summary of the error, in English.
- `correlationID` (string, obligatorio): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. Pass an `X-Correlation-Id` request header to thread your trace through to ours.
- `instance` (string, obligatorio): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix.
- `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 `/errors/invalid-request` (400) responses. Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

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

**401** Missing or invalid API token.

- `id` (string, obligatorio): 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, obligatorio): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Valores posibles: `/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, obligatorio): Human-readable summary of the error, in English.
- `correlationID` (string, obligatorio): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. Pass an `X-Correlation-Id` request header to thread your trace through to ours.
- `instance` (string, obligatorio): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix.
- `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 `/errors/invalid-request` (400) responses. Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

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

**404** No item with the given id was found in this team.

- `id` (string, obligatorio): 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, obligatorio): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Valores posibles: `/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, obligatorio): Human-readable summary of the error, in English.
- `correlationID` (string, obligatorio): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. Pass an `X-Correlation-Id` request header to thread your trace through to ours.
- `instance` (string, obligatorio): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix.
- `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 `/errors/invalid-request` (400) responses. Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

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

**429** Rate limit exceeded. Check `RateLimit`, `Retry-After`, and `X-RateLimit-*` response headers before retrying.

- `id` (string, obligatorio): 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, obligatorio): Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on `title`.

  Valores posibles: `/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, obligatorio): Human-readable summary of the error, in English.
- `correlationID` (string, obligatorio): Request correlation id (`rq_` followed by 32 lowercase hex chars, no dashes — e.g. `rq_01abf3...`). Identical to the `X-Correlation-Id` response header. Pass an `X-Correlation-Id` request header to thread your trace through to ours.
- `instance` (string, obligatorio): Pointer to the specific failing resource (e.g. `/items/12345`). Path-only, no `/v1` version prefix.
- `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 `/errors/invalid-request` (400) responses. Each entry locates a single failure via JSONPath-like `path` segments and a human-readable `message`.

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

Solicitud

**cURL**

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

**JavaScript**

```javascript
const response = await fetch("https://rest.boxhero-app.com/v1/items/{item_id}", {
  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/{item_id}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
)
data = response.json()
```

**HTTP**

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

Respuesta

**200**

```json
{
  "item": {
    "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.50",
    "price": "19.99",
    "quantity": 152,
    "quantities": [
      {
        "location_id": 47041,
        "quantity": 120
      },
      {
        "location_id": 47043,
        "quantity": 32
      }
    ]
  }
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-team-mode",
  "title": "This API is only available in Location mode. For Basic or Unit mode, please contact support.",
  "instance": "/items/12345"
}
```

**401**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}
```

**404**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/not-found",
  "title": "No item with the given id was found in this team.",
  "instance": "/items/12345"
}
```

**429**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/items/12345",
  "retryAfter": 60
}
```