Build your First GraphQL Query

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'll learn how to browse the schema to find available fields, type information, and valid query syntax.

Link to section

Prerequisites

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.

Square GraphQL supports read operations only, so you need to call Square API endpoints to create a customer and an order.

After you sign in to API Explorer using your Square account, choose Try in API Explorer in the following requests to open and run them in API Explorer:

  • Optional - Create a customer if you want to see customer data in the results.

    Create customer

  • Create an order. Before sending the request, replace the placeholder values for location_id and customer_id. If you're not specifying a customer, clear the customer_id field.

    Create order

Link to section

Authorize your query

  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.

Link to section

Choose the graph to query

  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.

    A screenshot of GraphQL Explorer with the orders entry point showing in Documentation Explorer.

  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.

Link to section

Add filter query arguments

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.

    A screenshot of GraphQL Explorer with the OrderFilter input type showing in Documentation Explorer.

  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.

Link to section

Add query fields

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.

    A screenshot of GraphQL Explorer with the Order object type showing in Documentation Explorer.

  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:

Link to section

Run the query

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

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.

Link to section

Next steps

  • 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 Overview.

  • 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.

Note

The sample applications include a script you can run to upload test data to your Square account.