Skip to main content
Anchor to Collection

Collection

object

Requires read_products access scope.

Represents a group of products that can be displayed in online stores and other sales channels in categories, which makes it easy for customers to find them. For example, an athletics store might create different collections for running attire, shoes, and accessories.

Collections can be defined by conditions, such as whether they match certain product tags. These are called smart or automated collections.

Collections can also be created for a custom group of products. These are called custom or manual collections.

Anchor to Fields and connectionsFields and connections

Anchor to availablePublicationsCountavailablePublicationsCount
•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 descriptionHtmldescriptionHtml
•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 feedbackfeedback
•ResourceFeedback

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 handle summer-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 hasProducthasProduct
•Boolean!
non-null

Whether the collection includes the specified product.

Anchor to idid
•ID!
non-null

A globally-unique ID.

Anchor to imageimage
•Image

The image associated with the collection.

Anchor to legacyResourceIdlegacyResourceId
•UnsignedInt64!
non-null

The ID of the corresponding resource in the REST Admin API.

Anchor to metafieldmetafield
•Metafield

A custom field, including its namespace and key, that's associated with a Shopify resource for the purposes of adding and storing additional information.

Anchor to metafieldsmetafields
•MetafieldConnection!
non-null

A list of custom fields that a merchant associates with a Shopify resource.

Anchor to productsproducts
•ProductConnection!
non-null

The products that are included in the collection.

Anchor to productsCountproductsCount
•Count

The number of products in the collection.

Anchor to publishedOnCurrentPublicationpublishedOnCurrentPublication
•Boolean!
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 publishedOnPublicationpublishedOnPublication
•Boolean!
non-null

Whether the resource is published to a specified publication.

Anchor to resourcePublicationsresourcePublications
•ResourcePublicationConnection!
non-null

The list of resources that are published to a publication.

Anchor to resourcePublicationsCountresourcePublicationsCount
•Count

The number of publications that a resource is published to, without feedback errors.

Anchor to resourcePublicationsV2resourcePublicationsV2
•ResourcePublicationV2Connection!
non-null

The list of resources that are either published or staged to be published to a publication.

Anchor to ruleSetruleSet
•CollectionRuleSet

For a smart (automated) collection, specifies the rules that determine whether a product is included.

Anchor to seoseo
•SEO!
non-null

If the default SEO fields for page title and description have been modified, contains the modified information.

Anchor to sortOrdersortOrder
•CollectionSortOrder!
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 templateSuffixtemplateSuffix
•String

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 the collection.custom.liquid template. If the value is null, then the collection is using the default collection.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 unpublishedPublicationsunpublishedPublications
•PublicationConnection!
non-null

The list of publications that the resource isn't published to.

Anchor to updatedAtupdatedAt
•DateTime!
non-null

The date and time (ISO 8601 format) when the collection was last modified.

Deprecated fields and connections

Anchor to metafieldDefinitionsmetafieldDefinitions
•MetafieldDefinitionConnection!
non-nullDeprecated
Anchor to publicationCountpublicationCount
•Int!
non-nullDeprecated
Anchor to publicationspublications
•CollectionPublicationConnection!
non-nullDeprecated
Anchor to publishedOnChannelpublishedOnChannel
•Boolean!
non-nullDeprecated
Anchor to publishedOnCurrentChannelpublishedOnCurrentChannel
•Boolean!
non-nullDeprecated
Anchor to storefrontIdstorefrontId
•StorefrontID!
non-nullDeprecated
Anchor to unpublishedChannelsunpublishedChannels
•ChannelConnection!
non-nullDeprecated
Was this section helpful?

Anchor to QueriesQueries

Anchor to collectioncollection
•query

Returns a Collection resource by ID.

Anchor to collectionByIdentifiercollectionByIdentifier
•query

Return a collection by an identifier.

Anchor to collectionscollections
•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.

Anchor to collectionByHandlecollectionByHandle
•query
Deprecated
Was this section helpful?

Anchor to MutationsMutations

Anchor to collectionAddProductscollectionAddProducts
•mutation

Adds products to a collection.

Arguments

Anchor to idid
•ID!
required

The ID of the collection that's being updated. This can't be a smart collection.

Anchor to productIdsproductIds
•[ID!]!
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.

Fields

Anchor to collectioncollection
•Collection

The updated collection. Returns null if an error is raised.

Anchor to userErrorsuserErrors
•[UserError!]!
non-null

The list of errors that occurred from executing the mutation.

Anchor to collectionCreatecollectionCreate
•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:

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 rules (for example, by tag, type, or price)
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 smart collections.

Arguments

Anchor to inputinput
•CollectionInput!
required

The properties to use when creating the collection.

Fields

Anchor to collectioncollection
•Collection

The collection that has been created.

Anchor to userErrorsuserErrors
•[UserError!]!
non-null

The list of errors that occurred from executing the mutation.

Anchor to collectionUpdatecollectionUpdate
•mutation

Updates a collection.

Arguments

Anchor to inputinput
•CollectionInput!
required

The updated properties for the collection.

Fields

Anchor to collectioncollection
•Collection

The updated collection.

Anchor to jobjob
•Job

The asynchronous job updating the products based on the new rule set.

Anchor to userErrorsuserErrors
•[UserError!]!
non-null

The list of errors that occurred from executing the mutation.

Deprecated mutations

Anchor to collectionPublishcollectionPublish
•mutation
Deprecated

Arguments

Anchor to inputinput
•CollectionPublishInput!
required

Specify a collection to publish and the sales channels to publish it to.

Fields

Anchor to collectioncollection
•Collection

The published collection.

Anchor to collectionPublicationscollectionPublications
•[CollectionPublication!]

The channels where the collection has been published.

Anchor to shopshop
•Shop!
non-null

The shop associated with the collection.

Anchor to userErrorsuserErrors
•[UserError!]!
non-null

The list of errors that occurred from executing the mutation.

Anchor to collectionUnpublishcollectionUnpublish
•mutation
Deprecated

Arguments

Anchor to inputinput
•CollectionUnpublishInput!
required

Specify a collection to unpublish and the sales channels to remove it from.

Fields

Anchor to collectioncollection
•Collection

The collection that has been unpublished.

Anchor to shopshop
•Shop!
non-null

The shop associated with the collection.

Anchor to userErrorsuserErrors
•[UserError!]!
non-null

The list of errors that occurred from executing the mutation.

Was this section helpful?

Anchor to InterfacesInterfaces

Was this section helpful?