--- title: collectionByHandle - GraphQL Admin description: |- 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection). api_version: 2025-10 api_name: admin type: query api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/queries/collectionbyhandle md: https://shopify.dev/docs/api/admin-graphql/latest/queries/collectionbyhandle.md --- # collection​By​Handle query Requires `read_products` access scope. Deprecated. Use [collectionByIdentifier](https://shopify.dev/docs/api/admin-graphql/latest/queries/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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection). ## Arguments * handle [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) required The handle of the collection. *** ## Possible returns * Collection [Collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection) The `Collection` object represents a group of [products](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) 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](https://shopify.dev/docs/apps/build/online-store), [sales channels](https://shopify.dev/docs/apps/build/sales-channels), and marketing campaigns. There are two types of collections: * **[Custom (manual) collections](https://help.shopify.com/manual/products/collections/manual-shopify-collection)**: You specify the products to include in a collection. * **[Smart (automated) collections](https://help.shopify.com/manual/products/collections/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish) mutation after creation. *** Collections can be displayed in a store with Shopify's theme system through [Liquid templates](https://shopify.dev/docs/storefronts/themes/architecture/templates/collection) and can be customized with [template suffixes](https://shopify.dev/docs/storefronts/themes/architecture/templates/alternate-templates) 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](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities). *** ## 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 ```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 } } } } } } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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 } } } } } } }" }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` #### Ruby ```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 ```javascript 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 ```json { "collectionByHandle": null } ``` * ### Retrieve a collection with five of its best-selling products by its handle #### Query ```graphql query { collectionByHandle(handle: "everything") { id title products(first: 5, sortKey: BEST_SELLING) { edges { node { id title priceRangeV2 { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } } } } } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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 } } } } } } }" }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` #### Ruby ```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 ```javascript 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 ```json { "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 ```graphql query getCollectionIdFromHandle($handle: String!) { collectionByHandle(handle: $handle) { id } } ``` #### Variables ```json { "handle": "ipods" } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-10/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" } }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql query getCollectionIdFromHandle($handle: String!) { collectionByHandle(handle: $handle) { id } }`, { variables: { "handle": "ipods" }, }, ); const json = await response.json(); return json.data; } ``` #### Ruby ```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 ```javascript 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 ```json { "collectionByHandle": { "id": "gid://shopify/Collection/841564295" } } ``` [Open in GraphiQL](http://localhost:3457/graphiql?query=query%20%7B%0A%20%20collectionByHandle\(handle%3A%20%22there%20is%20no%20collection%20with%20a%20handle%20like%20this%22\)%20%7B%0A%20%20%20%20id%0A%20%20%20%20title%0A%20%20%20%20products\(first%3A%205%2C%20reverse%3A%20true\)%20%7B%0A%20%20%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%20%20%20%20title%0A%20%20%20%20%20%20%20%20%20%20createdAt%0A%20%20%20%20%20%20%20%20%20%20priceRangeV2%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20minVariantPrice%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20amount%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20currencyCode%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%20%20maxVariantPrice%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20amount%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20currencyCode%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D) ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` ##### GQL ``` 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-10/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 } } } } } } }" }' ``` ##### React Router ``` import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { 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 json = await response.json(); return json.data; } ``` ##### 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 } } } } } } }`, }); ``` ##### 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) ``` ## Response JSON ```json { "collectionByHandle": null } ```