---
title: productByHandle - GraphQL Admin
description: Return a product by its handle.
api_version: 2025-10
api_name: admin
type: query
api_type: graphql
source_url:
  html: https://shopify.dev/docs/api/admin-graphql/latest/queries/productByHandle
  md: https://shopify.dev/docs/api/admin-graphql/latest/queries/productByHandle.md
---

# product​By​Handle

query

Requires `read_products` access scope.

Deprecated. Use [productByIdentifier](https://shopify.dev/docs/api/admin-graphql/latest/queries/productByIdentifier) instead.

Return a product by its handle.

## Arguments

* handle

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/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.

***

## Possible returns

* Product

  [Product](https://shopify.dev/docs/api/admin-graphql/latest/objects/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](https://shopify.dev/docs/api/admin-graphql/latest/objects/productvariant) to create or update different versions of the same product. You can also add or update product [media](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/media). Products can be organized by grouping them into a [collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/collection).

  Learn more about working with [Shopify's product model](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model/product-model-components), including limitations and considerations.

***

## Examples

* ### 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\`.

  #### Query

  ```graphql
  query {
    productByHandle(handle: "there is no product with a handle like this") {
      id
      title
      productType
      description
      vendor
    }
  }
  ```

  #### 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 { productByHandle(handle: \"there is no product with a handle like this\") { id title productType description vendor } }"
  }'
  ```

  #### 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 {
      productByHandle(handle: "there is no product with a handle like this") {
        id
        title
        productType
        description
        vendor
      }
    }`,
    );
    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 {
      productByHandle(handle: "there is no product with a handle like this") {
        id
        title
        productType
        description
        vendor
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      productByHandle(handle: "there is no product with a handle like this") {
        id
        title
        productType
        description
        vendor
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "productByHandle": null
  }
  ```

* ### Retrieve product information using the product handle

  #### Query

  ```graphql
  query {
    productByHandle(handle: "ipod-nano") {
      id
      handle
      title
      productType
      description
      vendor
      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 { productByHandle(handle: \"ipod-nano\") { id handle title productType description vendor 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 {
      productByHandle(handle: "ipod-nano") {
        id
        handle
        title
        productType
        description
        vendor
        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 {
      productByHandle(handle: "ipod-nano") {
        id
        handle
        title
        productType
        description
        vendor
        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 {
      productByHandle(handle: "ipod-nano") {
        id
        handle
        title
        productType
        description
        vendor
        priceRangeV2 {
          minVariantPrice {
            amount
            currencyCode
          }
          maxVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "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"
        }
      }
    }
  }
  ```

* ### Retrieve the ID of a product with a specified handle

  #### Query

  ```graphql
  query getProductIdFromHandle($handle: String!) {
    productByHandle(handle: $handle) {
      id
    }
  }
  ```

  #### Variables

  ```json
  {
    "handle": "element"
  }
  ```

  #### 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 getProductIdFromHandle($handle: String!) { productByHandle(handle: $handle) { id } }",
   "variables": {
      "handle": "element"
    }
  }'
  ```

  #### 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 getProductIdFromHandle($handle: String!) {
      productByHandle(handle: $handle) {
        id
      }
    }`,
    {
      variables: {
          "handle": "element"
      },
    },
    );
    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 getProductIdFromHandle($handle: String!) {
      productByHandle(handle: $handle) {
        id
      }
    }
  QUERY

  variables = {
    "handle": "element"
  }

  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 getProductIdFromHandle($handle: String!) {
        productByHandle(handle: $handle) {
          id
        }
      }`,
      "variables": {
          "handle": "element"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "productByHandle": {
      "id": "gid://shopify/Product/20995642"
    }
  }
  ```

[Open in GraphiQL](http://localhost:3457/graphiql?query=query%20%7B%0A%20%20productByHandle\(handle%3A%20%22there%20is%20no%20product%20with%20a%20handle%20like%20this%22\)%20%7B%0A%20%20%20%20id%0A%20%20%20%20title%0A%20%20%20%20productType%0A%20%20%20%20description%0A%20%20%20%20vendor%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 {
    productByHandle(handle: "there is no product with a handle like this") {
      id
      title
      productType
      description
      vendor
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}
```

##### GQL

```
query {
  productByHandle(handle: "there is no product with a handle like this") {
    id
    title
    productType
    description
    vendor
  }
}
```

##### 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 { productByHandle(handle: \"there is no product with a handle like this\") { id title productType description vendor } }"
}'
```

##### 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 {
    productByHandle(handle: "there is no product with a handle like this") {
      id
      title
      productType
      description
      vendor
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}
```

##### Node.js

```
const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    productByHandle(handle: "there is no product with a handle like this") {
      id
      title
      productType
      description
      vendor
    }
  }`,
});
```

##### 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 {
    productByHandle(handle: "there is no product with a handle like this") {
      id
      title
      productType
      description
      vendor
    }
  }
QUERY

response = client.query(query: query)
```

## Response

JSON

```json
{
  "productByHandle": null
}
```