Choose a version:

collectionByHandle

query

Requires read_products access scope.

Deprecated. Use collectionByIdentifier instead.

Retrieves a collection by its unique handle identifier. Handles provide a URL-friendly way to reference collections and are commonly used in storefront URLs and navigation.

For example, a collection with the title "Summer Sale" might have the handle summer-sale, allowing you to fetch it directly without knowing the internal ID.

Use CollectionByHandle to:

Fetch collections for storefront display and navigation
Build collection-based URLs and routing systems
Validate collection existence before displaying content

Handles are automatically generated from collection titles but can be customized by merchants for SEO and branding purposes.

Learn more about collections.

Anchor to Arguments

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?

Examples

Retrieve a collection by a handle that doesn't exist

Description

Trying to retrieve a collection by a handle that doesn't exist returns `null`.

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
            }
          }
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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 } } } } } } }"
}'

Remix

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();

Ruby

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)

Node.js

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
              }
            }
          }
        }
      }
    }
  }`,
});

Response

{
  "collectionByHandle": null
}

Retrieve a collection with five of its best-selling products by its handle

Query

query {
  collectionByHandle(handle: "everything") {
    id
    title
    products(first: 5, sortKey: BEST_SELLING) {
      edges {
        node {
          id
          title
          priceRangeV2 {
            minVariantPrice {
              amount
              currencyCode
            }
            maxVariantPrice {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { collectionByHandle(handle: \"everything\") { id title products(first: 5, sortKey: BEST_SELLING) { edges { node { id title priceRangeV2 { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } } } } } }"
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query {
    collectionByHandle(handle: "everything") {
      id
      title
      products(first: 5, sortKey: BEST_SELLING) {
        edges {
          node {
            id
            title
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }`,
);

const data = await response.json();

Ruby

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: "everything") {
      id
      title
      products(first: 5, sortKey: BEST_SELLING) {
        edges {
          node {
            id
            title
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    collectionByHandle(handle: "everything") {
      id
      title
      products(first: 5, sortKey: BEST_SELLING) {
        edges {
          node {
            id
            title
            priceRangeV2 {
              minVariantPrice {
                amount
                currencyCode
              }
              maxVariantPrice {
                amount
                currencyCode
              }
            }
          }
        }
      }
    }
  }`,
});

Response

{
  "collectionByHandle": {
    "id": "gid://shopify/Collection/94229130",
    "title": "All products more expensive than free",
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/108828309",
            "title": "Draft",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "10.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "10.0",
                "currencyCode": "USD"
              }
            }
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/910489600",
            "title": "Crafty Shoes",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "100.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "100.0",
                "currencyCode": "USD"
              }
            }
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/20995642",
            "title": "Element",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "10.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "15.0",
                "currencyCode": "USD"
              }
            }
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/121709582",
            "title": "Boots",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "30.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "30.0",
                "currencyCode": "USD"
              }
            }
          }
        },
        {
          "node": {
            "id": "gid://shopify/Product/912855135",
            "title": "SEO Boots",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "35.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "35.0",
                "currencyCode": "USD"
              }
            }
          }
        }
      ]
    }
  }
}

Retrieve the ID of a collection with a specified handle

Query

query getCollectionIdFromHandle($handle: String!) {
  collectionByHandle(handle: $handle) {
    id
  }
}

Variables

{
  "handle": "ipods"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query getCollectionIdFromHandle($handle: String!) { collectionByHandle(handle: $handle) { id } }",
 "variables": {
    "handle": "ipods"
  }
}'

Remix

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

const response = await admin.graphql(
  `#graphql
  query getCollectionIdFromHandle($handle: String!) {
    collectionByHandle(handle: $handle) {
      id
    }
  }`,
  {
    variables: {
        "handle": "ipods"
    },
  },
);

const data = await response.json();

Ruby

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 getCollectionIdFromHandle($handle: String!) {
    collectionByHandle(handle: $handle) {
      id
    }
  }
QUERY

variables = {
  "handle": "ipods"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query getCollectionIdFromHandle($handle: String!) {
      collectionByHandle(handle: $handle) {
        id
      }
    }`,
    "variables": {
        "handle": "ipods"
    },
  },
});

Response

{
  "collectionByHandle": {
    "id": "gid://shopify/Collection/841564295"
  }
}

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/2025-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

}