--- title: Global IDs in Shopify APIs description: >- Learn how global IDs work in Shopify APIs and how to retrieve global IDs for different objects. source_url: html: 'https://shopify.dev/docs/api/usage/gids' md: 'https://shopify.dev/docs/api/usage/gids.md' --- # Global IDs in Shopify APIs Shopify's GraphQL APIs use global IDs to refer to objects. A global ID is an application-wide uniform resource identifier (URI) that uniquely identifies an object. You can use a global ID to retrieve a specific Shopify object of any type. *** ## How it works To enable GraphQL clients to neatly handle caching and data refetching, GraphQL servers expose object identifiers in a standardized way using the [Relay specification](https://relay.dev/graphql/objectidentification.htm). Relay asks for a compliant server to expose a standard mechanism for fetching any object given an ID. These objects are referred as `nodes` and they implement the [`Node` interface](https://relay.dev/graphql/objectidentification.htm#sec-Node-Interface). Shopify's GraphQL APIs provide a [versionable](https://shopify.dev/docs/api/usage/versioning) implementation of this interface. ### Global ID structure Shopify uses [GlobalID](https://github.com/rails/globalid) to encode global IDs. By default, when implementing a `Node` interface, a type's `id` field constructs a global ID with the following structure: ## Global ID structure ```text gid://shopify/{object_name}/{id} ``` For example, a [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) object with the ID `123` would resolve to the following global ID: ## Global ID of a Product object ```text gid://shopify/Product/123 ``` ### Parameterized global IDs Some objects are more complex and have global IDs that contain parameters. A global ID with parameters has the following structure: ## Parameterized global ID structure ```text gid://shopify/{child_object_name}/{child_object_id}?{parent_object_name}_id={parent_object_id} ``` For example, the [`InventoryLevel`](https://shopify.dev/docs/api/admin-graphql/latest/objects/InventoryLevel) object is associated with the [`InventoryItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/InventoryItem) object. If the `InventoryLevel` object's ID is `123` and the `InventoryItem` object's ID is `456`, then the global ID would resolve to the following structure: ## Parameterized global ID for InventoryLevel object ```text gid://shopify/InventoryLevel/123?inventory_item_id=456 ``` *** ## Global ID examples The following table provides some common examples of global IDs that are associated with different GraphQL objects. For example purposes, each global ID is referenced as `123`. | GraphQL object | Example global ID | Description | | - | - | - | | `Article` | `gid://shopify/Article/123` | A globally unique identifier of an article. | | `Blog` | `gid://shopify/Blog/123` | A globally unique identifier of a blog. | | `Collection` | `gid://shopify/Collection/123` | A globally unique identifier of a collection. | | `Customer` | `gid://shopify/Customer/123` | A globally unique identifier of a customer. | | `DeliveryCarrierService` | `gid://shopify/DeliveryCarrierService/123` | A globally unique identifier of a delivery carrier service. | | `DeliveryLocationGroup` | `gid://shopify/DeliveryLocationGroup/123` | A globally unique identifier of a delivery location group. | | `DeliveryProfile` | `gid://shopify/DeliveryProfile/123` | A globally unique identifier of a delivery profile, an object that enables shops to create shipping rates for each product variant and location. | | `DeliveryZone` | `gid://shopify/DeliveryZone/123` | A globally unique identifier of a delivery zone. | | `DraftOrder` | `gid://shopify/DraftOrder/123` | A globally unique identifier of a draft order. | | `DraftOrderLineItem` | `gid://shopify/DraftOrderLineItem/123` | A globally unique identifier of a line item in a draft order. | | `Duty` | `gid://shopify/Duty/123` | A globally unique identifier of duties on an order. | | `EmailTemplate` | `gid://shopify/EmailTemplate/123` | A globally unique identifier of an email notification template that's associated with a Shopify store. | | `Fulfillment` | `gid://shopify/Fulfillment/123` | A globally unique identifier of a fulfillment. | | `FulfillmentEvent` | `gid://shopify/FulfillmentEvent/123` | A globally unique identifier of a fulfillment event. | | `FulfillmentService` | `gid://shopify/FulfillmentService/123` | A globally unique identifier of a fulfillment service. | | `InventoryItem` | `gid://shopify/InventoryItem/123` | A globally unique identifier of an inventory item, an object that represents a physical good. | | `InventoryLevel` | `gid://shopify/InventoryLevel/123?inventory_item_id=456` | A globally unique identifier of an inventory level, an object that represents the quantities of an inventory item for a location. | | `LineItem` | `gid://shopify/LineItem/123` | A globally unique identifier of a line item. | | `Location` | `gid://shopify/Location/123` | A globally unique identifier of a location, an object that represents a geographical location where your stores, pop-up stores, headquarters, and warehouses exist. | | `MarketingEvent` | `gid://shopify/MarketingEvent/123` | A globally unique identifer of a marketing event, an object that represents actions taken by your app, on behalf of the app user, to market products, collections, discounts, pages, blog posts, and other features. | | `MediaImage` | `gid://shopify/MediaImage/123` | A globally unique identifier of a Shopify-hosted image. | | `Metafield` | `gid://shopify/Metafield/123` | A globally unique identifier of a metafield, an object that provides a flexible way to attach additional information to a Shopify object. | | `Order` | `gid://shopify/Order/123` | A globally unique identifier of an order. | | `OrderTransaction` | `gid://shopify/OrderTransaction/123` | A globally unique identifier of an order transaction. | | `Page` | `gid://shopify/Page/123` | A globally unique identifier of a page. | | `PointOfSaleDevice` | `gid://shopify/PointOfSaleDevice/123` | A globally unique identifier of a Point of Sale Device. | | `Product` | `gid://shopify/Product/123` | A globally unique identifier of a product. | | `ProductImage` | `gid://shopify/ProductImage/123` | A globally unique identifier of a product image. | | `ProductVariant` | `gid://shopify/ProductVariant/123` | A globally unique identifier of a product variant. | | `Refund` | `gid://shopify/Refund/123` | A globally unique identifier of a refund. | | `Shop` | `gid://shopify/Shop/123` | A globally unique identifier of a Shopify store. | | `StaffMember` | `gid://shopify/StaffMember/123` | A globally unique identifier of a staff member in a Shopify store. | | `Theme` | `gid://shopify/Theme/123` | A globally unique identifier of a Shopify theme. | *** ## Querying global IDs A `node` is an object that has a global ID and is of a type that's defined by the schema. Connections retrieve a list of nodes. For example, the `products` connection finds all the `Product` type nodes connected to the query root. The following example shows how to use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) to query the global IDs of the first 5 products in your store: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql { products(first:5) { edges { node { id } } } } ``` ## JSON response ```json { "data": { "products": { "edges": [ { "node": { "id": "gid://shopify/Product/1" } }, { "node": { "id": "gid://shopify/Product/2" } }, { "node": { "id": "gid://shopify/Product/3" } }, { "node": { "id": "gid://shopify/Product/4" } }, { "node": { "id": "gid://shopify/Product/5" } } ] } } } ``` ### Retrieving global IDs through the UI Some global IDs can be quickly retrieved through the user interface (UI). For example, you can find a product's global ID from your Shopify admin by clicking **Products** and clicking a specific product. The URL of the page contains the product's global ID: ## Page URL containing the global ID of a product ```text https://admin.shopify.com/store/{shop}/products/{id} ``` *** ## Using global IDs in mutations Many mutations in Shopify's GraphQL APIs require an `id` input field. The value of the `id` field needs to be constructed as a global ID. The following example shows how to use an `id` input field to update a product's status: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql mutation { productUpdate(input: {id: "gid://shopify/Product/3", title: "Burton Custom Freestyle 151", status: "ARCHIVED"} ) { product { id status } } } ``` ## JSON response ```json { "data": { "productUpdate": { "product": { "id": "gid://shopify/Product/3", "status": "ARCHIVED" } } } } ``` *** ## Finding equivalent IDs between REST and Graph​QL Most REST Admin API resources include an `admin_graphql_api_id` property, which provides a global ID for the equivalent object in the GraphQL Admin API. For example, the following two properties on the [`Customer`](https://shopify.dev/docs/api/admin-rest/latest/resources/customer) resource are equivalent: ## Customer resource ```json { "id": 123456789, // A simple ID for a Customer resource in the REST Admin API "admin_graphql_api_id": "gid://shopify/Customer/123456789" // A global ID for the equivalent Customer object in the GraphQL Admin API } ``` Similarly, most GraphQL Admin API objects include a `legacyResourceId` field, which provides a simple ID for the equivalent resource in the REST Admin API. For example, the following two fields on the [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product#field-product-legacyresourceid) object are equivalent: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql { products(first:5) { edges { node { id # A global ID for the Product object in the GraphQL Admin API legacyResourceId # A simple ID for the equivalent Product resource in the REST Admin API } } } } ``` ## JSON response ```json { "data": { "products": { "edges": [ { "node": { "id": "gid://shopify/Product/4353554645014", "legacyResourceId": "4353554645014" } }, { "node": { "id": "gid://shopify/Product/4353554710550", "legacyResourceId": "4353554710550" } }, { "node": { "id": "gid://shopify/Product/4358159007766", "legacyResourceId": "4358159007766" } }, { "node": { "id": "gid://shopify/Product/5591484858390", "legacyResourceId": "5591484858390" } }, { "node": { "id": "gid://shopify/Product/5591485448214", "legacyResourceId": "5591485448214" } } ] } } } ``` ***