Item attributes
Item attributes define the names and values used by inventory variations. Attribute definitions belong to the account and are not restricted to one inventory location.
The item attribute object
| Field | Type | Description |
|---|---|---|
id | string | Unique attribute UUID. |
object | string | Always item_attribute. |
name | string | Internal attribute name. |
display_name | string or null | Optional customer-facing name. |
type | string | text, unique, or select. |
publish_on_documents | boolean | Whether the selected attribute appears on customer-facing documents. |
item_usage_count | integer | Number of inventory items currently using the attribute. |
values | array | Ordered pre-filled values for a select attribute. |
Each value contains id, object, value, and display_order.
List item attributes
GET/api/v3/item-attributes
Required scope: items:read
Returns account-owned attributes ordered by name. The q query parameter searches attribute and display names. Standard page and limit pagination parameters are supported.
Retrieve an item attribute
GET/api/v3/item-attributes/{attribute_id}
Required scope: items:read
Returns one account-owned attribute with its ordered values.
Create an item attribute
POST/api/v3/item-attributes
Required scope: items:write
Creates an attribute. The current user must retain inventory-modify permission. Send name, optional display_name, type, publish_on_documents, and the complete values array. Only select attributes accept values, and they require at least one. Send an Idempotency-Key when a request might be retried.
Update an item attribute
PATCH/api/v3/item-attributes/{attribute_id}
Required scope: items:write
Replaces the editable definition. Include an existing value's id to preserve it, omit id to add a value, and order the array as it should be displayed. An in-use type cannot be changed, and an option referenced by an existing variation cannot be removed. These unsafe changes return a conflict response. An optional Idempotency-Key makes exact retries safe.