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

# Create an item

> Creates a new item in the team.

Pass `location_id` (query) together with `quantity` (body) to seed initial stock at a single location; otherwise the item starts with zero stock everywhere. When the team has more than one active location and `quantity` is provided without `location_id`, the request fails with `402` (location quota).

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

## 認証

- `Authorization` (string, 必須): `Bearer <token>` 形式の Bearer 認証ヘッダーです。`<token>` には [APIトークン](https://www.boxhero.io/docs/ja/developers/api/authentication) を指定します。

## クエリパラメータ

- `location_id` (integer, minimum 0, maximum 2147483647): Location at which to seed initial stock. Required together with the body's `quantity` when the team has more than one active location.

## リクエストボディ

- `name` (string, min length 1, max length 255, 必須): Item display name. 1–255 characters.
- `sku` (string, min length 1, max length 255): Stock Keeping Unit. Optional, but must be unique across the team when set.
- `barcode` (string, max length 255): Primary barcode for the item. Optional.
- `photo_url` (string, max length 2048): Public URL of the item's photo. Optional.
- `cost` (string): Cost per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: `"12345.234"`. The team's currency is reported on `GET /v1/teams/linked`.
- `price` (string): Selling price per unit, as a decimal string. Range ±999,999,999.999 with up to 3 decimal places. Example: `"12345.234"`. The team's currency is reported on `GET /v1/teams/linked`.
- `attrs` (array of object): Custom attribute values. Official request format is `[{ "id": <attr_id>, "value": <value> }, ...]`. The legacy object form `{ "<attr_id>": <value> }` is still accepted for compatibility.

  - `id` (integer, minimum 0, maximum 2147483647, 必須): Attribute spec id.
  - `value` (string | number, 必須): Attribute value (typed per the spec).
- `quantity` (number, nullable): Initial on-hand quantity. Pass together with the `location_id` query to seed stock at a single location. Omit (or set `null`) to start with zero stock everywhere. Must be non-zero when provided.

## レスポンス

**201** The created item's id.

- `id` (integer, minimum 0, maximum 2147483647, 必須): Id of the newly created item.

**400** Request validation failed (e.g. duplicate SKU, invalid attribute value, file-type attribute, or `quantity = 0`). See the response body for field-level errors.

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

  指定可能な値: `/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, 必須): Human-readable summary of the error, in English.
- `correlationID` (string, 必須): 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, 必須): 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, 必須)
  - `message` (string, 必須)

**401** Missing or invalid API token.

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

  指定可能な値: `/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, 必須): Human-readable summary of the error, in English.
- `correlationID` (string, 必須): 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, 必須): 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, 必須)
  - `message` (string, 必須)

**402** The team's item quota has been reached, or initial stock was requested at a location the current plan does not cover. Upgrade the plan or delete an existing item / pass a covered `location_id` to continue.

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

  指定可能な値: `/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, 必須): Human-readable summary of the error, in English.
- `correlationID` (string, 必須): 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, 必須): 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, 必須)
  - `message` (string, 必須)

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

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

  指定可能な値: `/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, 必須): Human-readable summary of the error, in English.
- `correlationID` (string, 必須): 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, 必須): 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, 必須)
  - `message` (string, 必須)

リクエスト

**cURL**

```bash
curl --request POST \
  --url 'https://rest.boxhero-app.com/v1/items' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Finish Setting Powder",
    "sku": "SKU-12345678",
    "barcode": "2097678335587",
    "photo_url": "https://your.image-server.com/item_image.png",
    "cost": "8.50",
    "price": "19.99",
    "attrs": [
      {
        "id": 485086,
        "value": 20
      },
      {
        "id": 413101,
        "value": "2026-12-31"
      }
    ],
    "quantity": 32
  }'
```

**JavaScript**

```javascript
const response = await fetch("https://rest.boxhero-app.com/v1/items", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Finish Setting Powder",
    "sku": "SKU-12345678",
    "barcode": "2097678335587",
    "photo_url": "https://your.image-server.com/item_image.png",
    "cost": "8.50",
    "price": "19.99",
    "attrs": [
      {
        "id": 485086,
        "value": 20
      },
      {
        "id": 413101,
        "value": "2026-12-31"
      }
    ],
    "quantity": 32
  }),
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://rest.boxhero-app.com/v1/items",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "name": "Finish Setting Powder",
        "sku": "SKU-12345678",
        "barcode": "2097678335587",
        "photo_url": "https://your.image-server.com/item_image.png",
        "cost": "8.50",
        "price": "19.99",
        "attrs": [
            {
                "id": 485086,
                "value": 20,
            },
            {
                "id": 413101,
                "value": "2026-12-31",
            },
        ],
        "quantity": 32,
    },
)
data = response.json()
```

**HTTP**

```http
POST /v1/items HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Finish Setting Powder",
  "sku": "SKU-12345678",
  "barcode": "2097678335587",
  "photo_url": "https://your.image-server.com/item_image.png",
  "cost": "8.50",
  "price": "19.99",
  "attrs": [
    {
      "id": 485086,
      "value": 20
    },
    {
      "id": 413101,
      "value": "2026-12-31"
    }
  ],
  "quantity": 32
}
```

レスポンス

**201**

```json
{
  "id": 14290445
}
```

**400**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-request",
  "title": "Request validation failed (e.g. duplicate SKU, invalid attribute value, file-type attribute, or quantity = 0). See the response body for field-level errors.",
  "instance": "/items"
}
```

**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"
}
```

**402**

```json
{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/core/usage-limit-exceeded",
  "title": "The team's item quota has been reached, or initial stock was requested at a location the current plan does not cover. Upgrade the plan or delete an existing item / pass a covered location_id to continue.",
  "instance": "/items"
}
```

**429**

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