> 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/zh-tw/developers/api/reference/items.md).

# Items

> Items — the smallest unit of inventory tracked by BoxHero.

Each item carries an SKU, barcode, cost, price, and any custom attributes you have defined.

## Item 物件

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, 必填): Item id.
- `name` (string, 必填): Item display name.
- `sku` (string, 必填): Stock Keeping Unit. Unique within the team when set. Empty string when not assigned.
- `barcode` (string, 必填): Primary barcode for the item. Empty string when not assigned.
- `photo_url` (string, nullable, 必填): URL of the item's photo. `null` when no photo is set.
- `attrs` (array of ItemAttr, 必填): Custom attribute values attached to the item. Manage the underlying attribute specs via `/item-attrs`.

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

    可能的值: `text`, `date`, `number`, `barcode`
  - `name` (string, 必填): Attribute display name.
  - `value` (string | number, 必填): Attribute value. `text`/`date`/`barcode` are returned as strings (`date` as `YYYY-MM-DD`); `number` is returned as a number.
- `cost` (string, 必填): 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, 必填): 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, 必填): Total on-hand quantity for this item, summed across all locations.
- `quantities` (array of object, 必填): 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, 必填): Location id where this stock breakdown applies.
  - `quantity` (number, 必填): On-hand quantity of this item at the location.

範例

```json
{
  "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
    }
  ]
}
```

## 端點

- [List items](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/list-items) `GET /v1/items`
- [Create an item](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/create-item) `POST /v1/items`
- [Get an item](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/get-item) `GET /v1/items/{item_id}`
- [Update an item](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/update-item) `PUT /v1/items/{item_id}`
- [Delete an item](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/delete-item) `DELETE /v1/items/{item_id}`
- [Get an item by SKU](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/get-item-by-sku) `GET /v1/items/by-sku/{sku}`
- [Update an item by SKU](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/update-item-by-sku) `PUT /v1/items/by-sku/{sku}`
- [Delete an item by SKU](https://www.boxhero.io/docs/zh-tw/developers/api/reference/items/delete-item-by-sku) `DELETE /v1/items/by-sku/{sku}`