An overview about using a GraphQL schema and endpoint to work with Square APIs.
Developer Tools

GraphQL Overview (alpha) New

Important

Square GraphQL (alpha) is publicly available to all developers as part of an early alpha release. During this alpha release of Square GraphQL, Square is gathering feedback to improve our developer experience. Square GraphQL might be subject to breaking changes to the schema and the list of supported APIs that are backwards incompatible with future releases. Square also anticipates changes to GraphQL Explorer and the documentation during the alpha release. Queries to Square GraphQL are rate limited to two queries per second, which might make it inappropriate for use in a production environment.

GraphQL is an open-source standard that defines both a query language and a runtime that can retrieve data using queries. Using GraphQL, you can query multiple objects from different Square APIs. Square GraphQL supports queries only; it does not support mutations. If you need to perform both read and write operations, you should use the Square REST APIs.

The following APIs are supported in Square GraphQL:

  • Orders API

  • Catalog API

  • Customers API

  • Merchants API

Some of the features of Square GraphQL include:

  • A standards compliant GraphQL endpoint with the ability to serve multiple Square APIs.

  • The ability to work with existing data, the Sandbox, and OAuth.

  • Statically typed schemas that enable developer tooling.

  • The ability to query for exactly the data you need, including multiple types of data with one query.

How to access Square GraphQL Permalink Get a link to this section

There are two Square endpoints you can use for submitting GraphQL queries. The production endpoint is https://connect.squareup.com/alpha/graphql and the Sandbox endpoint is https://connect.squareupsandbox.com/alpha/graphql.

A simple way to get familiar with making GraphQL queries against Square data is by using GraphQL Explorer at https://developer.squareup.com/explorer/graphql.

The Square GraphQL endpoint works with any third-party GraphQL tools, such as GraphiQL (https://github.com/graphql/graphiql) and GraphQL IDE (https://github.com/graphql/graphql-playground).

For example, you can run a query using cURL:

Support for Square GraphQL Permalink Get a link to this section

You can post feedback, issues, and questions on the Square Developer forum (tag your question with the graphql tag) or you can email graphql-alpha@squareup.com.

Known issues with Square GraphQL Permalink Get a link to this section

  • Query variables do not work at this time.

GraphQL basics Permalink Get a link to this section

You should understand the following common GraphQL query-related concepts:

  • Schema. The schema shows what data is available to query. It defines the objects, object types, and attributes for the data.

  • Object. Objects are collections of data that you can query. They have object types and attributes.

  • Queries. GraphQL operations are in the form of queries. Because queries are also objects, you can name and reuse queries.

Queries Permalink Get a link to this section

A typical query begins with a { character. Lines that begin with a # character are treated as comments and ignored. An example query might look like the following:

For example, the following query:

Returns these values:

Filters Permalink Get a link to this section

A filter retrieves only data that meets a set of criteria you specify. Queries for Square GraphQL mirror the filters in the Square API. The filter parameter corresponds to the search endpoint in the Square API

Pagination Permalink Get a link to this section

Square GraphQL uses the cursor method of pagination. You retrieve data by specifying the page size and then use a pointer (cursor) to keep track of where the next set of data should be retrieved from. For example, suppose you want to retrieve data from the Orders graph. In your query, you specify the number of items you want to retrieve using the first variable. Then subsequent calls to retrieve more data use the after variable to return more data.

Your first query using pagination might look like the following:

The query response shows hasNextPage as true if there are more pages of data to retrieve. When you include after in the parameter, the value of the endCursor is passed into a subsequent query.

Working with Square GraphQL Permalink Get a link to this section

GraphQL queries can map to Square API data models. You can query API objects from several endpoints in a single query.

Authentication process Permalink Get a link to this section

To run a query, you provide a bearer token header just as you do when connecting to Square APIs. You have access to all the data that you have been granted permissions to view. Your query results are scoped to the permissions you have been granted.

If you are using GraphQL Explorer, you provide your access token in the Request Headers section or you select an access token using the Add access token button. Note that you must be logged in to your developer account for the Add access token button to work.

Rate limiting Permalink Get a link to this section

Rate limits enforce reasonable API usage. Rate limits also prevent bad actors from abusing the API and prevent clients from unintentionally sending requests in infinite loops or sending a high number of requests in bursts. Square uses a calculated query cost method for rate limiting. The server calculates the cost of the query before executing it and returns the calculated cost in the extension object. The Square GraphQL (alpha) is significantly rate limited to discourage using the alpha release in production.

Square allows the following before limiting:

  • You can run a maximum of two queries per second (2 QPS).

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

  • A query can have a maximum cost of 1000 points.

How to estimate the query cost Permalink Get a link to this section

Each GraphQL query has a different cost that you can calculate by identifying each type used in the query. The calculated query cost method has the following values:

  • Two points for a connection. A connection is a one-to-many relationship expressed as a paginated list. For example, the query { pets { owners { name } } } costs two points for the pets paginated list and two points for the owners join relationship.

  • One point for an object. The object is the base unit and is worth one point. Objects usually represent a single server-side operation such as a database query or a request to an internal service. The object cost of the query { pets { owners { name } } } is one point for each owner in the list and one point for each pet in the list.

  • One point for unions and interfaces. Because these behave like objects that return different types, they cost one point for each union or interface, just like objects.

  • Zero points for scalars and enums. Scalars are types that return a final value, such as strings, integers, IDs, and Booleans. Enums are a special type of scalar that returns one of a predefined set of values. These types live within objects that already have had their cost calculated.

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