Anchor to section titled 'undefined'collection
collection
query
Unstable
Requires read access scope.
Return a collection by its handle.
Anchor to section titled 'Arguments'
Arguments
The handle of the collection.
Was this section helpful?
Anchor to section titled 'Collection possible returns'
Collection possible returns
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.
Was this section helpful?
Code examples for QUERY: collectionByHandle
Query Reference for QUERY: collectionByHandle
"{\n collectionByHandle(handle) {\n # Collection fields\n }\n}"Input Reference for QUERY: collectionByHandle
Schema Reference for QUERY: collectionByHandle
Display Examples for QUERY: collectionByHandle
[
{
"example": {
"type_name": "collectionbyhandle",
"title": "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`.\n",
"query_string": "query {\n collectionByHandle(handle: \"there is no collection with a handle like this\") {\n id\n title\n products(first: 5, reverse: true) {\n edges {\n node {\n id\n title\n createdAt\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n}",
"response": {
"data": {
"collectionByHandle": null
}
},
"api_name": "admin",
"minimum_api_version": "2023-10",
"maximum_api_version": "unstable",
"location": "/components/merchandising/test/unit/graph_api/admin/collection_test.rb",
"curl_example": "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/unstable/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"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 } } } } } } }\"\n}'\n",
"remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n query {\n collectionByHandle(handle: \"there is no collection with a handle like this\") {\n id\n title\n products(first: 5, reverse: true) {\n edges {\n node {\n id\n title\n createdAt\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }`,\n);\n\nconst data = await response.json();\n",
"ruby_example": "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n query {\n collectionByHandle(handle: \"there is no collection with a handle like this\") {\n id\n title\n products(first: 5, reverse: true) {\n edges {\n node {\n id\n title\n createdAt\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }\nQUERY\n\nresponse = client.query(query: query)\n",
"node_example": "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: `query {\n collectionByHandle(handle: \"there is no collection with a handle like this\") {\n id\n title\n products(first: 5, reverse: true) {\n edges {\n node {\n id\n title\n createdAt\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }`,\n});\n",
"php_example": "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n query {\n collectionByHandle(handle: \"there is no collection with a handle like this\") {\n id\n title\n products(first: 5, reverse: true) {\n edges {\n node {\n id\n title\n createdAt\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }\nQUERY;\n\n$response = $client->query([\"query\" => $query]);\n"
},
"titleStringKey": "arguments",
"inputVariableEntries": []
},
{
"example": {
"type_name": "collectionbyhandle",
"title": "Retrieve a collection with five of its best-selling products by its handle",
"query_string": "query {\n collectionByHandle(handle: \"everything\") {\n id\n title\n products(first: 5, sortKey: BEST_SELLING) {\n edges {\n node {\n id\n title\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n}",
"response": {
"data": {
"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"
}
}
}
}
]
}
}
}
},
"api_name": "admin",
"minimum_api_version": "2023-10",
"maximum_api_version": "unstable",
"location": "/components/merchandising/test/unit/graph_api/admin/collection_test.rb",
"curl_example": "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/unstable/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"query { collectionByHandle(handle: \\\"everything\\\") { id title products(first: 5, sortKey: BEST_SELLING) { edges { node { id title priceRangeV2 { minVariantPrice { amount currencyCode } maxVariantPrice { amount currencyCode } } } } } } }\"\n}'\n",
"remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n query {\n collectionByHandle(handle: \"everything\") {\n id\n title\n products(first: 5, sortKey: BEST_SELLING) {\n edges {\n node {\n id\n title\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }`,\n);\n\nconst data = await response.json();\n",
"ruby_example": "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n query {\n collectionByHandle(handle: \"everything\") {\n id\n title\n products(first: 5, sortKey: BEST_SELLING) {\n edges {\n node {\n id\n title\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }\nQUERY\n\nresponse = client.query(query: query)\n",
"node_example": "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: `query {\n collectionByHandle(handle: \"everything\") {\n id\n title\n products(first: 5, sortKey: BEST_SELLING) {\n edges {\n node {\n id\n title\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }`,\n});\n",
"php_example": "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n query {\n collectionByHandle(handle: \"everything\") {\n id\n title\n products(first: 5, sortKey: BEST_SELLING) {\n edges {\n node {\n id\n title\n priceRangeV2 {\n minVariantPrice {\n amount\n currencyCode\n }\n maxVariantPrice {\n amount\n currencyCode\n }\n }\n }\n }\n }\n }\n }\nQUERY;\n\n$response = $client->query([\"query\" => $query]);\n"
},
"titleStringKey": "arguments",
"inputVariableEntries": []
},
{
"example": {
"type_name": "collectionbyhandle",
"title": "Retrieve the ID of a collection with a specified handle",
"query_string": "query getCollectionIdFromHandle($handle: String!) {\n collectionByHandle(handle: $handle) {\n id\n }\n}",
"variables": {
"handle": "ipods"
},
"response": {
"data": {
"collectionByHandle": {
"id": "gid://shopify/Collection/841564295"
}
}
},
"api_name": "admin",
"minimum_api_version": "2023-10",
"maximum_api_version": "unstable",
"location": "/components/merchandising/test/unit/graph_api/admin/collection_test.rb",
"curl_example": "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/unstable/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"query getCollectionIdFromHandle($handle: String!) { collectionByHandle(handle: $handle) { id } }\",\n \"variables\": {\n \"handle\": \"ipods\"\n }\n}'\n",
"remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n query getCollectionIdFromHandle($handle: String!) {\n collectionByHandle(handle: $handle) {\n id\n }\n }`,\n {\n variables: {\n \"handle\": \"ipods\"\n },\n },\n);\n\nconst data = await response.json();\n",
"ruby_example": "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n query getCollectionIdFromHandle($handle: String!) {\n collectionByHandle(handle: $handle) {\n id\n }\n }\nQUERY\n\nvariables = {\n \"handle\": \"ipods\"\n}\n\nresponse = client.query(query: query, variables: variables)\n",
"node_example": "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `query getCollectionIdFromHandle($handle: String!) {\n collectionByHandle(handle: $handle) {\n id\n }\n }`,\n \"variables\": {\n \"handle\": \"ipods\"\n },\n },\n});\n",
"php_example": "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n query getCollectionIdFromHandle($handle: String!) {\n collectionByHandle(handle: $handle) {\n id\n }\n }\nQUERY;\n\n$variables = [\n \"handle\" => \"ipods\",\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
},
"titleStringKey": "arguments",
"inputVariableEntries": []
}
]