Skip to main content

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.


To enable GraphQL clients to neatly handle caching and data refetching, GraphQL servers expose object identifiers in a standardized way using the Relay specification.

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. Shopify's GraphQL APIs provide a versionable implementation of this interface.

Shopify uses 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

gid://shopify/{object_name}/{id}

For example, a Product object with the ID 123 would resolve to the following global ID:

Global ID of a Product object

gid://shopify/Product/123

Anchor to Parameterized global IDsParameterized 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


For example, the InventoryLevel object is associated with the 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



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 objectExample global IDDescription
Articlegid://shopify/Article/123A globally unique identifier of an article.
Bloggid://shopify/Blog/123A globally unique identifier of a blog.
Collectiongid://shopify/Collection/123A globally unique identifier of a collection.
Customergid://shopify/Customer/123A globally unique identifier of a customer.
DeliveryCarrierServicegid://shopify/DeliveryCarrierService/123A globally unique identifier of a delivery carrier service.
DeliveryLocationGroupgid://shopify/DeliveryLocationGroup/123A globally unique identifier of a delivery location group.
DeliveryProfilegid://shopify/DeliveryProfile/123A globally unique identifier of a delivery profile, an object that enables shops to create shipping rates for each product variant and location.
DeliveryZonegid://shopify/DeliveryZone/123A globally unique identifier of a delivery zone.
DraftOrdergid://shopify/DraftOrder/123A globally unique identifier of a draft order.
DraftOrderLineItemgid://shopify/DraftOrderLineItem/123A globally unique identifier of a line item in a draft order.
Dutygid://shopify/Duty/123A globally unique identifier of duties on an order.
EmailTemplategid://shopify/EmailTemplate/123A globally unique identifier of an email notification template that's associated with a Shopify store.
Fulfillmentgid://shopify/Fulfillment/123A globally unique identifier of a fulfillment.
FulfillmentEventgid://shopify/FulfillmentEvent/123A globally unique identifier of a fulfillment event.
FulfillmentServicegid://shopify/FulfillmentService/123A globally unique identifier of a fulfillment service.
InventoryItemgid://shopify/InventoryItem/123A globally unique identifier of an inventory item, an object that represents a physical good.
InventoryLevelgid://shopify/InventoryLevel/123?inventory_item_id=456A globally unique identifier of an inventory level, an object that represents the quantities of an inventory item for a location.
LineItemgid://shopify/LineItem/123A globally unique identifier of a line item.
Locationgid://shopify/Location/123A globally unique identifier of a location, an object that represents a geographical location where your stores, pop-up stores, headquarters, and warehouses exist.
MarketingEventgid://shopify/MarketingEvent/123A 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.
MediaImagegid://shopify/MediaImage/123A globally unique identifier of a Shopify-hosted image.
Metafieldgid://shopify/Metafield/123A globally unique identifier of a metafield, an object that provides a flexible way to attach additional information to a Shopify object.
Ordergid://shopify/Order/123A globally unique identifier of an order.
OrderTransactiongid://shopify/OrderTransaction/123A globally unique identifier of an order transaction.
Pagegid://shopify/Page/123A globally unique identifier of a page.
Productgid://shopify/Product/123A globally unique identifier of a product.
ProductImagegid://shopify/ProductImage/123A globally unique identifier of a product image.
ProductVariantgid://shopify/ProductVariant/123A globally unique identifier of a product variant.
Refundgid://shopify/Refund/123A globally unique identifier of a refund.
Shopgid://shopify/Shop/123A globally unique identifier of a Shopify store.
StaffMembergid://shopify/StaffMember/123A globally unique identifier of a staff member in a Shopify store.
Themegid://shopify/Theme/123A globally unique identifier of a Shopify theme.

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 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

{
products(first:5) {
edges {
node {
id
}
}
}
}

JSON response

{
"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"
}
}
]
}
}
}

Anchor to Retrieving global IDs through the UIRetrieving 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

https://admin.shopify.com/store/{shop}/products/{id}

Anchor to Using global IDs in mutationsUsing 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

mutation {
productUpdate(input: {id: "gid://shopify/Product/3", title: "Burton Custom Freestyle 151", status: "ARCHIVED"} ) {
product {
id
status
}
}
}

JSON response

{
"data": {
"productUpdate": {
"product": {
"id": "gid://shopify/Product/3",
"status": "ARCHIVED"
}
}
}
}

Anchor to Finding equivalent IDs between REST and GraphQLFinding equivalent IDs between REST and GraphQL

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 resource are equivalent:

Customer resource

{
"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 object are equivalent:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
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

{
"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"
}
}
]
}
}
}

Was this page helpful?