Collection
Requires access scope.
The Collection
object represents a group of products
that merchants can organize to make their stores easier to browse and help customers find related products.
Collections serve as the primary way to categorize and display products across
online stores,
sales channels, and marketing campaigns.
There are two types of collections:
- Custom (manual) collections: You specify the products to include in a collection.
- Smart (automated) collections: You define rules, and products matching those rules are automatically included in the collection.
The Collection
object provides information to:
- Organize products by category, season, or promotion.
- Automate product grouping using rules (for example, by tag, type, or price).
- Configure product sorting and display order (for example, alphabetical, best-selling, price, or manual).
- Manage collection visibility and publication across sales channels.
- Add rich descriptions, images, and metadata to enhance discovery.
Collections can be displayed in a store with Shopify's theme system through Liquid templates and can be customized with template suffixes for unique layouts. They also support advanced features like translated content, resource feedback, and contextual publication for location-based catalogs.
Learn about using metafields with smart collections.
Anchor to Fields and connectionsFields and connections
- Anchor to availablePublicationsCountavailable•Count
Publications Count The number of publications that a resource is published to, without feedback errors.
- Anchor to descriptiondescription•String!non-null
A single-line, text-only description of the collection, stripped of any HTML tags and formatting that were included in the description.
- Anchor to truncateAttruncate•Int
At Truncates a string after the given length.
Arguments
- Anchor to descriptionHtmldescription•HTML!
Html non-null The description of the collection, including any HTML tags and formatting. This content is typically displayed to customers, such as on an online store, depending on the theme.
- Anchor to eventsevents•Event
Connection! non-null The paginated list of events associated with the host subject.
- Anchor to feedbackfeedback•Resource
Feedback Information about the collection that's provided through resource feedback.
- Anchor to handlehandle•String!non-null
A unique string that identifies the collection. If a handle isn't specified when a collection is created, it's automatically generated from the collection's original title, and typically includes words from the title separated by hyphens. For example, a collection that was created with the title
Summer Catalog 2022
might have the handlesummer-catalog-2022
.If the title is changed, the handle doesn't automatically change.
The handle can be used in themes by the Liquid templating language to refer to the collection, but using the ID is preferred because it never changes.
- Anchor to hasProducthas•Boolean!
Product non-null Whether the collection includes the specified product.
- •ID!required
The ID of the product to check.
Arguments
- •ID!
- •ID!non-null
A globally-unique ID.
- Anchor to imageimage•Image
The image associated with the collection.
- Anchor to legacyResourceIdlegacy•Unsigned
Resource Id Int64! non-null The ID of the corresponding resource in the REST Admin API.
- Anchor to metafieldmetafield•Metafield
A custom field, including its
namespace
andkey
, that's associated with a Shopify resource for the purposes of adding and storing additional information.- Anchor to metafieldsmetafields•Metafield
Connection! non-null A list of custom fields that a merchant associates with a Shopify resource.
- Anchor to productsproducts•Product
Connection! non-null The products that are included in the collection.
- Anchor to productsCountproducts•Count
Count The number of products in the collection.
- Anchor to publishedOnCurrentPublicationpublished•Boolean!
On Current Publication non-null Whether the resource is published to the app's publication. For example, the resource might be published to the app's online store channel.
- Anchor to publishedOnPublicationpublished•Boolean!
On Publication non-null Whether the resource is published to a specified publication.
- Anchor to publicationIdpublication•ID!
Id required The ID of the publication to check. For example,
.
Arguments
- Anchor to resourcePublicationsresource•Resource
Publications Publication Connection! non-null The list of resources that are published to a publication.
- Anchor to resourcePublicationsCountresource•Count
Publications Count The number of publications that a resource is published to, without feedback errors.
- Anchor to resourcePublicationsV2resource•Resource
Publications V2 Publication V2Connection! non-null The list of resources that are either published or staged to be published to a publication.
- Anchor to ruleSetrule•Collection
Set Rule Set For a smart (automated) collection, specifies the rules that determine whether a product is included.
- •SEO!non-null
If the default SEO fields for page title and description have been modified, contains the modified information.
- Anchor to sortOrdersort•Collection
Order Sort Order! non-null The order in which the products in the collection are displayed by default in the Shopify admin and in sales channels, such as an online store.
- Anchor to templateSuffixtemplate•String
Suffix The suffix of the Liquid template being used to show the collection in an online store. For example, if the value is
custom
, then the collection is using thecollection.custom.liquid
template. If the value isnull
, then the collection is using the defaultcollection.liquid
template.- Anchor to titletitle•String!non-null
The name of the collection. It's displayed in the Shopify admin and is typically displayed in sales channels, such as an online store.
- Anchor to translationstranslations•[Translation!]!non-null
The published translations associated with the resource.
- Anchor to unpublishedPublicationsunpublished•Publication
Publications Connection! non-null The list of publications that the resource isn't published to.
- Anchor to updatedAtupdated•Date
At Time! non-null The date and time (ISO 8601 format) when the collection was last modified.
Deprecated fields and connections
- Anchor to metafieldDefinitionsmetafield•Metafield
Definitions Definition Connection! non-nullDeprecated - Anchor to publicationCountpublication•Int!
Count non-nullDeprecated - Anchor to onlyPublishedonly•Boolean
Published Default:true Include only the resource's publications that are published. If false, then return all the resource's publications including future publications.
Arguments
- Anchor to publicationspublications•Collection
Publication Connection! non-nullDeprecated - Anchor to publishedOnChannelpublished•Boolean!
On Channel non-nullDeprecated - Anchor to channelIdchannel•ID!
Id required The ID of the channel to check.
Arguments
- Anchor to publishedOnCurrentChannelpublished•Boolean!
On Current Channel non-nullDeprecated - Anchor to storefrontIdstorefront•Storefront
Id ID! non-nullDeprecated - Anchor to unpublishedChannelsunpublished•Channel
Channels Connection! non-nullDeprecated
Anchor to QueriesQueries
- •query
Retrieves a collection by its ID. A collection represents a grouping of products that merchants can display and sell as a group in their online store and other sales channels.
Use the
collection
query when you need to:- Manage collection publishing across sales channels
- Access collection metadata and SEO information
- Work with collection rules and product relationships
A collection can be either a custom (manual) collection where products are manually added, or a smart (automated) collection where products are automatically included based on defined rules. Each collection has associated metadata including title, description, handle, image, and metafields.
- •query
Return a collection by an identifier.
- •query
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.
- Manage both custom (manual) and smart (automated) collections.
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 (for smart collections)
- Publishing status and publication details
- Metafields and custom attributes
Learn more about using metafields with smart collections.
- •queryDeprecated
Anchor to MutationsMutations
- •mutation
Adds products to a collection.
- •ID!required
The ID of the collection that's being updated. This can't be a smart collection.
- Anchor to productIdsproduct•[ID!]!
Ids required The IDs of the products that are being added to the collection. If any of the products is already present in the input collection, then an error is raised and no products are added.
Arguments
- Anchor to collectioncollection•Collection
The updated collection. Returns
null
if an error is raised.- Anchor to userErrorsuser•[User
Errors Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •ID!
- •mutation
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.
There are two types of collections:
- Custom (manual) collections: You specify the products to include in a collection.
- Smart (automated) collections: You define rules, and products matching those rules are automatically included in the collection.
Use the
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 rules (for example, by tag, type, or price)
NoteLearn more about using metafields with smart collections.
- Anchor to inputinput•Collection
Input! required The properties to use when creating the collection.
Arguments
- Anchor to collectioncollection•Collection
The collection that has been created.
- Anchor to userErrorsuser•[User
Errors Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •mutation
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
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 (using rule updates for smart collections)
- Publishing or unpublishing collections across different sales channels
- Updating custom data using metafields
There are two types of collections with different update capabilities:
- Custom (manual) collections: You can update collection properties, but rule sets can't be modified since products are manually selected.
- Smart (automated) collections: You can update both collection properties and the rules that automatically determine which products are included.
When updating rule sets for smart collections, 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
and
mutations.
Learn more about using metafields with smart collections.
- Anchor to inputinput•Collection
Input! required The updated properties for the collection.
Arguments
- Anchor to collectioncollection•Collection
The updated collection.
- •Job
The asynchronous job updating the products based on the new rule set.
- Anchor to userErrorsuser•[User
Errors Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
Deprecated mutations
- •mutationDeprecated
- Anchor to inputinput•Collection
Publish Input! required Specify a collection to publish and the sales channels to publish it to.
Arguments
- Anchor to collectioncollection•Collection
The published collection.
- Anchor to collectionPublicationscollection•[Collection
Publications Publication!] The channels where the collection has been published.
- Anchor to shopshop•Shop!non-null
The shop associated with the collection.
- Anchor to userErrorsuser•[User
Errors Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
- •mutationDeprecated
- Anchor to inputinput•Collection
Unpublish Input! required Specify a collection to unpublish and the sales channels to remove it from.
Arguments
- Anchor to collectioncollection•Collection
The collection that has been unpublished.
- Anchor to shopshop•Shop!non-null
The shop associated with the collection.
- Anchor to userErrorsuser•[User
Errors Error!]! non-null The list of errors that occurred from executing the mutation.
Fields
Anchor to InterfacesInterfaces
- •interface
- •interface
- •interface
- •interface