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 quantity is provided without location_id, the team must have exactly one active location (it is used automatically); otherwise the request fails with 400. Initial stock is applied in a second step after the item is created: if it fails, the item still exists and the error is returned, so add stock with a transaction instead of re-creating the item.

POSThttps://rest.boxhero-app.com/v1/items

การยืนยันสิทธิ์

Authorizationstringจำเป็น

เฮดเดอร์การยืนยันตัวตนแบบ Bearer ในรูปแบบ Bearer <token> โดย <token> คือ โทเค็น API ของคุณ

พารามิเตอร์ของคิวรี

location_idintegerminimum 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.

เนื้อหาคำขอ

namestringmin length 1, max length 255จำเป็น

Item display name. 1–255 characters.

skustringmin length 1, max length 255

Stock Keeping Unit. Optional; a random SKU-XXXXXXXX is generated when omitted. Must be unique across the team.

barcodestringmax length 255

Primary barcode for the item. Optional.

photo_urlstringmax length 2048

Public URL of the item's photo. Optional.

coststring

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.

pricestring

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.

attrsarray 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.

แสดงพร็อพเพอร์ตี

idintegerminimum 0, maximum 2147483647จำเป็น

Attribute spec id.

valuestring | numberจำเป็น

Attribute value (typed per the spec).

quantitynumbernullable

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.

การตอบกลับ

201The created item's id.

idintegerminimum 0, maximum 2147483647จำเป็น

Id of the newly created item.

400Request validation failed (e.g. duplicate SKU, invalid attribute value, file-type attribute, quantity = 0, or quantity given without location_id when the team does not have exactly one active location). See the response body for field-level errors.

idstringจำเป็น

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.

typestringจำเป็น

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

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

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.

instancestring

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.

codestring

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.

errorsarray 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.

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

401Missing, 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).

idstringจำเป็น

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.

typestringจำเป็น

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestring

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.

codestring

errorsarray of object

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

402The team is over one of its plan limits (items, locations, or members). Upgrade the plan or reduce usage to continue.

idstringจำเป็น

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.

typestringจำเป็น

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestring

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.

codestring

errorsarray of object

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

403The API token's member lacks permission to manage items. A non-zero cost also requires the purchase permission, a non-zero price the sales permission, and a non-zero initial quantity the stock-adjustment permission.

idstringจำเป็น

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.

typestringจำเป็น

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestring

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.

codestring

errorsarray of object

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

413Request body exceeds the size limit (1 MiB). Returned with type /errors/invalid-request.

idstringจำเป็น

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.

typestringจำเป็น

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestring

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.

codestring

errorsarray of object

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

429Rate 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.

idstringจำเป็น

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.

typestringจำเป็น

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringจำเป็น

Human-readable summary of the error, in English.

correlationIDstringจำเป็น

instancestring

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.

codestring

errorsarray of object

แสดงพร็อพเพอร์ตี

patharray of string | numberจำเป็น

messagestringจำเป็น

คำขอ

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
  }'

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();

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()

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
}

การตอบกลับ

{
  "id": 14290445
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Request validation failed (e.g. duplicate SKU, invalid attribute value, file-type attribute, quantity = 0, or quantity given without location_id when the team does not have exactly one active location). See the response body for field-level errors.",
  "instance": "/items"
}

{
  "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"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/core/usage-limit-exceeded",
  "title": "The team is over one of its plan limits (items, locations, or members). Upgrade the plan or reduce usage to continue.",
  "instance": "/items"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/core/forbidden",
  "title": "The API token's member lacks permission to manage items. A non-zero cost also requires the purchase permission, a non-zero price the sales permission, and a non-zero initial quantity the stock-adjustment permission.",
  "instance": "/items",
  "code": "feature-auth-error-example"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/invalid-request",
  "title": "Request body is too large.",
  "instance": "/items"
}

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