--- title: productByHandle - GraphQL Admin description: >- Retrieves a [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) using its handle. A handle is a unique, URL-friendly string that Shopify automatically generates from the product's title. Returns `null` if no product exists with the specified handle. api_version: 2025-01 api_name: admin type: query api_type: graphql source_url: html: 'https://shopify.dev/docs/api/admin-graphql/2025-01/queries/productByHandle' md: >- https://shopify.dev/docs/api/admin-graphql/2025-01/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. Retrieves a [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) using its handle. A handle is a unique, URL-friendly string that Shopify automatically generates from the product's title. Returns `null` if no product exists with the specified handle. ## Arguments * handle [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/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. * available​Publications​Count [Count](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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). * bundle​Components [Product​Bundle​Component​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ProductBundleComponentConnection) non-null A list of [components](https://shopify.dev/docs/apps/build/product-merchandising/bundles/add-product-fixed-bundle) that are associated with a product in a bundle. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * category [Taxonomy​Category](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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). * collections [Collection​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/CollectionConnection) non-null A list of [collections](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection) that include the product. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Collection​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/CollectionSortKeys) Default:ID Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax). * * default string * collection\_type string * handle string - Filter by a case-insensitive search of multiple fields in a document. - Example: * `query=Bob Norman` * `query=title:green hoodie` - Valid values: * `custom` * `smart` * * id id * product\_id id - Filter by `id` range. - Example: * `id:1234` * `id:>=1234` * `id:<=1234` Filter by collections containing a product by its ID. * * product\_publication\_status string * publishable\_status string * published\_at time - Filter by channel approval process status of the resource on a channel, such as the online store. The value is a composite of the [channel `app` ID](https://shopify.dev/api/admin-graphql/latest/objects/Channel#field-Channel.fields.app) (`Channel.app.id`) and one of the valid values. For simple visibility checks, use [published\_status](https://shopify.dev/api/admin-graphql/latest/queries/products#argument-query-filter-publishable_status) instead. - Valid values: * `* {channel_app_id}-approved` * `* {channel_app_id}-rejected` * `* {channel_app_id}-needs_action` * `* {channel_app_id}-awaiting_review` * `* {channel_app_id}-published` * `* {channel_app_id}-demoted` * `* {channel_app_id}-scheduled` * `* {channel_app_id}-provisionally_published` Example: * `product_publication_status:189769876-approved` **Deprecated:** This parameter is deprecated as of 2025-12 and will be removed in a future API version. Use [published\_status](https://shopify.dev/api/admin-graphql/latest/queries/products#argument-query-filter-publishable_status) for visibility checks. Filter by the publishable status of the resource on a channel. The value is a composite of the [channel `app` ID](https://shopify.dev/api/admin-graphql/latest/objects/Channel#app-price) (`Channel.app.id`) and one of the valid status values. - Valid values: * `* {channel_app_id}-unset` * `* {channel_app_id}-pending` * `* {channel_app_id}-approved` * `* {channel_app_id}-not_approved` Example: * `publishable_status:580111-unset` * `publishable_status:580111-pending` Filter by the date and time when the collection was published to the Online Store. * * published\_status string * title string - Filter resources by their visibility and publication state on a channel. Online store channel filtering: - `online_store_channel`: Returns all resources in the online store channel, regardless of publication status. - `published`/`visible`: Returns resources that are published to the online store. - `unpublished`: Returns resources that are not published to the online store. Channel-specific filtering using the [channel `app` ID](https://shopify.dev/api/admin-graphql/latest/objects/Channel#app-price) (`Channel.app.id`) with suffixes: - `{channel_app_id}-published`: Returns resources published to the specified channel. - `{channel_app_id}-visible`: Same as `{channel_app_id}-published` (kept for backwards compatibility). - `{channel_app_id}-intended`: Returns resources added to the channel but not yet published. - `{channel_app_id}-hidden`: Returns resources not added to the channel or not published. Other: - `unavailable`: Returns resources not published to any channel. - Valid values: * `online_store_channel` * `published` * `visible` * `unpublished` * `* {channel_app_id}-published` * `* {channel_app_id}-visible` * `* {channel_app_id}-intended` * `* {channel_app_id}-hidden` * `unavailable` Example: * `published_status:online_store_channel` * `published_status:published` * `published_status:580111-published` * `published_status:580111-hidden` * `published_status:unavailable` * updated\_at time *** * combined​Listing [Combined​Listing](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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. * combined​Listing​Role [Combined​Listings​Role](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/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. * compare​At​Price​Range [Product​Compare​At​Price​Range](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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. * contextual​Pricing [Product​Contextual​Pricing!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductContextualPricing) non-null The pricing that applies to a customer in a specific context. For example, a price might vary depending on the customer's location. Only active markets are considered in the price resolution. * context [Contextual​Pricing​Context!](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ContextualPricingContext) required ### Arguments The context used to generate contextual pricing for the variant. *** * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/DateTime) non-null The date and time when the product was created. * default​Cursor [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null A default [cursor](https://shopify.dev/api/usage/pagination-graphql) that returns the single next record, sorted ascending by ID. * description [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null A single-line description of the product, with [HTML tags](https://developer.mozilla.org/en-US/docs/Web/HTML) removed. * truncate​At [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments Truncates a string after the given length. *** * description​Html [HTML!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/HTML) non-null The description of the product, with HTML tags. For example, the description might include bold `` and italic `` text. * events [Event​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/EventConnection) non-null The paginated list of events associated with the host subject. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Event​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/EventSortKeys) Default:ID Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax). * * action string * comments boolean * created\_at time * id id * subject\_type string - The action that occured. - Example: * `action:create` Whether or not to include [comment-events](https://shopify.dev/api/admin-graphql/latest/objects/CommentEvent) in your search, passing `false` will exclude comment-events, any other value will include comment-events. - Example: * `false` * `true` Filter by the date and time when the event happened. - Example: * `created_at:>2020-10-21` * `created_at:=1234` * `id:<=1234` The resource type affected by this event. See [EventSubjectType](https://shopify.dev/api/admin-graphql/latest/enums/EventSubjectType) for possible values. Example: * `PRODUCT_VARIANT` * `PRODUCT` * `COLLECTION` *** * featured​Media [Media](https://shopify.dev/docs/api/admin-graphql/2025-01/interfaces/Media) The featured [media](https://shopify.dev/docs/apps/build/online-store/product-media) associated with the product. * feedback [Resource​Feedback](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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". * gift​Card​Template​Suffix [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/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 [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null 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. * has​Only​Default​Variant [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Whether the product has only a single variant with the default option and value. * has​Out​Of​Stock​Variants [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Whether the product has variants that are out of stock. * has​Variants​That​Requires​Components [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null 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 [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) non-null A globally-unique ID. * in​Collection [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Whether the product is in a specified [collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/collection). * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) required ### Arguments The ID of the collection to check. For example, `id: "gid://shopify/Collection/123"`. *** * is​Gift​Card [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Whether the product is a gift card. * legacy​Resource​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/UnsignedInt64) non-null The ID of the corresponding resource in the REST Admin API. * media [Media​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/MediaConnection) non-null The [media](https://shopify.dev/docs/apps/build/online-store/product-media) associated with the product. Valid media are images, 3D models, videos. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Product​Media​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/ProductMediaSortKeys) Default:POSITION Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax). * * id id * media\_type string - Filter by `id` range. - Example: * `id:1234` * `id:>=1234` * `id:<=1234` Valid values: * `IMAGE` * `VIDEO` * `MODEL_3D` * `EXTERNAL_VIDEO` *** * media​Count [Count](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/Count) The total count of [media](https://shopify.dev/docs/apps/build/online-store/product-media) that's associated with a product. * metafield [Metafield](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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. * namespace [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) ### Arguments The container the metafield belongs to. If omitted, the app-reserved namespace will be used. * key [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) required The key for the metafield. *** * metafields [Metafield​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/MetafieldConnection) non-null A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * namespace [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) ### Arguments The metafield namespace to filter by. If omitted, the app-reserved namespace will be used. * keys [\[String!\]](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) List of keys of metafields in the format `namespace.key`, will be returned in the same format. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * online​Store​Preview​Url [URL](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/URL) The [preview URL](https://help.shopify.com/manual/online-store/setting-up#preview-your-store) for the online store. * online​Store​Url [URL](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/URL) The product's URL on the online store. If `null`, then the product isn't published to the online store sales channel. * options [\[Product​Option!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductOption) non-null 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`). * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments Truncate the array result to this size. *** * price​Range​V2 [Product​Price​Range​V2!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/ProductPriceRangeV2) non-null 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. * product​Type [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null The [product type](https://help.shopify.com/manual/products/details/product-type) that merchants define. * published​At [Date​Time](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/DateTime) The date and time when the product was published to the online store. * published​In​Context [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null 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. * context [Contextual​Publication​Context!](https://shopify.dev/docs/api/admin-graphql/2025-01/input-objects/ContextualPublicationContext) required ### Arguments The context used to determine publication status. *** * published​On​Current​Publication [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null 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. * published​On​Publication [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null Whether the resource is published to a specified [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * publication​Id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) required ### Arguments The ID of the publication to check. For example, `id: "gid://shopify/Publication/123"`. *** * requires​Selling​Plan [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null 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. * resource​Publication​On​Current​Publication [Resource​Publication​V2](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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). * resource​Publications [Resource​Publication​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ResourcePublicationConnection) non-null The list of resources that are published to a [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:true ### Arguments Whether to return only the resources that are currently published. If false, then also returns the resources that are scheduled to be published. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * resource​Publications​Count [Count](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:true ### Arguments Include only the resource's publications that are published. If false, then return all the resource's publications including future publications. *** * resource​Publications​V2 [Resource​Publication​V2Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ResourcePublicationV2Connection) non-null The list of resources that are either published or staged to be published to a [publication](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication). * only​Published [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:true ### Arguments Whether to return only the resources that are currently published. If false, then also returns the resources that are scheduled or staged to be published. * catalog​Type [Catalog​Type](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/CatalogType) Filter publications by catalog type. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * restricted​For​Resource [Restricted​For​Resource](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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. * calculated​Order​Id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) required ### Arguments The resource Id of the order with edits applied but not saved. *** * selling​Plan​Groups [Selling​Plan​Group​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/SellingPlanGroupConnection) non-null A list of all [selling plan groups](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans/build-a-selling-plan) that are associated with the product either directly, or through the product's variants. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * selling​Plan​Groups​Count [Count](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/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 [SEO!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/SEO) non-null The [SEO title and description](https://help.shopify.com/manual/promoting-marketing/seo/adding-keywords) that are associated with a product. * status [Product​Status!](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/ProductStatus) non-null The [product status](https://help.shopify.com/manual/products/details/product-details-page#product-status), which controls visibility across all sales channels. * tags [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null 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. * template​Suffix [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The [theme template](https://shopify.dev/docs/storefronts/themes/architecture/templates) that's used when customers view the product in a store. * title [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null 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`. * total​Inventory [Int!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) non-null The quantity of inventory that's in stock. * tracks​Inventory [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) non-null 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 [\[Translation!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/Translation) non-null The published translations associated with the resource. * locale [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) required ### Arguments Filters translations locale. * market​Id [ID](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/ID) Filters translations by market ID. Use this argument to retrieve content specific to a market. *** * unpublished​Publications [Publication​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/PublicationConnection) non-null The list of [publications](https://shopify.dev/docs/api/admin-graphql/latest/objects/Publication) that the resource isn't published to. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/DateTime) non-null 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. * variants [Product​Variant​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ProductVariantConnection) non-null A list of [variants](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant) associated with the product. If querying a single product at the root, you can fetch up to 2048 variants. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) ### Arguments The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Product​Variant​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/ProductVariantSortKeys) Default:POSITION Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). *** * variants​Count [Count](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/Count) The number of [variants](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant) that are associated with the product. * vendor [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-null The name of the product's vendor. * body​Html [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) Deprecated * custom​Product​Type [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) Deprecated * description​Plain​Summary [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) non-nullDeprecated * featured​Image [Image](https://shopify.dev/docs/api/admin-graphql/2025-01/objects/Image) Deprecated * images [Image​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/ImageConnection) non-nullDeprecated * max​Width [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) Deprecated ### Arguments * max​Height [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) Deprecated * crop [Crop​Region](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/CropRegion) Deprecated * scale [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) DeprecatedDefault:1 * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Product​Image​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/ProductImageSortKeys) Default:POSITION Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). *** * metafield​Definitions [Metafield​Definition​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/MetafieldDefinitionConnection) non-nullDeprecated * namespace [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) ### Arguments Filter metafield definitions by namespace. * pinned​Status [Metafield​Definition​Pinned​Status](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldDefinitionPinnedStatus) Default:ANY Filter by the definition's pinned status. * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * reverse [Boolean](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Metafield​Definition​Sort​Keys](https://shopify.dev/docs/api/admin-graphql/2025-01/enums/MetafieldDefinitionSortKeys) Default:ID Sort the underlying list using a key. If your query is slow or returns an error, then [try specifying a sort key that matches the field used in the search](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations). * query [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax). * * default string * created\_at time * id id * key string * namespace string * owner\_type string * type string * updated\_at time - Filter by a case-insensitive search of multiple fields in a document. - Example: * `query=Bob Norman` * `query=title:green hoodie` Filter by the date and time when the metafield definition was created. - Example: * `created_at:>2020-10-21T23:39:20Z` * `created_at:=1234` * `id:<=1234` Filter by the metafield definition [`key`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-key) field. - Example: * `key:some-key` Filter by the metafield definition [`namespace`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-namespace) field. - Example: * `namespace:some-namespace` Filter by the metafield definition [`ownerType`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-ownertype) field. - Example: * `owner_type:PRODUCT` Filter by the metafield definition [`type`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition#field-type) field. - Example: * `type:single_line_text_field` Filter by the date and time when the metafield definition was last updated. Example: * `updated_at:>2020-10-21T23:39:20Z` * `updated_at: { 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-01/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-01/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) ##### GQL ```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-01/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; } ``` ##### 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 } }`, }); ``` ##### 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) ``` ## Response JSON ```json { "productByHandle": null } ```