Skip to main content
Anchor to Collection

Collection

object

Requires read_products 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:

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.
Note

Collections are unpublished by default. To make them available to customers, use the publishablePublish mutation after creation.

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 FieldsFields

Anchor to activeOperationsactiveOperations
•CollectionOperations!
non-null

Collection duplicate operations involving this collection, either as a source (copying products from this collection to another) or a target (copying products to this collection from another).

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.

Arguments

Anchor to truncateAttruncateAt
•Int

Truncates a string after the given length.

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 eventsevents
•EventConnection!
non-null

The paginated list of events associated with the host subject.

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey
•EventSortKeys
Default:ID

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to queryquery
•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to action
•string

The action that occured.

Example:

  • action:create
Anchor to comments
•boolean

Whether or not to include comment-events in your search, passing false will exclude comment-events, any other value will include comment-events.

Example:

  • false
  • true
Anchor to created_at
•time

Filter by the date and time when the event happened.

Example:

  • created_at:>2020-10-21
  • created_at:<now
Anchor to id
•id

Filter by id range.

Example:

  • id:1234
  • id:>=1234
  • id:<=1234
Anchor to subject_type
•string

The resource type affected by this event. See EventSubjectType for possible values.

Example:

  • PRODUCT_VARIANT
  • PRODUCT
  • COLLECTION
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.

Arguments

Anchor to idid
•ID!
required

The ID of the product to check.

Anchor to idid
•ID!
non-null

A globally-unique ID.

Anchor to imageimage
•Image

The image associated with the collection.

Arguments

Anchor to maxWidthmaxWidth
•Int
Deprecated
Anchor to maxHeightmaxHeight
•Int
Deprecated
Anchor to cropcrop
•CropRegion
Deprecated
Anchor to scalescale
•Int
DeprecatedDefault:1
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.

Arguments

Anchor to namespacenamespace
•String

The container the metafield belongs to. If omitted, the app-reserved namespace will be used.

Anchor to keykey
•String!
required

The key for the metafield.

Anchor to metafieldsmetafields
•MetafieldConnection!
non-null

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

Arguments

Anchor to namespacenamespace
•String

The metafield namespace to filter by. If omitted, all metafields are returned.

Anchor to keyskeys
•[String!]

List of keys of metafields in the format namespace.key, will be returned in the same format.

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to productsproducts
•ProductConnection!
non-null

The products that are included in the collection.

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey
•ProductCollectionSortKeys
Default:COLLECTION_DEFAULT

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

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.

Arguments

Anchor to publicationIdpublicationId
•ID!
required

The ID of the publication to check. For example, id: "gid://shopify/Publication/123".

Anchor to resourcePublicationsresourcePublications
•ResourcePublicationConnection!
non-null

The list of resources that are published to a publication.

Arguments

Anchor to onlyPublishedonlyPublished
•Boolean
Default:true

Whether to return only the resources that are currently published. If false, then also returns the resources that are scheduled to be published.

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to resourcePublicationsCountresourcePublicationsCount
•Count

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

Arguments

Anchor to onlyPublishedonlyPublished
•Boolean
Default:true

Include only the resource's publications that are published. If false, then return all the resource's publications including future publications.

Anchor to resourcePublicationsV2resourcePublicationsV2
•ResourcePublicationV2Connection!
non-null

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

Arguments

Anchor to onlyPublishedonlyPublished
•Boolean
Default:true

Whether to return only the resources that are currently published. If false, then also returns the resources that are scheduled or staged to be published.

Anchor to catalogTypecatalogType
•CatalogType

Filter publications by catalog type.

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

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.

Arguments

Anchor to localelocale
•String!
required

Filters translations locale.

Anchor to marketIdmarketId
•ID

Filters translations by market ID. Use this argument to retrieve content specific to a market.

Anchor to unpublishedPublicationsunpublishedPublications
•PublicationConnection!
non-null

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

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to updatedAtupdatedAt
•DateTime!
non-null

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

