Square GraphQL Overview

GraphQL streamlines your application flow by letting you request exactly the data you need. GraphQL can reduce development time and improve the customer experience by making requests more efficient. With fewer, faster, and more compact data transfers, GraphQL can be especially beneficial for resource-constrained mobile applications and in modern frontend development.

The open-source GraphQL standard defines both a query language and a runtime that retrieves data using queries. A single GraphQL query can retrieve data that would require multiple Square API calls.

Square GraphQL features include:

• A standards compliant GraphQL endpoint that serves multiple Square graphs. You can send one query to retrieve exactly the data you need from multiple Square objects and graphs.
• Support for OAuth access management.
• Support for testing in the Square Sandbox environment.
• Statically typed schemas that enable developer tooling. You can view the schema documentation when you sign in to GraphQL Explorer.

Square GraphQL supports query operations only; it doesn't support mutations or subscriptions. Applications that want to use GraphQL for faster querying and need to perform write operations must use both GraphQL and Square APIs or Square SDKs.

Square GraphQL supports query operations for the following Square graphs:

A graph provides similar read access to data as the corresponding Square API, as well as access to data that crosses API boundaries. For example, an orders query can return the email address, phone number, and other attributes of the customer associated with the order.

Square provides two endpoints where you can send GraphQL queries:

• For queries in the production environment, call: https://connect.squareup.com/public/graphql
• For queries in the Sandbox test environment, call: https://connect.squareupsandbox.com/public/graphql

Unlike Square API requests, a GraphQL query specifies the exact data to return from one or more supported graphs. For example, the following simple query gets the name and email address of customers for a specified seller:

{
  customers(
    filter: {
      merchantId: { equalToAnyOf: ["<MERCHANT_ID>"] }
    }
  ) {
    nodes {
      givenName
      familyName
      emailAddress
    }
  }
}

The data object in the response contains the query results. A response can contain both data with (partial) query results and errors with any errors encountered while processing the query.

To get started with Square GraphQL:

• Build and send queries in GraphQL Explorer. Just sign in, choose your access token, and send sample queries or write your own from scratch. For a feature overview and setup steps, see GraphQL Explorer Overview.

• Explore our documentation:

  • Read about concepts, patterns, and other GraphQL basics.
  • Learn how to use the find available data and valid syntax in the schema as you build your first query in GraphQL Explorer.
  • Check out some query examples for common scenarios.

• Try our samples, which include scripts to upload test data to your Square account:

  • Run built-in queries with the Square and GraphQL - Code Example (Node.js) sample application.
  • See GraphQL used in a real-world scenario in the Square Dev GraphQL and PKCE Example Application (React Native) mobile application.

• Send queries to Square GraphQL endpoints using third-party tools, such as Postman and GraphiQL. For example, the following cURL query retrieves an order and the customer who made the order:

  curl https://connect.squareupsandbox.com/public/graphql \
    -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{ 
      "query": "{ orders( filter: { id: { equalToAnyOf: [\"<ORDER_ID>\"]} merchantId: { equalToAnyOf: [\"<MERCHANT_ID>\"]}}) { nodes { state updatedAt customer { id emailAddress }}}}"
    }'

Most queries require that you filter by a merchant ID. If you need to get the merchant ID, query currentMerchant for the id field.

{
  currentMerchant {
    id
  }
}

GraphQL queries must provide a bearer access token in the Authorization header, just like Square API requests. The access token determines the data that you have permissions to view.

• A personal access token grants full access to the data in your Square account. If you query using a personal access token, make sure to use one that's valid for the target Sandbox or production environment.

• An OAuth access token grants granular access based on a set of permissions. If you query using an OAuth access token, the results are scoped to the permissions you requested and were granted. For example, if an orders query includes fields for the customer associated with the order, you need both ORDERS_READ and CUSTOMERS_READ permissions to get full results. For more information about the OAuth flow, see OAuth API Overview.

  Fields that you're not permitted to view are set to null in the results. In addition, the response contains an errors list with one or more SCOPE_MISSING errors. The error message provides related information, such as the missing OAuth scope.

If you're using GraphQL Explorer, the access token for the query is provided in the Request Headers pane. When signed in with your Square account, you can use the Add access token button to select a personal access token that grants full access to all data in your Square account. To test a specific set of permissions, you can paste an OAuth access token into the Request Headers pane.

