Build your First GraphQL Query

Learn how to build a Square GraphQL query using GraphQL Explorer and the schema documentation.

Square GraphQL provides read access to data in supported Square graphs. When querying with GraphQL, you specify the exact data that you want Square to return.

The following steps use Square GraphQL Explorer to create a query that gets open orders and information about the customer associated with each order. As you write the query, you learn how to browse the schema to find available fields, type information, and valid query syntax.

To query for data using Square GraphQL, you need a Square account. If you don't already have one, you can sign up and create a free account in minutes.

To get query results, you need at least one order in your account. You also need to associate a customer with the order if you want to see customer data in the results.

1. Sign in to GraphQL Explorer using your Square account. If the Documentation Explorer pane isn't showing, choose the Docs button to open it.

2. Choose Add access token and select an access token. The token is automatically added to the Request Headers pane and used to authorize your query.

3. Get your merchant ID, which is required for most queries. Remove any existing content from the query pane and enter the following query:

   {
     currentMerchant {
       id
     }
   }

4. Choose Run request. Copy the returned id to use in a later step.

   Note that the currentMerchant entry point provides quick access to the id of the merchant associated with the access token, as well as other properties such as businessName, currency, and locations.

1. In Documentation Explorer, choose the Query root type to see available entry points. For this exercise, choose orders.

   You can see that the orders entry point is an OrderConnection object that accepts several arguments.

   

2. In the query pane, start writing your query. Remove any existing content and enter the following snippet, which uses OpenOrders as the optional operation name:

   query OpenOrders {
     orders(
       # query arguments go here
     ) {
       # requested fields go here
     }
   }

   The example query you're building only includes orders, but queries can contain multiple entry points.

   Did you know?

   In the query pane, you can hover over the orders field to open a code hint that provides a short description of the field with links to relevant schema documentation. The query pane also provides code completion and syntax validation to help you write queries.

This example query filters orders by merchant ID and the OPEN state.

1. In Documentation Explorer, choose the OrderFilter type for the filter argument. Scroll down to the merchantId and state filters.

   

2. Navigate through the components that make up the merchantId and state filters to find the required syntax.

   • merchantId uses the following syntax:

     merchantId: { equalToAnyOf: [ID!] }

   • state uses the following syntax:

     state: { equalToAnyOf: [OrderState!] }

   The following snippet shows the filter syntax for the example query:

   filter: {
     merchantId: {
       equalToAnyOf: [ID!]
     }
     state: {
       equalToAnyOf: [OrderState!]
     }
   }

3. Add the snippet to your query. In the query pane, replace # query arguments go here with the filter argument. Then, replace the merchantId value with your merchant ID and the state value with OPEN.

   Your query should look like the following example, where YOUR_MERCHANT_ID is your merchant ID. You can ignore any mismatched indentation.

   query OpenOrders {
     orders( 
       filter: {
         merchantId: {
           equalToAnyOf: ["YOUR_MERCHANT_ID"]
         }
         state: {
           equalToAnyOf: [OPEN]
         }
       }
     ) {
       # requested fields go here
     }
   }

   The filter argument is now complete. The next part of the query specifies the order and customer data you want to retrieve.

Queries must explicitly specify the fields to retrieve. This example query gets information about the order and the customer associated with the order. In the following steps, you navigate through the schema to find fields to add to the query:

1. In Documentation Explorer, return to orders and choose the OrderConnection type. Note that the nodes field is an array of Order objects.

2. Choose the Order type to see the available order fields. For this query, you want to retrieve the id, createdAt, and customer fields for the order. Note that the customer field is a Customer object.

   

3. Choose the Customer type to see the available customer fields. For this query, you want to retrieve the familyName, phoneNumber, and address fields for the customer associated with the order. Note that the address field is an Address object.

4. Choose Address to see the available address fields. For this query, you just want to retrieve the postalCode field of the customer's address.

   The following snippet represents the hierarchical list of fields you want to retrieve, starting with the nodes field:

   nodes {
     id
     createdAt
     customer {
       familyName
       phoneNumber
       address {
         postalCode
       }
     }
   }

5. Add the snippet to your query. In the query pane, replace # requested fields go here with the fields you want to retrieve. Your query should look like the following example:

   query OpenOrders {
     orders( 
       filter: {
         merchantId: {
           equalToAnyOf: ["YOUR_MERCHANT_ID"]
         }
         state: {
           equalToAnyOf: [OPEN]
         }
       }
     ) {
       nodes {
         id
         createdAt
         customer {
           familyName
           phoneNumber
           address {
             postalCode
           }
         }
       }
     }
   }

Choose Run request. The following is an excerpt of an example response:

{
  "data": {
    "orders": {
      "nodes": [
        {
          "id": "o9r5HI1rP4DNu2zZfElQTio8uaB",
          "createdAt": "2023-06-08T06:54:26.332Z",
          "customer": {
            "familyName": "Singhal",
            "phoneNumber": "12065551012",
            "address": {
              "postalCode": "98121"
            }
          }
        },
        {
          "id": "6STgq2h0v1K6smkASQP7kdVuuaB",
          "createdAt": "2023-06-08T06:05:42.874Z",
          "customer": {
            "familyName": "Castillo",
            "phoneNumber": "629-555-9284",
            "address": null
          }
        },
        {
          "id": "CkmasoR7ZXSRG969A0ZEuMMlvaB",
          "createdAt": "2023-06-07T20:50:00.136Z",
          "customer": {
            "familyName": "Nguyen",
            "phoneNumber": "6095553220",
            "address": {
              "postalCode": "08009"
            }
          }
        },
        {
          "id": "QBRic2WOSImQjSFwJMaJsDkCuaB",
          "createdAt": "2023-06-07T18:45:24.973Z",
          "customer": {
            "familyName": "Cohen",
            "phoneNumber": "+12065554871",
            "address": {
              "postalCode": "98101"
            }
          }
        },
        ...
      ]
    }
  }
}

Keep in mind that each tender (payment) for an order might also have an associated customer. The customer associated with the payment might not be the same one that is associated with the order.

• Learn how to use variables to make your queries easier to reuse. For example, instead of specifying the merchant ID directly in the query, you can use a variable in the query and pass in the merchant ID separately.

• Learn how to use pagination to retrieve paged responses.

• Experiment with the sample queries available in GraphQL Explorer. For information about using GraphQL Explorer, see GraphQL Explorer.

• Run example queries using the Square and GraphQL - Code Example (Node.js) sample application.

• See Square GraphQL in action in the Square Dev GraphQL and PKCE Example Application (React Native) sample application that lets owners monitor orders and employee information at different locations.