Deprecated fields

Anchor to metafieldDefinitionsmetafieldDefinitions
•MetafieldDefinitionConnection!
non-nullDeprecated

Arguments

Anchor to namespacenamespace
•String

Filter metafield definitions by namespace.

Anchor to pinnedStatuspinnedStatus
•MetafieldDefinitionPinnedStatus
Default:ANY

Filter by the definition's pinned status.

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey
•MetafieldDefinitionSortKeys
Default:ID

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to queryquery
•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to default
•string

Filter by a case-insensitive search of multiple fields in a document.

Example:

  • query=Bob Norman
  • query=title:green hoodie
Anchor to created_at
•time

Filter by the date and time when the metafield definition was created.

Example:

  • created_at:>2020-10-21T23:39:20Z
  • created_at:<now
  • created_at:<=2024
Anchor to id
•id

Filter by id range.

Example:

  • id:1234
  • id:>=1234
  • id:<=1234
Anchor to key
•string

Filter by the metafield definition key field.

Example:

  • key:some-key
Anchor to namespace
•string

Filter by the metafield definition namespace field.

Example:

  • namespace:some-namespace
Anchor to owner_type
•string

Filter by the metafield definition ownerType field.

Example:

  • owner_type:PRODUCT
Anchor to type
•string

Filter by the metafield definition type field.

Example:

  • type:single_line_text_field
Anchor to updated_at
•time

Filter by the date and time when the metafield definition was last updated.

Example:

  • updated_at:>2020-10-21T23:39:20Z
  • updated_at:<now
  • updated_at:<=2024
Anchor to publicationCountpublicationCount
•Int!
non-nullDeprecated

Arguments

Anchor to onlyPublishedonlyPublished
•Boolean
Default:true

Include only the resource's publications that are published. If false, then return all the resource's publications including future publications.

Anchor to publicationspublications
•CollectionPublicationConnection!
non-nullDeprecated

Arguments

Anchor to onlyPublishedonlyPublished
•Boolean
Default:true

Whether or not to return only the collection publications that are published.

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to publishedOnChannelpublishedOnChannel
•Boolean!
non-nullDeprecated

Arguments

Anchor to channelIdchannelId
•ID!
required

The ID of the channel to check.

Anchor to publishedOnCurrentChannelpublishedOnCurrentChannel
•Boolean!
non-nullDeprecated
Anchor to storefrontIdstorefrontId
•StorefrontID!
non-nullDeprecated
Anchor to unpublishedChannelsunpublishedChannels
•ChannelConnection!
non-nullDeprecated

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Was this section helpful?

Anchor to QueriesQueries

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

Arguments

Anchor to idid
•ID!
required

The ID of the Collection to return.

Anchor to collectionByIdentifiercollectionByIdentifier
•query

Return a collection by an identifier.

Arguments

Anchor to identifieridentifier
•CollectionIdentifierInput!
required

The identifier of the collection.

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.

Arguments

Anchor to firstfirst
•Int

The first n elements from the paginated list.

Anchor to afterafter
•String

The elements that come after the specified cursor.

Anchor to lastlast
•Int

The last n elements from the paginated list.

Anchor to beforebefore
•String

The elements that come before the specified cursor.

Anchor to reversereverse
•Boolean
Default:false

Reverse the order of the underlying list.

Anchor to sortKeysortKey
•CollectionSortKeys
Default:ID

Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.

Anchor to queryquery
•String

A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.

Anchor to default
•string

Filter by a case-insensitive search of multiple fields in a document.

Example:

  • query=Bob Norman
  • query=title:green hoodie
Anchor to collection_type
•string

Valid values:

  • custom
  • smart
Anchor to handle
•string
Anchor to id
•id

Filter by id range.

Example:

  • id:1234
  • id:>=1234
  • id:<=1234
Anchor to product_id
•id

