Update an item

Partially updates an item.

Only the fields you include are changed. Use attrs[<id>] = null to remove a single custom attribute value. Stock levels are not modified here — issue a transaction instead.

PUThttps://rest.boxhero-app.com/v1/items/{item_id}

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

Authorizationstringจำเป็น

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

พารามิเตอร์ของพาธ

item_idintegerminimum 0, maximum 2147483647จำเป็น

เนื้อหาคำขอ

namestringmin length 1, max length 255

New display name. 1–255 characters.

skustringmax length 255

New SKU. An empty string is ignored (the SKU is left unchanged); an SKU cannot be cleared. Must remain unique within the team.

barcodestringmax length 255

New primary barcode.

photo_urlstringmax length 2048

New photo URL. Pass an empty string to clear.

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

Patch attribute values. Official request format is [{ "id": <attr_id>, "value": <value> }, ...]. Set value to null to remove that attribute. The legacy object form { "<attr_id>": <value> } is still accepted for compatibility.

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

idintegerminimum 0, maximum 2147483647จำเป็น

Attribute spec id.

valuestring | numbernullableจำเป็น

Attribute value (typed per the spec); null removes the attribute.

การตอบกลับ

200The updated item's id.

idintegerminimum 0, maximum 2147483647จำเป็น

Id of the updated item.

400Request validation failed (e.g. duplicate SKU, invalid attribute value, file-type attribute). 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 and a non-zero price the sales 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จำเป็น

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

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 PUT \
  --url 'https://rest.boxhero-app.com/v1/items/{item_id}' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Finish Setting Powder",
    "sku": "SKU-12345678",
    "attrs": [
      {
        "id": 485697,
        "value": null
      },
      {
        "id": 485086,
        "value": 20
      }
    ]
  }'

const response = await fetch("https://rest.boxhero-app.com/v1/items/{item_id}", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Finish Setting Powder",
    "sku": "SKU-12345678",
    "attrs": [
      {
        "id": 485697,
        "value": null
      },
      {
        "id": 485086,
        "value": 20
      }
    ]
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    "https://rest.boxhero-app.com/v1/items/{item_id}",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "name": "Finish Setting Powder",
        "sku": "SKU-12345678",
        "attrs": [
            {
                "id": 485697,
                "value": None,
            },
            {
                "id": 485086,
                "value": 20,
            },
        ],
    },
)
data = response.json()

PUT /v1/items/{item_id} HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Finish Setting Powder",
  "sku": "SKU-12345678",
  "attrs": [
    {
      "id": 485697,
      "value": null
    },
    {
      "id": 485086,
      "value": 20
    }
  ]
}

การตอบกลับ

{
  "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). See the response body for field-level errors.",
  "instance": "/items/12345"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "instance": "/items/12345",
  "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/12345"
}

{
  "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 and a non-zero price the sales permission.",
  "instance": "/items/12345",
  "code": "feature-auth-error-example"
}

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "type": "/errors/not-found",
  "title": "No item with the given id was found in this team.",
  "instance": "/items/12345"
}

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

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