--- 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: 2026-01 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 \\\publishable\Publish\\\ 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). * active​Operations [Collection​Operations!](https://shopify.dev/docs/api/admin-graphql/latest/objects/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). * available​Publications​Count [Count](https://shopify.dev/docs/api/admin-graphql/latest/objects/Count) The number of [publications](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication) that a resource is published to, without [feedback errors](https://shopify.dev/docs/api/admin-graphql/latest/objects/ResourceFeedback). * description [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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. * truncate​At [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments Truncates a string after the given length. *** * description​Html [HTML!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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. * events [Event​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/EventConnection) non-null The paginated list of events associated with the host subject. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Event​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/latest/enums/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](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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](https://shopify.dev/api/usage/search-syntax). * * action string * comments boolean * created\_at time * id id * subject\_type string - The action that occured. - Example: * `action:create` Whether or not to include [comment-events](https://shopify.dev/api/admin-graphql/latest/objects/CommentEvent) in your search, passing `false` will exclude comment-events, any other value will include comment-events. - Example: * `false` * `true` Filter by the date and time when the event occurred. Event data is retained for 1 year. - Example: * `created_at:>2025-10-21` * `created_at:=1234` * `id:<=1234` The resource type affected by this event. See [EventSubjectType](https://shopify.dev/api/admin-graphql/latest/enums/EventSubjectType) for possible values. Example: * `PRODUCT_VARIANT` * `PRODUCT` * `COLLECTION` *** * feedback [Resource​Feedback](https://shopify.dev/docs/api/admin-graphql/latest/objects/ResourceFeedback) Information about the collection that's provided through resource feedback. * handle [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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. * has​Product [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the collection includes the specified product. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the product to check. *** * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * image [Image](https://shopify.dev/docs/api/admin-graphql/latest/objects/Image) The image associated with the collection. * max​Width [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) Deprecated ### Arguments * max​Height [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) Deprecated * crop [Crop​Region](https://shopify.dev/docs/api/admin-graphql/latest/enums/CropRegion) Deprecated * scale [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) DeprecatedDefault:1 *** * legacy​Resource​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/UnsignedInt64) non-null The ID of the corresponding resource in the REST Admin API. * metafield [Metafield](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metafield) A [custom field](https://shopify.dev/docs/apps/build/custom-data), including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information. * namespace [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) ### Arguments The container the metafield belongs to. If omitted, the app-reserved namespace will be used. * key [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) required The key for the metafield. *** * metafields [Metafield​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldConnection) non-null A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * namespace [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) ### Arguments The metafield namespace to filter by. If omitted, all metafields are returned. * keys [\[String!\]](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) List of keys of metafields in the format `namespace.key`, will be returned in the same format. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * products [Product​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ProductConnection) non-null The products that are included in the collection. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Product​Collection​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/latest/enums/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](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). *** * products​Count [Count](https://shopify.dev/docs/api/admin-graphql/latest/objects/Count) The number of products in the collection. * published​On​Publication [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the resource is published to a specified [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * publication​Id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) required ### Arguments The ID of the publication to check. For example, `id: "gid://shopify/Publication/123"`. *** * resource​Publications [Resource​Publication​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ResourcePublicationConnection) non-null The list of resources that are published to a [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:true ### Arguments Whether to return only the resources that are currently published. If false, then also returns the resources that are scheduled to be published. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * resource​Publications​Count [Count](https://shopify.dev/docs/api/admin-graphql/latest/objects/Count) The number of [publications](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication) that a resource is published to, without [feedback errors](https://shopify.dev/docs/api/admin-graphql/latest/objects/ResourceFeedback). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:true ### Arguments Include only the resource's publications that are published. If false, then return all the resource's publications including future publications. *** * resource​Publications​V2 [Resource​Publication​V2Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ResourcePublicationV2Connection) non-null The list of resources that are either published or staged to be published to a [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:true ### Arguments 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. * catalog​Type [Catalog​Type](https://shopify.dev/docs/api/admin-graphql/latest/enums/CatalogType) Filter publications by catalog type. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * rule​Set [Collection​Rule​Set](https://shopify.dev/docs/api/admin-graphql/latest/objects/CollectionRuleSet) For a smart (automated) collection, specifies the rules that determine whether a product is included. * seo [SEO!](https://shopify.dev/docs/api/admin-graphql/latest/objects/SEO) non-null If the default SEO fields for page title and description have been modified, contains the modified information. * sort​Order [Collection​Sort​Order!](https://shopify.dev/docs/api/admin-graphql/latest/enums/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. * template​Suffix [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/Translation) non-null The published translations associated with the resource. * locale [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) required ### Arguments Filters translations locale. * market​Id [ID](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) Filters translations by market ID. Use this argument to retrieve content specific to a market. *** * unpublished​Publications [Publication​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/PublicationConnection) non-null The list of [publications](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication) that the resource isn't published to. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time ([ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601)) when the collection was last modified. * metafield​Definitions [Metafield​Definition​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldDefinitionConnection) non-nullDeprecated * namespace [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) ### Arguments Filter metafield definitions by namespace. * pinned​Status [Metafield​Definition​Pinned​Status](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldDefinitionPinnedStatus) Default:ANY Filter by the definition's pinned status. * first [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Metafield​Definition​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/latest/enums/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](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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](https://shopify.dev/api/usage/search-syntax). * * default string * created\_at time * id id * key string * namespace string * owner\_type string * type string * updated\_at time - Filter by a case-insensitive search of multiple fields in a document. - Example: * `query=Bob Norman` * `query=title:green hoodie` Filter by the date and time when the metafield definition was created. - Example: * `created_at:>2020-10-21T23:39:20Z` * `created_at:=1234` * `id:<=1234` Filter by the metafield definition [`key`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-key) field. - Example: * `key:some-key` Filter by the metafield definition [`namespace`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-namespace) field. - Example: * `namespace:some-namespace` Filter by the metafield definition [`ownerType`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-ownertype) field. - Example: * `owner_type:PRODUCT` Filter by the metafield definition [`type`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-type) field. - Example: * `type:single_line_text_field` Filter by the date and time when the metafield definition was last updated. Example: * `updated_at:>2020-10-21T23:39:20Z` * `updated_at: { 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 } } } } } } }`, }); ``` #### Shopify CLI ```bash shopify app execute \ --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 } } } } } } }' ``` #### 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/2026-01/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 } } } } } } }`, }); ``` #### Shopify CLI ```bash shopify app execute \ --query \ '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/2026-01/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" }, }, }); ``` #### Shopify CLI ```bash shopify app execute \ --query \ 'query getCollectionIdFromHandle($handle: String!) { collectionByHandle(handle: $handle) { id } }' \ --variables \ '{ "handle": "ipods" }' ``` #### Response ```json { "collectionByHandle": { "id": "gid://shopify/Collection/841564295" } } ```