Catalog organization and discovery
Learn when catalog work belongs to brands, series, categories, collections, tags, templates, Search, or API reference.
Start here when the product record is not the only thing changing. The surrounding catalog model decides where an item appears, how it is grouped, what labels it carries, and which reusable option model shapes it.
The short model
A product is the shopper-recognizable item. The structure around it is made from several smaller models.
Brands and series identify who makes the product and the brand-owned line it belongs to. Categories place the product in taxonomy and navigation. Collections group products for curated merchandising. Tags apply reusable labels to products, variants, and markets. Attribute templates and fields define reusable structured values such as color, material, size, season, or internal classifications. Variant templates define which template set applies to a product's variants.
Choose the catalog organization surface when the work is about how items are organized, filtered, grouped, labeled, or discovered. Use Products when the product name, description, media, status, or product-level relationships are changing. Use Variants when the exact purchasable version, price, stock, or variant-level tag is changing.
Choose the surface by the job
| Job | Use this surface | Why |
|---|---|---|
| Manage brand records or brand-owned series | Brands | The reference includes Management API operations for brand records and series under a brand, plus Shopper API brand reads. |
| Read series directly in storefront context | Series | The reference includes Shopper API reads for listing series, reading a series by ID, and reading a series by slug. |
| Build or maintain navigation taxonomy | Categories | Category operations own category records, category trees, category-product membership, and bulk category or membership changes. |
| Curate merchandising groups | Collections | Collection operations own collection records, collection hierarchy, product membership, and bulk collection or membership changes. |
| Apply reusable catalog labels | Tags | Tag operations own tag records, market availability, product-by-tag listing, and bulk product or variant tag relationships. |
| Define the reusable attribute model | Attribute Templates and Attribute Template Fields | Template operations define the reusable field model; field operations change one field inside an existing template. |
| Attach or manage actual structured values | Attributes | Attribute operations own attribute values, value relationships, attachments, linked attributes, and bulk attribute work. |
| Read, set, or delete product variant template sets | Variant Templates | Variant template operations are product-scoped and control which template set applies to a product's variants. |
| Search, filter, autocomplete, or rank storefront results | Search latest | Search is the better starting point for discovery-heavy storefront experiences. |
Contract facts to keep in mind
Use these facts to choose the right reference. Use operation pages for exact fields, auth, validation, status codes, and response shapes.
- Brand and series records share the same catalog identity model. A brand is the top-level maker or label; a series belongs under one brand.
- Deleting a series moves products back to the parent brand before removing the series.
- Updating a category slug or parent can create redirects for the old path and for affected child paths when automatic redirect handling is enabled.
- Moving or renaming a collection can update child URI paths and create redirects for changed paths.
- Creating a tag automatically associates it with every market in the app.
- Bulk category, collection, and tag create/update operations accept up to 50 records and return separate successful and failed collections. Delete batches accept 1 to 100 IDs.
- Relationship bulk operations for category-product, collection-product, product-tag, variant-tag, and variant-group-tag changes accept up to 50 relationship groups.
- Shopper REST reads for brands, series, categories, collections, and tags are compatibility reads. Use Search for discovery experiences where ranking, filtering, facets, autocomplete, or product-result composition matters.
Events
Use Events after catalog organization changes. The Event catalog covers brand, category, collection, and tag event families. It does not expose dedicated series, attribute-template, attribute-template-field, or variant-template event families.
Use the Event catalog for exact event type strings, schema IDs, required fields, and payload fields. Use Events latest for delivery and retry behavior.
Where to go next
- Need the product/variant mental model? Read Products, variants, variant groups, prices, and stock.
- Need the reusable value model? Read Attributes.
- Need group-level presentation between product and variant? Read Variant groups.
- Need exact REST contracts? Use Reference.