# productByHandle - admin-graphql - QUERY
Version: 2024-10

## Description
Return a product by its handle.

### Access Scopes
`read_products` access scope.


## Arguments
* [handle](/docs/api/admin-graphql/2024-10/scalars/String): String! - 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.


## Returns
* [availablePublicationsCount](/docs/api/admin-graphql/2024-10/objects/Count): 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).
* [bodyHtml](/docs/api/admin-graphql/2024-10/scalars/String): String The description of the product, with
HTML tags. For example, the description might include
bold `<strong></strong>` and italic `<i></i>` text.
* [category](/docs/api/admin-graphql/2024-10/objects/TaxonomyCategory): TaxonomyCategory The category of a product
from [Shopify's Standard Product Taxonomy](https://shopify.github.io/product-taxonomy/releases/unstable/?categoryId=sg-4-17-2-17).
* [combinedListing](/docs/api/admin-graphql/2024-10/objects/CombinedListing): CombinedListing A special product type that combines separate products from a store into a single product listing.
[Combined listings](https://shopify.dev/apps/build/product-merchandising/combined-listings) are connected
by a shared option, such as color, model, or dimension.
* [combinedListingRole](/docs/api/admin-graphql/2024-10/enums/CombinedListingsRole): CombinedListingsRole The [role of the product](https://shopify.dev/docs/apps/build/product-merchandising/combined-listings/build-for-combined-listings)
in a combined listing.

If `null`, then the product isn't part of any combined listing.
* [compareAtPriceRange](/docs/api/admin-graphql/2024-10/objects/ProductCompareAtPriceRange): ProductCompareAtPriceRange The [compare-at price range](https://help.shopify.com/manual/products/details/product-pricing/sale-pricing)
of the product in the shop's default currency.
* [contextualPricing](/docs/api/admin-graphql/2024-10/objects/ProductContextualPricing): ProductContextualPricing! The pricing that applies to a customer in a specific context. For example, a price might vary depending on the customer's location.
* [createdAt](/docs/api/admin-graphql/2024-10/scalars/DateTime): DateTime! The date and time when the product was created.
* [customProductType](/docs/api/admin-graphql/2024-10/scalars/String): String The custom product type specified by the merchant.
* [defaultCursor](/docs/api/admin-graphql/2024-10/scalars/String): String! A default [cursor](https://shopify.dev/api/usage/pagination-graphql) that returns the single next record, sorted ascending by ID.
* [description](/docs/api/admin-graphql/2024-10/scalars/String): String! A single-line description of the product,
with [HTML tags](https://developer.mozilla.org/en-US/docs/Web/HTML) removed.
* [descriptionHtml](/docs/api/admin-graphql/2024-10/scalars/HTML): HTML! The description of the product, with
HTML tags. For example, the description might include
bold `<strong></strong>` and italic `<i></i>` text.
* [descriptionPlainSummary](/docs/api/admin-graphql/2024-10/scalars/String): String! Stripped description of the product, single line with HTML tags removed.
Truncated to 60 characters.
* [featuredImage](/docs/api/admin-graphql/2024-10/objects/Image): Image The featured image for the product.
* [featuredMedia](/docs/api/admin-graphql/2024-10/interfaces/Media): Media The featured [media](https://shopify.dev/docs/apps/build/online-store/product-media)
associated with the product.
* [feedback](/docs/api/admin-graphql/2024-10/objects/ResourceFeedback): ResourceFeedback The information that lets merchants know what steps they need to take
to make sure that the app is set up correctly.

For example, if a merchant hasn't set up a product correctly in the app,
then the feedback might include a message that says "You need to add a price
to this product".
* [giftCardTemplateSuffix](/docs/api/admin-graphql/2024-10/scalars/String): String The [theme template](https://shopify.dev/docs/storefronts/themes/architecture/templates) that's used when customers view the gift card in a store.
* [handle](/docs/api/admin-graphql/2024-10/scalars/String): String! A unique, human-readable string of the product's title. A handle can contain letters, hyphens (`-`), and numbers, but no spaces.
The handle is used in the online store URL for the product.
* [hasOnlyDefaultVariant](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product has only a single variant with the default option and value.
* [hasOutOfStockVariants](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product has variants that are out of stock.
* [hasVariantsThatRequiresComponents](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether at least one of the product variants requires
[bundle components](https://shopify.dev/docs/apps/build/product-merchandising/bundles/add-product-fixed-bundle).

Learn more about
[store eligibility for bundles](https://shopify.dev/docs/apps/build/product-merchandising/bundles#store-eligibility).
* [id](/docs/api/admin-graphql/2024-10/scalars/ID): ID! A globally-unique ID.
* [inCollection](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product
is in a specified
[collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/collection).
* [isGiftCard](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product is a gift card.
* [legacyResourceId](/docs/api/admin-graphql/2024-10/scalars/UnsignedInt64): UnsignedInt64! The ID of the corresponding resource in the REST Admin API.
* [mediaCount](/docs/api/admin-graphql/2024-10/objects/Count): Count The total count of [media](https://shopify.dev/docs/apps/build/online-store/product-media)
that's associated with a product.
* [metafield](/docs/api/admin-graphql/2024-10/objects/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.
* [onlineStorePreviewUrl](/docs/api/admin-graphql/2024-10/scalars/URL): URL The [preview URL](https://help.shopify.com/manual/online-store/setting-up#preview-your-store) for the online store.
* [onlineStoreUrl](/docs/api/admin-graphql/2024-10/scalars/URL): URL The product's URL on the online store.
If `null`, then the product isn't published to the online store sales channel.
* [options](/docs/api/admin-graphql/2024-10/objects/ProductOption): ProductOption! A list of product options. The limit is defined by the
[shop's resource limits for product options](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop#field-resourcelimits) (`Shop.resourceLimits.maxProductOptions`).
* [priceRange](/docs/api/admin-graphql/2024-10/objects/ProductPriceRange): ProductPriceRange! The price range of the product.
* [priceRangeV2](/docs/api/admin-graphql/2024-10/objects/ProductPriceRangeV2): ProductPriceRangeV2! The minimum and maximum prices of a product, expressed in decimal numbers.
For example, if the product is priced between $10.00 and $50.00,
then the price range is $10.00 - $50.00.
* [privateMetafield](/docs/api/admin-graphql/2024-10/objects/PrivateMetafield): PrivateMetafield Returns a private metafield by namespace and key that belongs to the resource.
* [productCategory](/docs/api/admin-graphql/2024-10/objects/ProductCategory): ProductCategory The product category specified by the merchant.
* [productType](/docs/api/admin-graphql/2024-10/scalars/String): String! The [product type](https://help.shopify.com/manual/products/details/product-type)
that merchants define.
* [publicationCount](/docs/api/admin-graphql/2024-10/scalars/Int): 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).
* [publishedAt](/docs/api/admin-graphql/2024-10/scalars/DateTime): DateTime The date and time when the product was published to the online store.
* [publishedInContext](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product is published for a customer only in a specified context. For example, a product might be published for a customer only in a specific location.
* [publishedOnChannel](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the resource is published to a specific channel.
* [publishedOnCurrentChannel](/docs/api/admin-graphql/2024-10/scalars/Boolean): 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](/docs/api/admin-graphql/2024-10/scalars/Boolean): 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](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the resource is published to a specified
[publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication).
* [requiresSellingPlan](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether the product can only be purchased with
a [selling plan](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans).
Products that are sold on subscription (`requiresSellingPlan: true`) can be updated only for online stores.
If you update a product to be subscription-only (`requiresSellingPlan:false`), then the product is unpublished from all channels, except the online store.
* [resourcePublicationOnCurrentPublication](/docs/api/admin-graphql/2024-10/objects/ResourcePublicationV2): ResourcePublicationV2 The resource that's either published or staged to be published to
the [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication).
* [resourcePublicationsCount](/docs/api/admin-graphql/2024-10/objects/Count): 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).
* [restrictedForResource](/docs/api/admin-graphql/2024-10/objects/RestrictedForResource): RestrictedForResource Whether the merchant can make changes to the product when they
[edit the order](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders)
associated with the product. For example, a merchant might be restricted from changing product details when they
edit an order.
* [sellingPlanGroupCount](/docs/api/admin-graphql/2024-10/scalars/Int): Int! A count of [selling plan groups](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans/build-a-selling-plan)
that are associated with the product.
* [sellingPlanGroupsCount](/docs/api/admin-graphql/2024-10/objects/Count): Count A count of [selling plan groups](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans/build-a-selling-plan)
that are associated with the product.
* [seo](/docs/api/admin-graphql/2024-10/objects/SEO): SEO! The [SEO title and description](https://help.shopify.com/manual/promoting-marketing/seo/adding-keywords)
that are associated with a product.
* [standardizedProductType](/docs/api/admin-graphql/2024-10/objects/StandardizedProductType): StandardizedProductType The standardized product type in the Shopify product taxonomy.
* [status](/docs/api/admin-graphql/2024-10/enums/ProductStatus): ProductStatus! The [product status](https://help.shopify.com/manual/products/details/product-details-page#product-status),
which controls visibility across all sales channels.
* [storefrontId](/docs/api/admin-graphql/2024-10/scalars/StorefrontID): StorefrontID! The Storefront GraphQL API ID of the `Product`.

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.
* [tags](/docs/api/admin-graphql/2024-10/scalars/String): String! A comma-separated list of searchable keywords that are
associated with the product. For example, a merchant might apply the `sports`
and `summer` tags to products that are associated with sportwear for summer.

Updating `tags` overwrites
any existing tags that were previously added to the product. To add new tags without overwriting
existing tags, use the [`tagsAdd`](https://shopify.dev/api/admin-graphql/latest/mutations/tagsadd)
mutation.
* [templateSuffix](/docs/api/admin-graphql/2024-10/scalars/String): String The [theme template](https://shopify.dev/docs/storefronts/themes/architecture/templates) that's used when customers view the product in a store.
* [title](/docs/api/admin-graphql/2024-10/scalars/String): String! The name for the product that displays to customers. The title is used to construct the product's handle.
For example, if a product is titled "Black Sunglasses", then the handle is `black-sunglasses`.
* [totalInventory](/docs/api/admin-graphql/2024-10/scalars/Int): Int! The quantity of inventory that's in stock.
* [totalVariants](/docs/api/admin-graphql/2024-10/scalars/Int): Int! The number of [variants](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant)
that are associated with the product.
* [tracksInventory](/docs/api/admin-graphql/2024-10/scalars/Boolean): Boolean! Whether [inventory tracking](https://help.shopify.com/manual/products/inventory/getting-started-with-inventory/set-up-inventory-tracking)
has been enabled for the product.
* [translations](/docs/api/admin-graphql/2024-10/objects/Translation): Translation! The published translations associated with the resource.
* [updatedAt](/docs/api/admin-graphql/2024-10/scalars/DateTime): DateTime! The date and time when the product was last modified.
A product's `updatedAt` value can change for different reasons. For example, if an order
is placed for a product that has inventory tracking set up, then the inventory adjustment
is counted as an update.
* [variantsCount](/docs/api/admin-graphql/2024-10/objects/Count): Count The number of [variants](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant)
that are associated with the product.
* [vendor](/docs/api/admin-graphql/2024-10/scalars/String): String! The name of the product's vendor.


## Examples
### Retrieve a product by a handle that doesn't exist
Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-10/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"
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"
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" 
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"
Graphql query: "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}"
#### Graphql Input
null
#### Graphql Response
{
  "data": {
    "productByHandle": null
  }
}

### Retrieve product information using the product handle
Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-10/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"
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"
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" 
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"
Graphql query: "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}"
#### Graphql Input
null
#### Graphql 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"
        }
      }
    }
  }
}

### Retrieve the ID of a product with a specified handle
Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-10/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"
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"
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" 
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"
Graphql query: "query getProductIdFromHandle($handle: String!) {\n  productByHandle(handle: $handle) {\n    id\n  }\n}"
#### Graphql Input
{
  "handle": "element"
}
#### Graphql Response
{
  "data": {
    "productByHandle": {
      "id": "gid://shopify/Product/20995642"
    }
  }
}