An overview on how to create queries using GraphQL Explorer with Square APIs.
Developer Tools

GraphQL Explorer (alpha) New

GraphQL Explorer is Square's interactive in-browser tool for writing, validating, and testing GraphQL queries for Square APIs. GraphQL Explorer provides auto-generated documentation of the available schemas. To access GraphQL Explorer, sign in to your Square developer account and access GraphQL Explorer at

You can use GraphQL Explorer to do the following:

  • Query an externally accessible GraphQL endpoint.

  • Retrieve data from any graph for a single merchant using an OAuth token (and filtering to a merchant ID).

  • Query any graphs individually, restricted only by rate and cost limiting.

Currently, you can run queries on several graphs of the Square APIs. For this alpha release, you can only query and view existing graphs.

The following APIs are supported in Square GraphQL:

  • Orders API

  • Catalog API

  • Customers API

  • Merchants API

  • Payments API

  • Refunds API

To use GraphQL Explorer, enter your query in the left pane to see live syntax and validation errors highlighted within the text.

numbered GraphQL Explorer UI

  1. Runs the query in the query pane.

  2. Shows the access codes available for the signed-in account. Select one.

  3. Lists the sample queries that can appear in the query pane.

  4. Adds highlighting and color to the query pane.

  5. The query pane, which provides syntax and schema checking.

  6. Where you enter query variables. Not currently available.

  7. Shows the access code used for the query.

  8. The results window.

  9. Shows the schema and documentation.

GraphQL Explorer provides schema documentation you can use to construct queries. The schema documentation, which is shown when you select the Docs button, shows the correct query format. You write the query in the query pane. The following example shows how to use the schema documentation to create a query.


You can also use the code hint that appears while typing in the editor for query help.

To create a simple merchant query using the schema documentation:

  1. Determine which graph you want to create a query for. This example uses the Merchant graph to create a merchant query.

    graphql1 merchant connection

  2. GraphQL Explorer uses query variables to define the merchant ID or a merchant and a location ID for the query. The variable is declared immediately after the query name and the value of the variable is specified in the Query Variables pane. Note that you do not have to use query variables; you can specify the variable value right in the query. In this example, the variable $merchantId is declared as the ID of the merchant.

    graphql2 merchant filter

  3. In the schema documentation, look at what parameters the merchant query takes. All queries require a filter parameter to specify a merchant ID or a merchant and a location ID. This example creates a filter that filters on merchant ID. The code takes the format merchants(filter: MerchantsFilter): Merchant. Define the MerchantsFilter as merchants:[].

    graphql4 merchantlocationmap

  4. Use your merchant ID as the value for the merchant filter. Place this code in the braces of the filter object.

    graphql5 merchant ID

    The completed filter looks similar to the following:

  5. The next part of the query includes the set of fields you want returned from the query. You add this part of the query immediately after the filter and before the final bracket. Look at the return type from the type of query you are creating to determine what fields are returned. For this example, use the schema to search for MerchantConnection and then under Fields, find nodes and choose Merchants.


  6. In the Fields list, add the fields that you want to retrieve. Note that some fields have additional nested fields such as the Location type for the mainLocation field.

  7. The query is ready to run. Note that in this example, the query variable $merchantId is used. You can also enter the value directly inside the query.

    The complete query is shown as follows:

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.