Filter by collections containing a product by its ID.

Anchor to product_publication_status
•string

Filter by channel approval process status of the resource on a channel, such as the online store. The value is a composite of the channel app ID (Channel.app.id) and one of the valid values. For simple visibility checks, use published_status instead.

Valid values:

  • * {channel_app_id}-approved
  • * {channel_app_id}-rejected
  • * {channel_app_id}-needs_action
  • * {channel_app_id}-awaiting_review
  • * {channel_app_id}-published
  • * {channel_app_id}-demoted
  • * {channel_app_id}-scheduled
  • * {channel_app_id}-provisionally_published

Example:

  • product_publication_status:189769876-approved
Anchor to publishable_status
•string

Deprecated: This parameter is deprecated as of 2025-12 and will be removed in a future API version. Use published_status for visibility checks. Filter by the publishable status of the resource on a channel. The value is a composite of the channel app ID (Channel.app.id) and one of the valid status values.

Valid values:

  • * {channel_app_id}-unset
  • * {channel_app_id}-pending
  • * {channel_app_id}-approved
  • * {channel_app_id}-not_approved

Example:

  • publishable_status:580111-unset
  • publishable_status:580111-pending
Anchor to published_at
•time

Filter by the date and time when the collection was published to the Online Store.

Anchor to published_status
•string

Filter resources by their visibility and publication state on a channel. Online store channel filtering: - online_store_channel: Returns all resources in the online store channel, regardless of publication status. - published/visible: Returns resources that are published to the online store. - unpublished: Returns resources that are not published to the online store. Channel-specific filtering using the channel app ID (Channel.app.id) with suffixes: - {channel_app_id}-published: Returns resources published to the specified channel. - {channel_app_id}-visible: Same as {channel_app_id}-published (kept for backwards compatibility). - {channel_app_id}-intended: Returns resources added to the channel but not yet published. - {channel_app_id}-hidden: Returns resources not added to the channel or not published. Other: - unavailable: Returns resources not published to any channel.

Valid values:

  • online_store_channel
  • published
  • visible
  • unpublished
  • * {channel_app_id}-published
  • * {channel_app_id}-visible
  • * {channel_app_id}-intended
  • * {channel_app_id}-hidden
  • unavailable

Example:

  • published_status:online_store_channel
  • published_status:published
  • published_status:580111-published
  • published_status:580111-hidden
  • published_status:unavailable
Anchor to title
•string
Anchor to updated_at
•time
Anchor to savedSearchIdsavedSearchId
•ID

The ID of a saved search. The search’s query string is used as the query argument.

Anchor to collectionByHandlecollectionByHandle
•query
Deprecated

Arguments

Anchor to handlehandle
•String!
required

The handle of the collection.

Was this section helpful?

Anchor to MutationsMutations

Anchor to collectionAddProductscollectionAddProducts
•mutation

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.

This operation only works with manual collections where merchants explicitly choose which products to include. It will return an error if used with smart collections that automatically include products based on conditions.

Learn more about collection management.

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.

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.

Anchor to collectionDuplicatecollectionDuplicate
•mutation

Duplicates a collection.

An existing collection ID and new title are required.

Publication Duplication

Publications may be excluded by passing copyPublications: false in the input.

Metafields

Metafield values are not duplicated if the unique values capability is enabled.

Arguments

Anchor to inputinput
•CollectionDuplicateInput!
required

The input for duplicating a collection.

Anchor to collectionUpdatecollectionUpdate
•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 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 (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 publishablePublish and publishableUnpublish mutations.

Learn more about using metafields with smart collections.

Arguments

Anchor to inputinput
•CollectionInput!
required

The updated properties for the collection.

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.

Anchor to collectionUnpublishcollectionUnpublish
•mutation
Deprecated

Arguments

Anchor to inputinput
•CollectionUnpublishInput!
required

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

Was this section helpful?

Anchor to InterfacesInterfaces

Was this section helpful?