---
title: GraphQL queries
description: Learn about GraphQL queries and follow some examples for retrieving data.
source_url:
  html: 'https://shopify.dev/docs/apps/build/graphql/basics/queries'
  md: 'https://shopify.dev/docs/apps/build/graphql/basics/queries.md'
---

ExpandOn this page

* [How to use these examples](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#how-to-use-these-examples)
* [Query​Root](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#queryroot)
* [Fields](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#fields)
* [Connections](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#connections)
* [Filtering connections using a search query](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#filtering-connections-using-a-search-query)
* [Next steps](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#next-steps)

# GraphQL queries

Note

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](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) or [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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.

***

## How to use these examples

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

Shopify [provides a read-only demo store](https://shopify.dev/docs/api/usage/api-exploration/admin-graphiql-explorer#execute-queries-on-a-demo-store) which can be used to execute queries without needing to connect to a development store. You have access to the demo store via a [GraphQL Explorer interface](https://shopify.dev/docs/graphiql/admin-graphiql) where you can execute the queries on the left pane of that view. [Open the Explorer](https://shopify.dev/docs/graphiql/admin-graphiql) in a new tab or window, then paste the example query in the left pane to view the results.

In the code snippets below, take a look at the `Demo store query` tabs for queries you can run.

***

## Query​Root

The [`QueryRoot`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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.

Note

You don't need to reference the `QueryRoot` object in your query.

### Example

The following diagram illustrates example relationships between objects that are retrieved in an query:

![The relationships between the objects retrieved in the query.](https://shopify.dev/assets/assets/images/api/usage/graphql-basics/nodes-BMSxYiGC.png)

The query requests the [`Shop`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Shop) object, data from a few fields, the child [`ShopAddress`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopAddress) object, and the `products` [connection](#connections). 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:

## QueryRoot: POST https\://{shop}.myshopify.com/api/2025-10/graphql.json

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

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

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

##### Demo store query

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

##### GraphQL app query

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

##### cURL with token

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

## Response

JSON

```json
{
  "data": {
    "shop": {
      "id": "gid://shopify/Shop/17681717",
      "name": "example",
      "email": "john@example.com",
      "billingAddress": {
        "id": "gid://shopify/ShopAddress/20516601878",
        "address1": "151 O'Connor St"
      }
    },
    "products": {
      "nodes": [
        {
          "id": "gid://shopify/Product/108828309",
          "title": "Draft"
        },
        {
          "id": "gid://shopify/Product/121709582",
          "title": "Boots"
        }
      ]
    }
  }
}
```

***

## Fields

A field is unit of data associated with an object or type. For example, in the GraphQL Admin API's [`QueryRoot`](https://shopify.dev/docs/api/admin-graphql/latest/objects/queryroot) object, the [`customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/queryroot#field-queryroot-customer) field queries a single customer, and returns a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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.

### Example

The following query retrieves a specific customer, and selects a few fields from the [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) object:

## Fields: POST https\://{shop}.myshopify.com/api/2025-10/graphql.json

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

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

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

##### Demo store query

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

##### GraphQL app query

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

##### cURL with token

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

## Response

JSON

```json
{
  "data": {
    "customer": {
      "displayName": "Beatrice Alighieri",
      "phone": "+12345678912"
    }
  }
}
```

Tip

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](https://shopify.dev/docs/apps/build/graphql/migrate/learn-how#translating-ids-from-rest-to-graphql).

***

## Connections

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](https://shopify.dev/docs/api/usage/limits#rate-limits) and [pagination](https://shopify.dev/docs/api/usage/pagination-graphql).

You can access the nodes in a connection in the following ways:

* **`edges`**: `customers { edges { node { ... } } }`
* **`nodes`**: `customers { nodes { ... } }`

Tip

`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](https://shopify.dev/docs/api/usage/pagination-graphql#connection-edges).

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](https://shopify.dev/docs/api/usage/pagination-graphql).

### Example

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:

![You can query the edges of the product connection to access product objects.](https://shopify.dev/assets/assets/images/api/usage/graphql-basics/connections-CvtuKflp.png)

The example requests the `products` connection, and asks for the first three products. Because the [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) object has a [`variants`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product#connection-product-variants) connection, the same pattern is used to get information on the first three variants for the original products:

#### Using nodes

## Connections using nodes: POST https\://{shop}.myshopify.com/api/2025-10/graphql.json

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

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

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

##### Demo store query

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

##### GraphQL app query

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

##### cURL with token

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

## Response

JSON

```json
{
  "data": {
    "products": {
      "nodes": [
        {
          "id": "gid://shopify/Product/1321540321336",
          "handle": "ocean-blue-shirt",
          "variants": {
            "nodes": [
              {
                "id": "gid://shopify/ProductVariant/12195005104184",
                "displayName": "Ocean Blue Shirt - xs"
              }
            ]
          }
        }
      ]
    }
  }
}
```

#### Using edges

## Connections using edges: POST https\://{shop}.myshopify.com/api/2025-10/graphql.json

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

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

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

##### Demo store query

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

##### GraphQL app query

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

##### cURL with token

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

## Response

JSON

```json
{
  "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.

***

## Filtering 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](https://shopify.dev/docs/api/usage/search-syntax).

The following query retrieves the first two orders that are fulfilled:

## Using query: POST https\://{shop}.myshopify.com/api/2025-10/graphql.json

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

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

```bash
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
        }
    }
  }"
}
```

##### Demo store query

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

##### GraphQL app query

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

##### cURL with token

```
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
        }
    }
  }"
}
```

## Response

JSON

```json
{
  "data": {
    "orders": {
      "nodes": [
        {
          "id": "gid://shopify/Order/410479493176",
          "name": "#1592",
          "displayFulfillmentStatus": "FULFILLED"
        },
        {
          "id": "gid://shopify/Order/410478542904",
          "name": "#1564",
          "displayFulfillmentStatus": "FULFILLED"
        }
      ]
    }
  }
}
```

***

## Next steps

Learn how to create and modify data with [mutations](https://shopify.dev/docs/apps/build/graphql/basics/mutations).

***

* [How to use these examples](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#how-to-use-these-examples)
* [Query​Root](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#queryroot)
* [Fields](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#fields)
* [Connections](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#connections)
* [Filtering connections using a search query](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#filtering-connections-using-a-search-query)
* [Next steps](https://shopify.dev/docs/apps/build/graphql/basics/queries.md#next-steps)