collectionByHandle - admin-graphql - QUERY

Version: 2025-01

Description:

Return a collection by its handle.

Access Scopes

`read_products` access scope.

Arguments

• handle: String! - The handle of the collection.

Returns

• availablePublicationsCount: 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! A single-line, text-only description of the collection, stripped of any HTML tags and formatting that were included in the description.
• descriptionHtml: HTML! 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.
• feedback: ResourceFeedback Information about the collection that's provided through resource feedback.
• handle: String! 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.
• hasProduct: Boolean! Whether the collection includes the specified product.
• id: ID! A globally-unique ID.
• image: Image The image associated with the collection.
• legacyResourceId: UnsignedInt64! The ID of the corresponding resource in the REST Admin API.
• metafield: 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.
• productsCount: Count The number of products in the collection.
• publicationCount: Int! 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).
• publishedOnChannel: Boolean! Whether the resource is published to a specific channel.
• publishedOnCurrentChannel: Boolean! Whether the resource is published to a [channel](https://shopify.dev/docs/api/admin-graphql/latest/objects/Channel). For example, the resource might be published to the online store channel.
• publishedOnCurrentPublication: Boolean! Whether the resource is published to the app's [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). For example, the resource might be published to the app's online store channel.
• publishedOnPublication: Boolean! Whether the resource is published to a specified [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication).
• resourcePublicationsCount: 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).
• ruleSet: CollectionRuleSet For a smart (automated) collection, specifies the rules that determine whether a product is included.
• seo: SEO! If the default SEO fields for page title and description have been modified, contains the modified information.
• sortOrder: CollectionSortOrder! 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.
• storefrontId: StorefrontID! The Storefront GraphQL API ID of the `Collection`. As of the `2022-04` version release, the Storefront GraphQL API will no longer return Base64 encoded IDs to match the behavior of the Admin GraphQL API. Therefore, you can safely use the `id` field's value instead.
• templateSuffix: 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! 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! The published translations associated with the resource.
• updatedAt: DateTime! The date and time ([ISO 8601 format](http://en.wikipedia.org/wiki/ISO_8601)) when the collection was last modified.

Examples

• Retrieve a collection by a handle that doesn't exist

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/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"
          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"
          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"
          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"
          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"
          Graphql query: "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}"
        

  input: null

  response: {
    "data": {
      "collectionByHandle": null
    }
  }

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

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/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"
          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"
          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"
          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"
          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"
          Graphql query: "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}"
        

  input: null

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

  Retrieve the ID of a collection with a specified handle

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/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"
          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"
          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"
          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"
          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"
          Graphql query: "query getCollectionIdFromHandle($handle: String!) {\n  collectionByHandle(handle: $handle) {\n    id\n  }\n}"
        

  input: {
    "handle": "ipods"
  }

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