GraphQL queries
The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.
The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.
GraphQL queries retrieve data from a server, similar to a GET request for a REST API. However, unlike REST, GraphQL queries are sent to a single endpoint and use the POST HTTP method.
A GraphQL API models data as nodes that are connected by edges. A node is an object that has a global ID, such as the Order or Product objects. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.
Anchor to QueryRootQuery
The QueryRoot object is the initial entry point for all queries in the GraphQL API. Everything that can be queried is defined as a field or connection on the QueryRoot object.
To learn about what data you can query, refer to the QueryRoot object in the relevant API's reference.
You don't need to reference the QueryRoot object in your query.
Anchor to ExampleExample
The following diagram illustrates example relationships between objects that are retrieved in an query:
The query requests the Shop object, data from a few fields, the child ShopAddress object, and the products connection. The following is the single request structure to retrieve this data. In the response, the structure of the data object mirrors the query's shape:
POST /admin/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to FieldsFields
A field is unit of data associated with an object or type. For example, in the GraphQL Admin API's QueryRoot object, the customer field queries a single customer, and returns a Customer object.
An argument is a set of key-value pairs attached to a field, providing a parameterized input to the field that influences the returned data or an operation's behavior. For example, the customer field requires the id argument, which specifies the customer to query. After selecting the customer field and providing an ID, you list the fields on the Customer object that you want to return.
To learn about what data you can query, refer the object's fields in the relevant API's reference.
Anchor to ExampleExample
The following query retrieves a specific customer, and selects a few fields from the Customer object:
POST /admin/api/{api_version}/graphql.json
GraphQL query
JSON response
On many endpoints, the REST Admin API returns the admin_graphql_api_id property, which you can use to query that specific object in the GraphQL Admin API. Learn more.
Anchor to ConnectionsConnections
Connections in GraphQL represent relationships between associated types. Nodes are elements within connections. You can traverse connections to perform nested queries, retrieving data from multiple nodes in a single GraphQL query. If you're selecting something with a pluralized name, then you're likely using a connection.
When you select a connection, you must pass a first or last argument to limit the number of nodes that are returned. This is a key component to manage rate-limiting and pagination.
You can access the nodes in a connection in the following ways:
edges:customers { edges { node { ... } } }nodes:customers { nodes { ... } }
nodes is shorthand for edges { node ... and is appropriate for most queries. To retrieve information that's specific to the connection between a node and its parent, you might want to use edges. Learn more.
Regardless of the syntax that you use, the return is an array of objects of the same type. For example, when you query a product's variants, an array of Variant objects is returned.
Similar to when you query an individual node, list the fields to return. The response returns that data for those fields for each node in the connection. If a connection contains fewer objects than requested, then the response contains all the data that's available.
If you want to retrieve the next batch of objects, or you need to retrieve more than the maximum number of objects, then you can paginate the objects using cursor-based pagination.
Anchor to ExampleExample
The following diagram illustrates example relationships between GraphQL types in a connection, including the connection, its constituent edges and nodes, and the associated objects and fields:
The example requests the products connection, and asks for the first three products. Because the Product object has a variants connection, the same pattern is used to get information on the first three variants for the original products:
POST /admin/api/{api_version}/graphql.json
GraphQL query
query {
products(first:3) {
nodes {
id
handle
variants(first:3) {
nodes {
id
displayName
}
}
}
}
}query {
products(first:3) {
edges {
node {
id
handle
variants(first:3) {
edges {
node {
id
displayName
}
}
}
}
}
}
}JSON response
{
"data": {
"products": {
"nodes": [
{
"id": "gid://shopify/Product/1321540321336",
"handle": "ocean-blue-shirt",
"variants": {
"nodes": [
{
"id": "gid://shopify/ProductVariant/12195005104184",
"displayName": "Ocean Blue Shirt - xs"
}
]
}
}
]
}
}
}{
"data": {
"products": {
"edges": [
{
"node": {
"id": "gid://shopify/Product/1321540321336",
"handle": "ocean-blue-shirt",
"variants": {
"edges": [
{
"node": {
"id": "gid://shopify/ProductVariant/12195005104184",
"displayName": "Ocean Blue Shirt - xs"
}
}
]
}
}
}
]
}
}
}In the response, only one set of data is returned because the store only has a single product and variant.
Anchor to Filtering connections using a search queryFiltering connections using a search query
You can filter connections with query argument, to return only the nodes that match a search query.
To learn which fields you can filter a connection by, refer to the API documentation for the connection's query argument. To learn how to format a search query, refer to Search syntax.
The following query retrieves the first two orders that are fulfilled:
POST /admin/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Next stepsNext steps
Learn how to create and modify data with mutations.