Rate limits are intended to enforce reasonable API usage. Square uses a calculated query cost method for rate limiting based on the following limits:

• Applications can send a maximum of 10 queries per second (10 QPS).

• A query can have a maximum depth of 10. Query depth is the number of nested levels of the query fields.

• A query can have a maximum complexity score of 250 points.

  The 250 maximum complexity score combined with the 10 QPS limit results in an implicit limit of 2500 complexity points consumed per second. Queries that exceed the maximum complexity score return a COMPLEXITY_MAX_REACHED error.

{
  "Authorization": "Bearer <ACCESS_TOKEN>",
  "x-graphql-include-debug": 1
}

{
  "data": {
    ...
  },
  "extensions": {
    "requestId": "NWPefYffJdBEA",
    "complexityScore": 24
  }
}

You should be aware of the following limitations when working with Square GraphQL:

• Square GraphQL supports query operations only; it doesn't support mutation or subscription operations. Applications that need to perform both read and write operations must also call Square APIs directly or use Square SDKs. Note that Square SDKs cannot be used to send GraphQL queries.

• Not all Square APIs have corresponding GraphQL support. Supported graphs generally provide access to the same data as the corresponding Square APIs, as well as expanded direct access to referenced objects that cross API boundaries. However, graphs aren't always at parity with corresponding Square APIs. For example:

  • Deprecated fields might not be available.
  • Compared to corresponding list or search endpoints, GraphQL might provide more or fewer filters.
  • You cannot retrieve custom attributes associated with merchants, locations, orders, or customers using GraphQL queries. Only catalog custom attributes are supported.

  Although Square graphs are continually updated to reflect the latest version of the corresponding Square APIs, there might be exceptions. You should use the current schema as the source of truth for GraphQL support. You can view the schema in GraphQL Explorer or by using the introspection system, as shown in the following simple introspection query:

  {
    __schema {
      types {
        name
        description
        kind
      }
    }
  }

  For more information, see Introspection at graphql.org.

• Rate limits are applied to Square GraphQL queries.

• The API Logs feature in the Developer Dashboard doesn't include GraphQL queries.

Tag your feedback, issues, and questions with graphql-api and post them on the Square Developer forums or email [email protected].

The Square GraphQL schema generally reflects the latest version of the corresponding Square APIs. The following are backward-incompatible changes to the schema that might require updates to your application code:

query MerchantsQuery {
  merchants(
    filter: {
      merchants: [ "<MERCHANT_ID>" ]
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

query MerchantsQuery {
  merchants(
    filter: {
      id: { 
        equalToAnyOf: [ "<MERCHANT_ID>" ]
      }
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

query CatalogObjectsQuery {
  catalog(
    merchantId: { 
      equalToAnyOf: [ "<MERCHANT_ID>" ]
    }
    all {     
      filter: {
        id: { 
          equalToAnyOf: [ "<CATALOG_OBJECT_ID>" ]
        }
      }
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

query CatalogObjectsQuery {
  catalog(
    filter: {
      merchantId: { 
        equalToAnyOf: [ "<MERCHANT_ID>" ]
      }
      id: { 
        equalToAnyOf: [ "<CATALOG_OBJECT_ID>" ]
      }
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

query CatalogItemsQuery {
  catalog(
    merchantId: { 
      equalToAnyOf: [ "<MERCHANT_ID>" ]
    }
    items {     
      filter: {
        id: { 
          equalToAnyOf: [ "<CATALOG_ITEM_ID>" ]
        }
      }
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

query CatalogItemsQuery {
  catalogItems(
    filter: {
      merchantId: { 
        equalToAnyOf: [ "<MERCHANT_ID>" ]
      }
      id: { 
        equalToAnyOf: [ "<CATALOG_ITEM_ID>" ]
      }
    }
  ) {
    nodes {
      # requested fields
    }
  }
}

• GraphQL Explorer Overview
• GraphQL Basics
• Build your First GraphQL Query
• GraphQL Query Examples
• Sample: Square and GraphQL - Code Example (Node.js)
• Sample: Square Dev GraphQL and PKCE Example Application (React Native)
• Blog: Unlock a Better Mobile Experience with Square GraphQL and PKCE