Skip to main content
Collections table in the admin

Catalog > Collections

​
Definition

The Analogy: A Collection is a playlist. It groups Listings into a themed unit so customers can browse, filter, and land on a category page on the Online Store.
Special in TWICE: Collections are either Manual (you pick the Listings) or Smart (Listings are matched automatically by catalog-scope Tags). Both types live in the same model and expose the same storefront surface.

​
Where do I use it?

  • Online Store navigation — Each Collection renders a category page at /collections/{slug}
  • Storefront merchandising — Promote a seasonal or themed set on the home page
  • Filtered browsing — Customers shop a curated slice of the Catalog instead of the full inventory
  • Tag-driven automation — A Smart Collection stays in sync as Listings get re-tagged
  • SEO entry points — Each Collection has its own page title, meta description and OpenGraph metadata
  • Bulk operations — Use a Collection as the selection set for Price-Table linking or bulk edits

​
Manual vs. Smart

The type field is the discriminator between the two membership models. A Collection’s type cannot be flipped after creation — pick the right type up front. Smart Collections match against catalog-scope Tags only (the only scope shown in the admin’s smart-rule picker).

​
Smart Collection conditions

A Smart Collection holds an array of smartConditions. Each condition is a reference to one Tag. A CollectionSmartCondition has the following fields: There is no operator field on a condition — the predicate is always “Listing has this tag”. Operators like not equals, contains or attribute comparisons are not part of the model today. The combinator between conditions is set on the Collection itself via tagMatchType: tagMatchType is editable any time; membership recomputes on the next read.
Because Smart Collections match on tags only, plan your tag taxonomy before scaling Collections. A bikes tag, a road-bikes tag and a discounted tag let you build “All bikes”, “Road bikes” and “Discounted road bikes” (with tagMatchType = 'all') without duplicate management.

​
Key Properties

​
Relationships

A Collection groups Listings. A single Listing can belong to any number of Collections — there is no cardinality constraint.
Smart Collections reference Tag rows with scope = 'catalog'. Tags are shared across Listings and Collections, so adding a tag to a new Listing instantly affects every Smart Collection that references it.
Collections render on the Online Store at /collections/{urlHandle}. Whether each member Listing appears depends on that Listing’s own sales-channel flags. See the Online Store concept.
Each CollectionMediaLinks row attaches a FileResource (hero image, banner) ordered by orderIndex. The first image is used as a fallback for the social-share preview.

​
Collection detail tabs

When you open a Collection in the admin:

​
Performance considerations

  • Smart Collections recompute on read. The current implementation resolves membership at query time by joining Listing tags to Collection conditions. There is no materialised “membership” table to keep in sync.
  • Cross-Collection membership is free. A Listing can be in any number of Collections without storage overhead, because Manual rows are simple join records and Smart matches are computed.
  • Tag operations cascade. Renaming or deleting a Tag affects every Smart Collection that references it. Renames are safe; deletes will silently shrink Collection membership.
  • Pagination matters for large Collections. Use the listCatalogItems endpoint per Collection to retrieve members in pages rather than reading the entire Collection object.

​
Lifecycle

1

Create

POST /collections with title, type, and (for Smart) an initial tagMatchType.
No. type is fixed at creation. To convert, create a new Collection of the desired type and migrate.
No — you can create the Smart Collection first and add conditions afterwards. Until conditions exist, the Collection has zero members.
2

Populate

For Manual: add Listings with POST /collections/:id/items. For Smart: add tags with POST /collections/:id/conditions and set tagMatchType.
3

Publish on the Online Store

Collections render automatically on the Online Store once they have a urlHandle (or by ID if no handle is set). There is no separate “publish” toggle.
4

Maintain

For Manual: add and remove items as merchandising changes. For Smart: maintain the underlying Tag taxonomy — the Collection follows automatically.
5

Retire

DELETE /collections/:id removes the Collection. Member Listings are not affected — only the Collection rows.

​
Frequently Asked Questions

Yes, any number. There is no cap and no exclusivity rule.
Categories are a structural classification of what a Listing is (a single canonical tree). Collections are a merchandising overlay of how Listings are grouped for sale. A Listing has one taxonomy category but can be in many Collections.
Not today. Conditions are positive tag matches only, combined by any or all.
The corresponding smartConditions row is removed, and Listings previously matched only by that tag fall out of the Collection on the next read.
Manual Collections are ordered by orderIndex on each membership row. Smart Collections derive their order from the listing query, not from the order in which conditions are added.

​
Developer Reference

Collections are exposed as collections in the API.

API: Collections

Open the endpoint in the API reference.

Listings

The Catalog rows a Collection groups

Online Store

Where Collection pages render

Category Taxonomy

Structural classification, complementary to Collections

Price Tables

Apply a shared Price Table to every Listing in a Collection