Start here when you need reusable catalog values, structured option metadata, or attribute relationships before choosing a Management API route.
Use this page to decide whether the job belongs to template setup, field definitions, attribute values, item relationships, linked attributes, bulk work, or variant shipping attributes. Use the API reference for exact request fields, response fields, enum values, and status codes.
Attributes let you describe catalog records with reusable structured values such as color, size, material, season, or internal classification.
The model has two parts:
- Attribute template: the reusable group and rules. Examples:
Color, Size, Material, or Season.
- Attribute: one option inside a template. Examples:
Red, XL, Cotton, or Winter.
A simple way to remember the model: the template is the question, and the attribute is the answer. A Color template can contain Forest Green, Black, and Sand Beige; a product can then attach Color / Forest Green.
The current Management API attribute surface has 29 operations across three hubs:
- Attribute Templates has 6 operations for template list, create, read, update, delete, and bulk create.
- Attribute Template Fields has 2 operations for field upsert and field delete.
- Attributes has 21 operations for value records, item relationships, linked attributes, bulk value work, and bulk relationship work.
| Job | Use | Why |
|---|
| Define which resources can use a set of values | Attribute Templates reference | Templates own the reusable key, name, filterable/translatable flags, resource list, and custom field list. |
| Add or replace structured option metadata | Attribute Template Fields reference | Field upsert changes the definition used by attributes inside that template; field delete removes the definition and stored values for that field. |
| Create or update the values inside one template | Attributes reference | Attribute value routes own keys, names, descriptions, translations, custom field values, image values, and image-object values. |
| Attach an existing value to products, categories, tags, media, organisations, or merchant users | Attributes relationship operations | Relationship routes create or remove item-to-attribute links without deleting the shared attribute. |
| Link one attribute to another attribute | Link attributes or Delete attribute link | Links let reads return related values from another template alongside directly attached values. |
| Replace shipping flags on a variant | Variants reference | Variant shipping attributes are managed from the Variants reference, not from the general attribute template routes. |
Use these facts to choose the right reference. Use operation pages for exact fields, validation, limits, status codes, and response shapes.
- The catalog model supports these resource values:
product, product-variant, product-bundle, category, image, video, file, tag, organisation, and merchant-user.
- The field keys
key, name, and description are reserved because they already belong to the base attribute model.
- Template fields add structured data to each option, such as text, number, boolean, color, image, or image object.
- Attribute reads include translations. Image fields are returned as CDN URLs, and image-object fields include the resolved image object when it can be found.
- Variant shipping attributes are managed from the Variants reference, not from the general attribute template routes.
Attaching an attribute to a resource creates an attribute-to-item relationship. Detaching removes that link; it does not delete the shared attribute value.
An attribute can also link to another attribute in a different template. Attribute detail responses include linked attributes, and item attribute reads include linked attributes alongside directly attached attributes. Linking does not duplicate every item relationship, and unlinking does not delete direct item-to-attribute relationships.
Bulk relationship requests accept up to 50 attribute rows. Bulk template, attribute, and relationship routes return separate successful and failed collections.
Creating or updating an attribute publishes an attribute-updated event. Deleting an attribute publishes an attribute-deleted event. Bulk create and update still publish attribute-updated events for successful attributes. Bulk delete publishes attribute-deleted events for successful deletes.
Attribute templates, attributes, fields, relationships, bulk work, and links are available through Management API routes. Start with Management API latest, then use Attribute Templates, Attribute Template Fields, and Attributes. Use Variants for variant shipping attributes.
Attributes
# Attributes
Start here when you need reusable catalog values, structured option metadata, or attribute relationships before choosing a Management API route.
Use this page to decide whether the job belongs to template setup, field definitions, attribute values, item relationships, linked attributes, bulk work, or variant shipping attributes. Use the API reference for exact request fields, response fields, enum values, and status codes.
## The core idea
Attributes let you describe catalog records with reusable structured values such as color, size, material, season, or internal classification.
The model has two parts:
- **Attribute template**: the reusable group and rules. Examples: `Color`, `Size`, `Material`, or `Season`.
- **Attribute**: one option inside a template. Examples: `Red`, `XL`, `Cotton`, or `Winter`.
A simple way to remember the model: the template is the question, and the attribute is the answer. A `Color` template can contain `Forest Green`, `Black`, and `Sand Beige`; a product can then attach `Color / Forest Green`.
## Choose the right surface
The current Management API attribute surface has 29 operations across three hubs:
- **Attribute Templates** has 6 operations for template list, create, read, update, delete, and bulk create.
- **Attribute Template Fields** has 2 operations for field upsert and field delete.
- **Attributes** has 21 operations for value records, item relationships, linked attributes, bulk value work, and bulk relationship work.
| Job | Use | Why |
| --- | --- | --- |
| Define which resources can use a set of values | [Attribute Templates reference](/reference/attribute-templates) | Templates own the reusable key, name, filterable/translatable flags, resource list, and custom field list. |
| Add or replace structured option metadata | [Attribute Template Fields reference](/reference/attribute-template-fields) | Field upsert changes the definition used by attributes inside that template; field delete removes the definition and stored values for that field. |
| Create or update the values inside one template | [Attributes reference](/reference/attributes) | Attribute value routes own keys, names, descriptions, translations, custom field values, image values, and image-object values. |
| Attach an existing value to products, categories, tags, media, organisations, or merchant users | [Attributes relationship operations](/reference/attributes) | Relationship routes create or remove item-to-attribute links without deleting the shared attribute. |
| Link one attribute to another attribute | [Link attributes](/reference/attributes/link-attributes) or [Delete attribute link](/reference/attributes/delete-attribute-link) | Links let reads return related values from another template alongside directly attached values. |
| Replace shipping flags on a variant | [Variants reference](/reference/variants) | Variant shipping attributes are managed from the Variants reference, not from the general attribute template routes. |
## Contract facts to keep in mind
Use these facts to choose the right reference. Use operation pages for exact fields, validation, limits, status codes, and response shapes.
- The catalog model supports these resource values: `product`, `product-variant`, `product-bundle`, `category`, `image`, `video`, `file`, `tag`, `organisation`, and `merchant-user`.
- The field keys `key`, `name`, and `description` are reserved because they already belong to the base attribute model.
- Template fields add structured data to each option, such as text, number, boolean, color, image, or image object.
- Attribute reads include translations. Image fields are returned as CDN URLs, and image-object fields include the resolved image object when it can be found.
- Variant shipping attributes are managed from the Variants reference, not from the general attribute template routes.
## Relationships and links
Attaching an attribute to a resource creates an attribute-to-item relationship. Detaching removes that link; it does not delete the shared attribute value.
An attribute can also link to another attribute in a different template. Attribute detail responses include linked attributes, and item attribute reads include linked attributes alongside directly attached attributes. Linking does not duplicate every item relationship, and unlinking does not delete direct item-to-attribute relationships.
Bulk relationship requests accept up to 50 attribute rows. Bulk template, attribute, and relationship routes return separate successful and failed collections.
## Events and bulk work
Creating or updating an attribute publishes an attribute-updated event. Deleting an attribute publishes an attribute-deleted event. Bulk create and update still publish attribute-updated events for successful attributes. Bulk delete publishes attribute-deleted events for successful deletes.
## Working with the API
Attribute templates, attributes, fields, relationships, bulk work, and links are available through Management API routes. Start with [Management API latest](/apis/management/latest), then use [Attribute Templates](/reference/attribute-templates), [Attribute Template Fields](/reference/attribute-template-fields), and [Attributes](/reference/attributes). Use [Variants](/reference/variants) for variant shipping attributes.
