Attributes
The 19 tools of the Attributes toolset in the Catalog area, with their permissions, approval rules and inputs.
Ezen az oldalon
Toolset attributes, 19 tools.
Records
attribute
A product property such as brand, color or size, with its settings. Rows carry values_count and products_count instead of the values; attribute_value_list pages and searches the values of one attribute. Product attributes are read with product_get include attributes, and the filter attributes of a category with product_category_get include attributes.
- Permission:
products.read - Tools:
attribute_list,attribute_get - Sorts:
rank,name,handle,type,created_at - Written by customers or third parties, so data and never instructions:
name,description
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
q | string | Search in name and handle | |
id | list of string | ||
handle | list of string | ||
type | list of string | Only these value types. one of "select", "color", "text", "number" | |
role | list of string | Only attributes holding these roles. one of "brand", "color", "size", "material", "pattern", "gender", "age_group" | |
group_id | list of string | Only attributes in these groups | |
is_default | boolean | true: only attributes shown on every product; false: only the others | |
builtin | boolean | true: only the built-in product-field attributes; false: only the store's own |
attribute_group
A specification group attributes are shown under on the product page, such as Dimensions. Ranked groups come first.
- Permission:
products.read - Tools:
attribute_group_list - Sorts:
rank,name,created_at - Written by customers or third parties, so data and never instructions:
name
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
q | string | Search in the names |
attribute_value
One value of an attribute, with products_count (the products holding it). Ranked values come first, then alphabetical; q searches the values in any letter case.
- Permission:
products.read - Tools:
attribute_value_list - Sorts:
rank,value,created_at - Written by customers or third parties, so data and never instructions:
value,metadata
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
attribute_id | string | yes | Attribute id |
q | string | Search in the values |
Actions
attribute_create
Create a product attribute such as Material or Pages.
- Action key:
attribute.create - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
handle | string | URL key of lower-case letters a-z, digits and hyphens; derived from the name when left out and fixed once created | |
description | string or null | ||
type | string | Value type, select by default. text and number are always single and open; color is always preset. one of "select", "color", "text", "number" | |
unit | string or null | Unit label of a number attribute, such as cm. at most 16 characters | |
selection_mode | string | one of "single", "multiple" | |
entry_type | string | one of "preset", "open" | |
is_default | boolean | Show the attribute on every product | |
role | string or null | What the attribute stands for, whatever it is called: brand, color, size, material, pattern, gender or age_group. One attribute per role; null takes it away. one of "brand", "color", "size", "material", "pattern", "gender", "age_group" | |
rank | integer or null | Position among attributes, 0 first; unranked ones follow by name; null unranks. at least 0 | |
group_id | string or null | Specification group from attribute_group_list; null for none | |
show_on_product_page | boolean | Listed in the product page specifications | |
show_on_card | boolean | Shown on product cards in listings | |
filterable | boolean | Offered as a listing filter; select and color attributes only | |
in_feeds | boolean | Sent to marketplace and shopping feeds | |
searchable | boolean | Its values find products in search; the brand is searchable by default |
Example input:
{
"name": "Material",
"type": "select",
"filterable": true
}attribute_delete
Delete an attribute and all its values.
Existing links to products, categories and articles are removed with it. The products stay.
- Action key:
attribute.delete - Permission:
products.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with
run_destructive_action. - Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute id |
Example input:
{
"id": "019bb16c-5c98-717a-a047-bf3a2819b5a2"
}attribute_group_create
Create a specification group; attribute_update puts attributes in it with group_id.
- Action key:
attribute_group.create - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Group name, such as Dimensions. 1 to 120 characters |
rank | integer or null | Position among the groups, 0 first. at least 0 |
Example input:
{
"name": "Dimensions"
}attribute_group_delete
Delete a specification group.
Its attributes stay, in no group.
- Action key:
attribute_group.delete - Permission:
products.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with
run_destructive_action. - Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute group id |
Example input:
{
"id": "019bb193-1900-7ae0-a53f-e43cf6bf2206"
}attribute_group_reorder
Put the specification groups in a new leading order.
ids become the first groups in that order; the other ranked groups keep their order after them.
- Action key:
attribute_group.reorder - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
ids | list of string | yes | Group ids in the new order. 1 to 1000 items |
Example input:
{
"ids": [
"019bb193-1900-7ae0-a53f-e43cf6bf2206",
"019bb196-14a1-7a29-9e06-ecff8f16debe"
]
}attribute_group_update
Rename a specification group or move it among the groups.
- Action key:
attribute_group.update - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute group id |
name | string | New name. 1 to 120 characters | |
rank | integer or null | New position, 0 first; null unranks. at least 0 |
Example input:
{
"id": "019bb193-1900-7ae0-a53f-e43cf6bf2206",
"name": "Size and weight"
}attribute_reorder
Put attributes in a new leading order.
ids become the first attributes in that order; the other ranked attributes keep their order after them.
- Action key:
attribute.reorder - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
ids | list of string | yes | Attribute ids in the new order. 1 to 1000 items |
Example input:
{
"ids": [
"019bb16c-5c98-717a-a047-bf3a2819b5a2",
"019bb16f-e0f6-76c6-9e2f-c083ff7fe50b"
]
}attribute_update
Change an attribute: its name, type, placement, visibility and flags.
Only the fields you send change. The handle never changes after create.
- Action key:
attribute.update - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute id |
name | string | ||
description | string or null | ||
type | string | New value type; only select and color convert into each other. one of "select", "color", "text", "number" | |
unit | string or null | New unit label of a number attribute; null clears it. at most 16 characters | |
selection_mode | string | one of "single", "multiple" | |
entry_type | string | one of "preset", "open" | |
is_default | boolean | Show the attribute on every product | |
role | string or null | What the attribute stands for, whatever it is called: brand, color, size, material, pattern, gender or age_group. One attribute per role; null takes it away. one of "brand", "color", "size", "material", "pattern", "gender", "age_group" | |
rank | integer or null | Position among attributes, 0 first; unranked ones follow by name; null unranks. at least 0 | |
group_id | string or null | Specification group from attribute_group_list; null for none | |
show_on_product_page | boolean | Listed in the product page specifications | |
show_on_card | boolean | Shown on product cards in listings | |
filterable | boolean | Offered as a listing filter; select and color attributes only | |
in_feeds | boolean | Sent to marketplace and shopping feeds | |
searchable | boolean | Its values find products in search; the brand is searchable by default |
Example input:
{
"id": "019bb16c-5c98-717a-a047-bf3a2819b5a2",
"filterable": true,
"show_on_card": true
}attribute_value_create
Add a value to an attribute.
- Action key:
attribute_value.create - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.
| Field | Type | Required | Description |
|---|---|---|---|
attribute_id | string | yes | Attribute id |
value | string | yes | at least 1 characters |
color | string or null | Swatch of a color attribute value, a hex color such as #1a2b3c. at most 7 characters | |
icon | string or null | The value's icon: an icon name such as lucide:star, a platform logo as logo:<id> (steam, epic-games, gog, playstation, xbox, nintendo, battle-net, ea, ubisoft, rockstar, microsoft, windows, macos, linux), or an uploaded SVG as svg:<svg …>; null removes it | |
rank | integer or null | Position among the values, 0 first. at least 0 | |
metadata | map of string or number or boolean or list of any value or map of any value or null |
Example input:
{
"attribute_id": "019bb16c-5c98-717a-a047-bf3a2819b5a2",
"value": "Cotton"
}attribute_value_delete
Delete a value of an attribute.
Product and article links that reference it are removed with it.
- Action key:
attribute_value.delete - Permission:
products.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with
run_destructive_action. - Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute value id |
Example input:
{
"id": "019bb19b-d94f-7f27-a94d-1a4d43187e0a"
}attribute_value_merge
Merge one value of an attribute into another value of the same attribute.
For two spellings of one brand, for example: every product and article holding the source value holds the target instead, and the source value is deleted. Only when the merchant asked for it; unused values are never merged or deleted on their own.
- Action key:
attribute_value.merge - Permission:
products.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with
run_destructive_action. - Retries: runs at most once; a repeat with the same idempotency key returns the first result.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute value id to merge away |
target_id | string | yes | Attribute value id of the same attribute that stays |
Example input:
{
"id": "019bb19b-d94f-7f27-a94d-1a4d43187e0a",
"target_id": "019bb19e-77e0-720d-8566-64cd0e8233b2"
}attribute_value_reorder
Put the values of an attribute in a new leading order.
ids become the first values in that order; the other ranked values keep their order after them.
- Action key:
attribute_value.reorder - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
attribute_id | string | yes | Attribute id |
ids | list of string | yes | Value ids in the new order. 1 to 1000 items |
Example input:
{
"attribute_id": "019bb16c-5c98-717a-a047-bf3a2819b5a2",
"ids": [
"019bb19b-d94f-7f27-a94d-1a4d43187e0a",
"019bb19e-77e0-720d-8566-64cd0e8233b2"
]
}attribute_value_update
Change a value of an attribute: its text, swatch, icon or position.
- Action key:
attribute_value.update - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Attribute value id |
value | string | at least 1 characters | |
color | string or null | New swatch hex color; null clears it. at most 7 characters | |
icon | string or null | New icon: an icon name such as lucide:star, a platform logo as logo:<id> (steam, epic-games, gog, playstation, xbox, nintendo, battle-net, ea, ubisoft, rockstar, microsoft, windows, macos, linux), or an uploaded SVG as svg:<svg …>; null removes it | |
rank | integer or null | New position among the values, 0 first; null unranks. at least 0 | |
metadata | map of string or number or boolean or list of any value or map of any value or null or null |
Example input:
{
"id": "019bb19b-d94f-7f27-a94d-1a4d43187e0a",
"value": "Organic cotton"
}category_attribute_set
Change a product category's filter attributes in one call.
add links the attribute ids, remove unlinks those, and the rest stay as they are. Only select and color attributes filter a category; built-in, text and number attributes are refused. Answers with the category attributes afterwards. Read them with product_category_get include attributes.
- Action key:
category_attribute.set - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | Product category id |
add | list of string | Attribute ids to link to the category | |
remove | list of string | Attribute ids to unlink from the category |
Example input:
{
"category_id": "019bb50f-c863-7fa2-b8ae-0d6b18758e24",
"add": [
"019bb16c-5c98-717a-a047-bf3a2819b5a2"
],
"remove": [
"019bb16f-e0f6-76c6-9e2f-c083ff7fe50b"
]
}product_attribute_set
Set the values one attribute holds on a product.
Afterwards the attribute holds exactly value_ids plus values, so send both empty to clear it. values are texts; one that matches an existing value (any letter case for a select or colour) takes that value, and a new value is created only when the attribute is open to free entry. A number attribute takes plain numbers such as 12 or 1.5. A single-value attribute takes one value. Built-in attributes are product fields and are not set here. Read the current values with product_get include attributes.
- Action key:
product_attribute.set - Permission:
products.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | Product id |
attribute_id | string | yes | Attribute id |
value_ids | list of string | Existing value ids of the attribute | |
values | list of string | Value texts, matched to existing values or created when entry is open. at most 100 items |
Example inputs:
{
"product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
"attribute_id": "019bb16c-5c98-717a-a047-bf3a2819b5a2",
"values": [
"Cotton"
]
}{
"product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
"attribute_id": "019bb16c-5c98-717a-a047-bf3a2819b5a2"
}