Shopify's new Collections API: the shift to composable, source-based collections

For as long as anyone reading this has built on Shopify, a collection has been one of exactly two things. A custom collection, where a merchant hand-picks products one by one, or a smart collection, where products fall in automatically because they match a set of rules. You picked one at creation time, and you lived with the tradeoff. Curation gave you control but no automation. Rules gave you automation but no exceptions. If you wanted a rules-based collection with three products manually pulled out and one manually forced in, you were out of luck, or you were writing an app to babysit the product list by hand.

As of the 2026-07 GraphQL Admin API (stable July 1, 2026), that split is gone. Shopify has rebuilt the collections model around a single idea: a collection is a union of sources. This post walks through what that actually means, the new capabilities it unlocks, and the one caveat theme developers need to know before they get excited.

The old model: a fork in the road

The mental model that shipped with Shopify years ago was a fork. At the moment you created a collection, you chose a lane. A custom collection stored an ordered list of products you added yourself. A smart collection stored a ruleSet: a set of conditions like tag equals summer or price less than 50, joined by all (every rule must match) or any (at least one), and Shopify kept the membership current for you.

It worked, but the seams showed the moment a merchant wanted anything in between. "Everything tagged sale, but pull these two clearance duds out" was impossible on a smart collection: rules had no notion of an exception. "This hand-curated edit, plus anything that goes on sale automatically" was impossible on a custom collection: it had no rules at all. Apps papered over the gap by re-computing product lists and pushing them in with collectionAddProducts on a schedule, which is exactly the kind of shadow-state babysitting the platform should own.

The new model: a collection is a union of sources

In 2026-07 the fork disappears. A collection now has a sources array, and each source contributes members. Shopify unions the sources together, subtracts anything matched by an exclusion, and re-evaluates the whole thing automatically as products and variants change. Curation and automation stop being a choice you make once. They are just different kinds of source you layer into the same collection.

According to Shopify's developer docs, the sources come in a few shapes. A conditions source (documented as CollectionConditionsSource) is the evolution of the old smart-collection rules: conditions plus explicit product or variant selections in one place. A sub-collection source (CollectionSubCollectionsSource) inherits membership from other collections you reference by ID. And a shareable source is an app-owned conditions source that lives independently and can be linked into more than one collection at once.

1Collection "Summer sale, hand-tuned"2  sources:3    - conditions:  tag = "summer"  AND  price < 50      (auto)4    - selections:  [Ceramic Mug, Linen Tote]           (manual, forced in)5  exclusions:6    - selections:  [Faded Cap, Last-season Sandal]      (manual, pulled out)7 8Result = (matches the rules  OR  hand-picked)  MINUS  excluded

What the new model unlocks

The reframe is elegant, but the reason it matters is the capabilities that fall out of it. Five stand out.

• Multi-source collections. Layer rule-based conditions, manual picks, references to other collections, and app sources in a single collection. The "rules plus a few hand-forced exceptions" case that was impossible before is now the default shape.
• Variant-level targeting. Sources can target individual variants, not just whole products. A collection can hold "only the red variants" or "only the in-stock sizes" instead of dragging the entire product in because one variant qualified. Shopify documents this as evaluating conditions per variant when a source is variant-scoped.
• Sub-collections. A collection can reference other collections as a source and stay in sync as they change. This is the native way to build "all sale items" as the union of each category's sale collection, with a documented one-level nesting limit.
• Manual exclusions. Rule-based collections can finally carry explicit exceptions. Match everything tagged clearance, then subtract the three products you never want to show. No app, no scheduled re-sync.
• Shareable app-owned sources. An app can publish a source (say, "trending in the last 24 hours" or "personalized for this segment") that a merchant opts into as one ingredient of a native collection. The app contributes intelligence without taking over the whole product list, and the merchant keeps control of everything else.

Is this a breaking change?

For your existing collections, no. The migration is deliberately non-breaking. Legacy-shaped collections keep working, and the older fields you already call (ruleSet, collectionAddProducts, the classic collectionCreate(input:) argument) are still present in 2026-07, now marked deprecated. Webhooks (collections/create, collections/update, collections/delete) behave as before, and reading collection.products to get the resulting product list is unchanged.

The caveat for theme developers

Here is the part that is easy to miss in the excitement. The new model lives in the Admin API. The storefront side, how a variant-scoped collection actually renders on a collection page, with swatches, filters, and price ranges scoped to just the included variants, is a separate piece that was still rolling out behind a beta flag when the model went stable.

In the developer-preview thread, Shopify's Diana Cheptene (Merchandising team) confirmed storefront support was being enabled gradually and, encouragingly, that it would need no theme changes on the developer's end once live. But "gradually rolling out" and "stable in the Admin API" are two different timelines. If you build a merchandising feature that depends on variant-level collection pages rendering correctly today, verify it on the target store first. We pulled that whole question into its own post: variant-level collections and the storefront.

Why this is worth understanding deeply

It would be easy to file this under "new API, read the changelog when I need it." That undersells it. The custom-versus-smart split was one of the oldest load-bearing assumptions in the whole platform, baked into apps, theme logic, merchant mental models, and a decade of Stack Overflow answers. Replacing it with a composable union of sources is the kind of foundational change that quietly reshapes what is buildable.

The reusable lesson, and the thing an AI assistant will not tell you unless you already know to ask, is that composition beats configuration. A collection built from small, combinable sources is easier to reason about, extend, and share than a monolith that is either fully manual or fully automatic. That principle shows up everywhere in good Shopify architecture, from theme sections and blocks to how you model product data. Collections just caught up to it.

Sources: Shopify Partners, Introducing the new Collections API; Shopify Dev, Use the new collections model and the 2026-07 changelog entry; and the developer-preview community thread.