Sending your first GraphQL query

A GraphQL query retrieves data from a server, similar to a GET request for a REST API. However, unlike REST, all GraphQL queries and mutations are sent to a single endpoint and use the POST http method.

A GraphQL API models data as nodes connected by edges. A node is an object that has a global ID, such as an Order object or Product object. 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 data that you want to retrieve.

Post /admin/api/2019-04/graphql.json

query {
  shop {
    id
    name
    email
  }
}

JSON response

{
  "data": {
    "shop": {
      "id": "gid:\/\/shopify\/Shop\/17681717",
      "name": "johns-apparel",
      "email": "john@johns-apparel.com"
    }
  },
  ...
}

QueryRoot

At the root of every GraphQL query is the node (or nodes) that you're fetching data for. Everything that can be queried is defined as a field or connection on the QueryRoot object.

A field is a single resource or property. For example, the customer field queries a single customer. In the GraphQL Admin API reference, the customer field is defined like this:

customer (Customer)

Returns a Customer resource by ID.

id (ID!) required

The ID of the Customer to return.

The field requires the id argument to specify which customer to query. After selecting the customer field and providing an ID, you list the fields on the Customer type that you want to return.

query {
  customer(id: "gid://shopify/Customer/6581271756") {
    displayName
    phone
  }
}
{
  "data": {
    "customer": {
      "displayName": "Beatrice Alighieri",
      "phone": "+12345678912"
    }
  }
}

Notice that after the data key, the shape of the response keys reflects the shape of the query keys.

GraphQL connections

Connections query related nodes. For example, the orders connection returns a list of a shop's orders. If you're selecting something with a pluralized name, then you're often (but not always) using a connection.

When you use a connection, you include an argument to select the segment of results that you want to return, such as the first 50 results.

Similar to querying a single node, you list the fields that you want to return. The response returns that data for each node in the connection:

query {
  orders(first: 2) {
    ...
      name
    ...
  }
}
{
  "data": {
    "orders": {
      ...
        "name": "#1002"
      ...
        "name": "#1001"
      ...
    }
  }
}

Because you select a group of nodes in a connection, you need to paginate the results. To allow for pagination, the list of fields is wrapped in two extra layers: edges and node.

query {
  orders(first: 2) {
    edges {
      node {
        name
      }
    }
  }
}
{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "name": "#1002"
          }
        },
        {
          "node": {
            "name": "#1001"
          }
        }
      ]
    }
  }
}

The response above includes a single edges object, and two node objects (one for each set of results).

You can learn more about edges and pagination in Paginating results with GraphQL. For now, remember that when you use a connection, you need to include the edges and node fields.

Send your first query

You can send a query to Shopify by using cURL to send a POST request to a store's /admin/api/2019-04/graphql.json endpoint. The examples below use the customers connection to retrieve a list of customer IDs, and then use one of those IDs to query a specific customer.

Set up a development store

If you're new to building Shopify integrations, then you need to create a Shopify Partner account and create a development store. A development store is a free Shopify account that you can use to install and test your apps. To learn more, see Creating development stores.

Steps:

  1. Create a Partner account, if you don't already have one.
  2. Create a development store, or log into an existing one.
  3. Generate API credentials for a private app, and take note of the API password.
  4. Generate data for your store by using the Shopify Developer Tools app. Use the app to generate some orders, products, and customers.

Retrieve a list of customers

The example below retrieves your development store's first three customers. For each Customer node, the query returns an ID and display name. To try the query, run the cURL command from your terminal with the following subsitutions:

  • { store } — your development store's name
  • { api_password } — the API password of the private app that you created

GraphQL query

query {
  customers(first:3) {
    edges {
      node {
        id
        displayName
      }
    }
  }
}

cURL request

curl -X POST \
  https://{ store }.com/admin/api/2019-04/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: { api_password }' \
  -d ' {
      "query": "query { customers(first:3) { edges { node { id displayName } } } }"
  }'

The response should look similar to the following:

{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "displayName": "Greg Piotrowski",
            "id": "gid://shopify/Customer/5704248076"
          }
        },
        {
          "node": {
            "displayName": "Christopher Gorski",
            "id": "gid://shopify/Customer/5704248204"
          }
        },
        {
          "node": {
            "displayName": "Emily Gibson",
            "id": "gid://shopify/Customer/5704248268"
          }
        }
      ]
    }
  }
}

Retrieve a single customer

You can use a customer ID from the previous example to query for that specific customer. To try the query, run the cURL command from your terminal with the following substitutions:

  • { store } — your development store's name
  • { api_password } — the API password of your private app
  • { customer_id } — the ID of a customer from the previous example

GraphQL query

query {
  customer(id:"gid:\/\/shopify\/Customer\/5704248076") {
    id
    displayName
    phone
    acceptsMarketing
  }
}

cURL request

curl -X POST \
  https://{ store }.myshopify.com/admin/api/2019-04/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: { api_password }' \
  -d ' {
      "query": "query { customer(id:\"{ customer_id }\") { displayName phone acceptsMarketing } }"
  }'

The response should look similar to this:

{
  "data": {
    "customer": {
      "id": "gid:\/\/shopify\/Customer\/5704248076",
      "displayName": "Greg Piotrowski",
      "phone": "+17183120906",
      "acceptsMarketing": false
    }
  }
}

Next steps

  • GraphQL mutations and variables — Learn how to create and modify data using GraphQL mutations, and then send your first mutation to create a customer profile.

Sign up for a Partner account to get started.

Sign up