productByHandle
query

Choose a version:

Requires read_products access scope.

Return a product by its handle.

Anchor to section titled 'Arguments'

Arguments

Anchor to handle handle String! required: A unique string that identifies the product. Handles are automatically generated based on the product's title, and are always lowercase. Whitespace and special characters are replaced with a hyphen: -. If there are multiple consecutive whitespace or special characters, then they're replaced with a single hyphen. Whitespace or special characters at the beginning are removed. If a duplicate product title is used, then the handle is auto-incremented by one. For example, if you had two products called Potion, then their handles would be potion and potion-1. After a product has been created, changing the product title doesn't update the handle.

Was this section helpful?

Anchor to section titled 'Product possible returns'

Product possible returns

Anchor to Product Product Product: The Product object lets you manage products in a merchant’s store.

Products are the goods and services that merchants offer to customers. They can include various details such as title, description, price, images, and options such as size or color. You can use product variants to create or update different versions of the same product. You can also add or update product media. Products can be organized by grouping them into a collection.

Learn more about working with Shopify's product model, including limitations and considerations.

Was this section helpful?

Code examples for QUERY: productByHandle

Query Reference for QUERY: productByHandle

"{\n  productByHandle(handle) {\n    # Product fields\n  }\n}"

Input Reference for QUERY: productByHandle

Schema Reference for QUERY: productByHandle

Display Examples for QUERY: productByHandle

[
  {
    "example": {
      "type_name": "productbyhandle",
      "title": "Retrieve a product by a handle that doesn't exist",
      "description": "Trying to retrieve a product by a handle that doesn't exist returns `null`.\n",
      "query_string": "query {\n  productByHandle(handle: \"there is no product with a handle like this\") {\n    id\n    title\n    productType\n    description\n    vendor\n  }\n}",
      "response": {
        "data": {
          "productByHandle": null
        }
      },
      "api_name": "admin",
      "minimum_api_version": "2023-10",
      "maximum_api_version": "unstable",
      "location": "/components/merchandising/test/unit/graph_api/admin/product_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 { productByHandle(handle: \\\"there is no product with a handle like this\\\") { id title productType description vendor } }\"\n}'\n",
      "remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  query {\n    productByHandle(handle: \"there is no product with a handle like this\") {\n      id\n      title\n      productType\n      description\n      vendor\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    productByHandle(handle: \"there is no product with a handle like this\") {\n      id\n      title\n      productType\n      description\n      vendor\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    productByHandle(handle: \"there is no product with a handle like this\") {\n      id\n      title\n      productType\n      description\n      vendor\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    productByHandle(handle: \"there is no product with a handle like this\") {\n      id\n      title\n      productType\n      description\n      vendor\n    }\n  }\nQUERY;\n\n$response = $client->query([\"query\" => $query]);\n"
    },
    "titleStringKey": "arguments",
    "inputVariableEntries": []
  },
  {
    "example": {
      "type_name": "productbyhandle",
      "title": "Retrieve product information using the product handle",
      "query_string": "query {\n  productByHandle(handle: \"ipod-nano\") {\n    id\n    handle\n    title\n    productType\n    description\n    vendor\n    priceRangeV2 {\n      minVariantPrice {\n        amount\n        currencyCode\n      }\n      maxVariantPrice {\n        amount\n        currencyCode\n      }\n    }\n  }\n}",
      "response": {
        "data": {
          "productByHandle": {
            "id": "gid://shopify/Product/440089423",
            "handle": "ipod-nano",
            "title": "IPod Nano - 8GB",
            "productType": "Cult Products",
            "description": "It's the small iPod with one very big idea: Video. Now the world's most popular music player, available in 4GB and 8GB models, lets you enjoy TV shows, movies, video podcasts, and more. The larger, brighter display means amazing picture quality. In six eye-catching colors, iPod nano is stunning all around. And with models starting at just $149, little speaks volumes.",
            "vendor": "Apple",
            "priceRangeV2": {
              "minVariantPrice": {
                "amount": "199.0",
                "currencyCode": "USD"
              },
              "maxVariantPrice": {
                "amount": "199.0",
                "currencyCode": "USD"
              }
            }
          }
        }
      },
      "api_name": "admin",
      "minimum_api_version": "2023-10",
      "maximum_api_version": "unstable",
      "location": "/components/merchandising/test/unit/graph_api/admin/product_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 { productByHandle(handle: \\\"ipod-nano\\\") { id handle title productType description vendor 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    productByHandle(handle: \"ipod-nano\") {\n      id\n      handle\n      title\n      productType\n      description\n      vendor\n      priceRangeV2 {\n        minVariantPrice {\n          amount\n          currencyCode\n        }\n        maxVariantPrice {\n          amount\n          currencyCode\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    productByHandle(handle: \"ipod-nano\") {\n      id\n      handle\n      title\n      productType\n      description\n      vendor\n      priceRangeV2 {\n        minVariantPrice {\n          amount\n          currencyCode\n        }\n        maxVariantPrice {\n          amount\n          currencyCode\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    productByHandle(handle: \"ipod-nano\") {\n      id\n      handle\n      title\n      productType\n      description\n      vendor\n      priceRangeV2 {\n        minVariantPrice {\n          amount\n          currencyCode\n        }\n        maxVariantPrice {\n          amount\n          currencyCode\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    productByHandle(handle: \"ipod-nano\") {\n      id\n      handle\n      title\n      productType\n      description\n      vendor\n      priceRangeV2 {\n        minVariantPrice {\n          amount\n          currencyCode\n        }\n        maxVariantPrice {\n          amount\n          currencyCode\n        }\n      }\n    }\n  }\nQUERY;\n\n$response = $client->query([\"query\" => $query]);\n"
    },
    "titleStringKey": "arguments",
    "inputVariableEntries": []
  },
  {
    "example": {
      "type_name": "productbyhandle",
      "title": "Retrieve the ID of a product with a specified handle",
      "query_string": "query getProductIdFromHandle($handle: String!) {\n  productByHandle(handle: $handle) {\n    id\n  }\n}",
      "variables": {
        "handle": "element"
      },
      "response": {
        "data": {
          "productByHandle": {
            "id": "gid://shopify/Product/20995642"
          }
        }
      },
      "api_name": "admin",
      "minimum_api_version": "2023-10",
      "maximum_api_version": "unstable",
      "location": "/components/merchandising/test/unit/graph_api/admin/product_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 getProductIdFromHandle($handle: String!) { productByHandle(handle: $handle) { id } }\",\n \"variables\": {\n    \"handle\": \"element\"\n  }\n}'\n",
      "remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  query getProductIdFromHandle($handle: String!) {\n    productByHandle(handle: $handle) {\n      id\n    }\n  }`,\n  {\n    variables: {\n      \"handle\": \"element\"\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 getProductIdFromHandle($handle: String!) {\n    productByHandle(handle: $handle) {\n      id\n    }\n  }\nQUERY\n\nvariables = {\n  \"handle\": \"element\"\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 getProductIdFromHandle($handle: String!) {\n      productByHandle(handle: $handle) {\n        id\n      }\n    }`,\n    \"variables\": {\n      \"handle\": \"element\"\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 getProductIdFromHandle($handle: String!) {\n    productByHandle(handle: $handle) {\n      id\n    }\n  }\nQUERY;\n\n$variables = [\n  \"handle\" => \"element\",\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
    },
    "titleStringKey": "arguments",
    "inputVariableEntries": []
  }
]

productByHandlequery

Arguments

Product possible returns

productByHandle
query