Change: Collections API Moves to Inclusion and Exclusion Conditions

The collectionRulesConditions field’s description has been updated to reflect that it lists all usable rules for creating collections, but the field remains deprecated in favor of the new CollectionSourceInclusionCondition* and CollectionSourceExclusionCondition* types. The collections query description now removes the mention of managing both custom and smart collections and refers to “collection rules or conditions” instead of “smart collections”, and the old publishable_status argument has been replaced by published_status. The collectionCreate mutation’s documentation was rewritten to emphasize that the legacy ruleSet input is deprecated and that product membership should now be defined through sources with inclusion and manual selections. The collectionAddProducts, collectionAddProductsV2, and collectionRemoveProducts mutations are all marked deprecated and now recommend using collectionUpdate with inclusion.selectionsToAdd or inclusions.selectionsToRemove to bulk‑manage products. The collectionUpdate mutation description was expanded to clarify that it can modify properties, products, or publication settings, that product membership changes can be performed through rules, sources, or conditions, and that these updates may run asynchronously and return a Job. These changes unify product assignment and removal under collectionUpdate, deprecating the older add/remove operations. Overall, the API is shifting toward a single, more consistent approach for creating and updating collections using inclusion/exclusion conditions instead of legacy rule sets.

Query Changes

🔄 Modified Queries (2)

collectionRulesConditions

Lists all rules that can be used to create collections.

collections

Retrieves a list of collections
in a store. Collections are groups of products
that merchants can organize for display in their online store and
other sales channels.
For example, an athletics store might create different collections for running attire, shoes, and accessories.

Use the collections query when you need to:

Build a browsing interface for a store's product groupings.
Create collection searching, sorting, and filtering experiences (for example, by title, type, or published status).
Sync collection data with external systems.

The collections query supports pagination
for large catalogs and saved searches
for frequently used collection queries.

The collections query returns collections with their associated metadata, including:

Basic collection information (title, description, handle, and type)
Collection image and SEO metadata
Product count and product relationships
Collection rules or conditions
Publishing status and publication details
Metafields and custom attributes

Learn more about using metafields with collection conditions.

Mutation Changes

🔄 Modified Mutations (5)

collectionAddProducts

Adds multiple products to an existing collection in a single operation. This mutation provides an efficient way to bulk-manage collection membership without individual product updates.

For example, when merchants create seasonal collections, they can add dozens of related products at once rather than updating each product individually. A clothing store might add all winter jackets to a "Winter Collection" in one operation.

Use CollectionAddProducts to:

Bulk-add products to collections for efficient catalog management
Implement collection building tools in admin interfaces
Organize collection membership during bulk product operations
Reduce API calls when managing large product sets

The mutation processes multiple product additions and returns success status along with any errors encountered during the operation. Products are added to the collection while preserving existing collection settings.

Learn more about collection management.

⚠️ Deprecated: Use `collectionUpdate` with inclusion.selectionsToAdd instead.

~ Modified argument: id

collectionAddProductsV2

Adds products to a Collection asynchronously and returns a Job to track the operation's progress. This mutation handles large product sets efficiently by processing them in the background.

You can poll the returned job using the job query to monitor completion status.

Note:
This mutation adds products in the order specified in the productIds argument.

⚠️ Deprecated: Use `collectionUpdate` with inclusion.selectionsToAdd instead.

collectionCreate

Creates a collection
to group products together
in the online store and
other sales channels.
For example, an athletics store might create different collections for running attire, shoes, and accessories.

Use the collectionCreate mutation when you need to:

Create a new collection for a product launch or campaign
Organize products by category, season, or promotion
Automate product grouping using conditions (for example, by tag, type, or price)

Collections can include products manually and can also include products automatically based on rules, sources,
or conditions.

Defining a collection's membership

Define membership with sources on the collection argument
(CollectionCreateInput).
Each source adds products through conditions (such as product tag, title, or metafield—see
CollectionSourceInclusionConditionInput
for the full list) and through manual selections.

Note:
The input argument and its ruleSet field are deprecated. Existing integrations should migrate to
collection and sources — a ruleSet rule maps to an equivalent source condition (for example, a
tag rule becomes a productTag condition). If both collection and input are provided, collection
is used.

Note:
The created collection is unpublished by default. To make it available to customers,
use the publishablePublish
mutation after creation.

Learn more about using metafields with collection conditions.

~ Modified argument: collection

collectionRemoveProducts

Removes multiple manually included products from a collection in a single operation. This mutation can process large product sets (up to 250 products) and may take significant time to complete for collections with many products.

For example, when ending a seasonal promotion, merchants can remove all sale items from a "Summer Clearance" collection at once rather than editing each product individually.

Use CollectionRemoveProducts to:

Bulk-remove products from collections efficiently
Clean up collection membership during catalog updates
Implement automated collection management workflows

The operation processes asynchronously to avoid timeouts and performance issues, especially for large product sets.

Learn more about collection management.

⚠️ Deprecated: Use `collectionUpdate` with inclusions.selectionsToRemove instead.

~ Modified argument: id

collectionUpdate

Updates a collection,
modifying its properties, products, or publication settings. Collections help organize
products together
in the online store and
other sales channels.

Use the collectionUpdate mutation to programmatically modify collections in scenarios such as:

Updating collection details, like title, description, or image
Modifying SEO metadata for better search visibility
Changing which products are included in a collection by updating its rules, sources, or conditions
Updating custom data using metafields

Collections can include products manually and can also include products automatically based on rules, sources,
or conditions. When product membership is updated through rules, sources, or conditions, the operation might
be processed asynchronously. In these cases, the mutation returns a job object
that you can use to track the progress of the update.

To publish or unpublish collections to specific sales channels, use the dedicated
publishablePublish and
publishableUnpublish mutations.

Learn more about using metafields with collection conditions.

Type Changes

➕ Added Types (74)

🏗️CollectionExclusionProductSelection➕ AddedOBJECT

Represents a product that has been manually selected for exclusion from a collection.

Fields: product, variantIds

🏗️CollectionExclusionProductSelectionConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple CollectionExclusionProductSelections.

Fields: edges, nodes, pageInfo

🏗️CollectionExclusionProductSelectionEdge➕ AddedOBJECT

An auto-generated type which holds one CollectionExclusionProductSelection and a cursor during pagination.

Fields: cursor, node

🏗️CollectionSourceExclusion➕ AddedOBJECT

Defines the rules and selections for excluding products from a collection.

Fields: conditions, matchType, selections

🔌CollectionSourceExclusionCondition➕ AddedINTERFACE

A condition that determines which products should be excluded from a collection.

Fields: id

🏗️CollectionSourceExclusionConditionCollection➕ AddedOBJECT

A condition based on collections for excluding products from a collection.

Fields: id, matchType, values

🏗️CollectionSourceExclusionConditionProductCategory➕ AddedOBJECT

A condition based on product category IDs for excluding products from a collection.