Skip to main content
A collection is a group of products behind a URL handle (like summer-sale). Membership can be manual (you pick the products, in an order you control) or smart (you write rules and matching products join automatically). Readers can’t tell the two apart — a collection just has products. Collections ride the product scope, since they’re product merchandising.

​
Reading collections

Only published, in-window collections are returned — drafts and scheduled-out collections are invisible to the API.
product_count and the products list are availability-filtered — they reflect what a storefront would actually show (active, in their publish window), not raw membership.

​
A manual collection

Create the collection, then add products to it.
handle is derived from the name when you omit it. Remove products with DELETE on the same path ({ "products": [...] }), and set an explicit order with PUT /v1/collections/{handle}/products/order:
sort_order: MANUAL is what makes your hand-ordered positions show; the other sort orders (TITLE_ASC, CREATED_DESC, STOCK_DESC, …) compute the order for you.

​
A smart collection

Set membership_type: SMART and a rules object. Products that match the rules join automatically — and stay current as products change — so you never manage membership by hand.
  • match is ANY (an OR) or ALL (an AND) across up to 10 conditions.
  • field is one of tag, category, type, inventory, title, price. tag and category take an id as the value; type and title take a string; inventory and price take a number (price in minor units of your default currency).
  • op depends on the field — eq/neq for tag/category/type, the comparisons (gt/gte/lt/lte/eq) for inventory/price, and contains/not_contains/eq for title.
Membership materializes in the background, so a brand-new smart collection may report product_count: 0 for a moment before it catches up.

​
Preview before you commit

POST /v1/collections/preview-rules tells you how many products a rule set would match, without creating anything:

​
Updating & deleting

PUT /v1/collections/{handle} edits a collection; you can even flip membership_type between MANUAL and SMART and the members are reconciled for you. Writes reach drafts too (a collection needn’t be published to be edited). DELETE /v1/collections/{handle} removes the collection — the products in it are not deleted, only the grouping.

​
Good to know

  • Reads are storefront-shaped. The API only ever returns published, in-window collections and, within them, buyable products. If you published a collection but it’s missing from the list, check its publish_at / unpublish_at.
  • Private details stay private. The read shape never exposes a smart collection’s rules or how its membership is decided — to a reader, smart and manual collections are identical.
  • Manual membership is manual only. Adding/removing/reordering products applies to MANUAL collections; a SMART collection’s membership is owned by its rules.
See the Commerce API reference for every field and status code.