GraphQL queries

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 How to use these examplesHow to use these examples

If you want to use the examples below on Shopify, you have a few options to perform queries:

Anchor to QueryRootQueryRoot

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.

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:

query {
  shop {
    id
    name
    email
    billingAddress {
      id
      address1
    }
  }
  products(first:2) {
    nodes {
      id
      title
    }
  }
}

query {
  shop {
    id
    name
    email
    billingAddress {
      id
      address1
    }
  }
  products(first:2) {
    nodes {
      id
      title
    }
  }
}

SHOP_TOKEN="ACCESS_TOKEN"
SHOP_SUBDOMAIN="shop"

curl -sX POST \
  https://${SHOP_SUBDOMAIN}.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H "X-Shopify-Access-Token: ${SHOP_TOKEN}" \
  -d @- <<EOF
{
  "query": "{
    shop {
        id
        name
        email
        billingAddress {
            id
            address1
        }
    }
    products(first:2) {
        nodes {
            id
            title
        }
    }
  }"
}
EOF

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:

query {
  customer(id: "gid://shopify/Customer/6581271756") {
    displayName
    phone
  }
}

query {
  customer(id: "gid://shopify/Customer/6581271756") {
    displayName
    phone
  }
}

SHOP_TOKEN="ACCESS_TOKEN"
SHOP_SUBDOMAIN="shop"

curl -sX POST \
  https://${SHOP_SUBDOMAIN}.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H "X-Shopify-Access-Token: ${SHOP_TOKEN}" \
  -d @- <<EOF
{
  "query": "{
    customer(id: \"gid://shopify/Customer/6581271756\") {
        displayName
        phone
    }
  }"
}
EOF

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 { ... } }

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:

Anchor to Using nodesUsing nodes

query {
  products(first:3) {
    nodes {
      id
      handle
      variants(first:3) {
        nodes {
          id
          displayName
        }
      }
    }
  }
}

query {
  products(first:3) {
    nodes {
      id
      handle
      variants(first:3) {
        nodes {
          id
          displayName
        }
      }
    }
  }
}

SHOP_TOKEN="ACCESS_TOKEN"
SHOP_SUBDOMAIN="shop"

curl -sX POST \
  https://${SHOP_SUBDOMAIN}.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H "X-Shopify-Access-Token: ${SHOP_TOKEN}" \
  -d @- <<EOF
{
  "query": "{
    products(first:3) {
        nodes {
          id
          handle
          variants(first:3) {
              nodes {
                id
                displayName
              }
          }
        }
    }
  }"
}
EOF

Anchor to Using edgesUsing edges

query {
  products(first:3) {
    edges {
      node {
        id
        handle
        variants(first:3) {
          edges {
            node {
              id
              displayName
            }
          }
        }
      }
    }
  }
}

query {
  products(first:3) {
    edges {
      node {
        id
        handle
        variants(first:3) {
          edges {
            node {
              id
              displayName
            }
          }
        }
      }
    }
  }
}

SHOP_TOKEN="ACCESS_TOKEN"
SHOP_SUBDOMAIN="shop"

curl -sX POST \
  https://${SHOP_SUBDOMAIN}.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H "X-Shopify-Access-Token: ${SHOP_TOKEN}" \
  -d @- <<EOF
{
  "query": "{
    products(first:3) {
        edges {
          node {
              id
              handle
              variants(first:3) {
                edges {
                    node {
                      id
                      displayName
                    }
                }
              }
          }
        }
    }
  }"
}
EOF

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:

query {
  orders(first:2, query:"fulfillment_status:shipped") {
    nodes {
      id
      name
      displayFulfillmentStatus
    }
  }
}

query {
  orders(first:2, query:"fulfillment_status:shipped") {
    nodes {
      id
      name
      displayFulfillmentStatus
    }
  }
}

SHOP_TOKEN="ACCESS_TOKEN"
SHOP_SUBDOMAIN="shop"

curl -sX POST \
  https://${SHOP_SUBDOMAIN}.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H "X-Shopify-Access-Token: ${SHOP_TOKEN}" \
  -d @- <<EOF
{
  "query": "{
    orders(first:2, query:\"fulfillment_status:shipped\") {
        nodes {
          id
          name
          displayFulfillmentStatus
        }
    }
  }"
}

Anchor to Next stepsNext steps

Learn how to create and modify data with mutations.