Choose a version:

collectionByHandle

queryDeprecated

Requires read_products access scope.

Return a collection by its handle. Use collectionByIdentifier instead.

Arguments

Anchor to handlehandle • String!required: The handle of the collection.

Was this section helpful?

Anchor to Possible returnsPossible returns

Collection

•

Collection

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.

availablePublicationsCount• Count: The number of publications that a resource is published to, without feedback errors.
description• 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.
descriptionHtml• 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.
feedback• ResourceFeedback: Information about the collection that's provided through resource feedback.
handle• 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.
hasProduct• Boolean! non-null: Whether the collection includes the specified product.
id• ID! non-null: A globally-unique ID.
image• Image: The image associated with the collection.
legacyResourceId• UnsignedInt64! non-null: The ID of the corresponding resource in the REST Admin API.
metafield• 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.
metafields • MetafieldConnection! non-null: A list of custom fields that a merchant associates with a Shopify resource.
products • ProductConnection! non-null: The products that are included in the collection.
productsCount• Count: The number of products in the collection.
publishedOnCurrentPublication• 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.
publishedOnPublication• Boolean! non-null: Whether the resource is published to a specified publication.
resourcePublications • ResourcePublicationConnection! non-null: The list of resources that are published to a publication.
resourcePublicationsCount• Count: The number of publications that a resource is published to, without feedback errors.
resourcePublicationsV2 • ResourcePublicationV2Connection! non-null: The list of resources that are either published or staged to be published to a publication.
ruleSet• CollectionRuleSet: For a smart (automated) collection, specifies the rules that determine whether a product is included.
seo• SEO! non-null: If the default SEO fields for page title and description have been modified, contains the modified information.
sortOrder• 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.
templateSuffix• 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.
title• 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.
translations• [Translation!]! non-null: The published translations associated with the resource.
unpublishedPublications • PublicationConnection! non-null: The list of publications that the resource isn't published to.
updatedAt• DateTime! non-null: The date and time (ISO 8601 format) when the collection was last modified.
metafieldDefinitions • MetafieldDefinitionConnection! non-nullDeprecated: List of metafield definitions. This field will be removed in a future version. Use the root metafieldDefinitions field instead.
privateMetafield• PrivateMetafield Deprecated: Returns a private metafield by namespace and key that belongs to the resource. Metafields created using a reserved namespace are private by default. See our guide for migrating private metafields.
privateMetafields • PrivateMetafieldConnection! non-nullDeprecated: List of private metafields that belong to the resource. Metafields created using a reserved namespace are private by default. See our guide for migrating private metafields.
publicationCount• Int! non-nullDeprecated: The number of publications that a resource is published to, without feedback errors. Use resourcePublicationsCount instead.
publications • CollectionPublicationConnection! non-nullDeprecated: The channels where the collection is published. Use resourcePublications instead.
publishedOnChannel• Boolean! non-nullDeprecated: Whether the resource is published to a specific channel. Use publishedOnPublication instead.
publishedOnCurrentChannel• Boolean! non-nullDeprecated: Whether the resource is published to a channel. For example, the resource might be published to the online store channel. Use publishedOnCurrentPublication instead.
storefrontId• StorefrontID! non-nullDeprecated: The Storefront GraphQL API ID of the Collection.

As of the 2022-04 version release, the Storefront GraphQL API will no longer return Base64 encoded IDs to match the behavior of the Admin GraphQL API. Therefore, you can safely use the id field's value instead. Use id instead.
unpublishedChannels • ChannelConnection! non-nullDeprecated: The list of channels that the resource is not published to. Use unpublishedPublications instead.

Was this section helpful?

Retrieve a collection by a handle that doesn't exist
Retrieve a collection with five of its best-selling products by its handle
Retrieve the ID of a collection with a specified handle

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query {

collectionByHandle(handle: "there is no collection with a handle like this") {

title

products(first: 5, reverse: true) {

edges {

node {

title

createdAt

priceRangeV2 {

minVariantPrice {

amount

currencyCode

}

maxVariantPrice {

amount

currencyCode

}

}`,

);

const data = await response.json();

query {
  collectionByHandle(handle: "there is no collection with a handle like this") {
    id
    title
    products(first: 5, reverse: true) {
      edges {
        node {
          id
          title
          createdAt
          priceRangeV2 {
            minVariantPrice {
              amount
              currencyCode
            }
            maxVariantPrice {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { collectionByHandle(handle: \"there is no collection with a handle like this\") { id title products(first: 5, reverse: true) { edges { node { id title createdAt priceRangeV2 { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } } } } } }"
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  query {
    collectionByHandle(handle: "there is no collection with a handle like this") {
      id
      title
      products(first: 5, reverse: true) {
        edges {
          node {
            id
            title
            createdAt
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }`,
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    collectionByHandle(handle: "there is no collection with a handle like this") {
      id
      title
      products(first: 5, reverse: true) {
        edges {
          node {
            id
            title
            createdAt
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }`,
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query {
    collectionByHandle(handle: "there is no collection with a handle like this") {
      id
      title
      products(first: 5, reverse: true) {
        edges {
          node {
            id
            title
            createdAt
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"collectionByHandle": null

}