Choose a version:

collectionByHandle

query

Requires read_products access scope.

Deprecated. Use collectionByIdentifier instead.

Return a collection by its handle.

Arguments

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

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to CollectionCollection •Collection: 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.

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.

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

}