Square GraphQL

Streamline your application flow with fewer, faster, and more compact data transfers using GraphQL.

Link to section


GraphQL queries can improve performance and reduce development time by letting you request exactly the data you need. GraphQL can be especially beneficial for resource-constrained mobile applications and in modern frontend development.

Square GraphQL features include:

  • A standards compliant endpoint serving multiple Square graphs. One GraphQL query can retrieve data that requires multiple Square API calls.
  • 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; mutations and subscriptions aren't supported. 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.

Link to section

Supported Square graphs

Square GraphQL supports query operations for the following Square graphs:

Entry point:

  • cardsOnFile - Retrieves stored credit or debit cards that can be used for card-on-file payments.

Entry points:

  • cashDrawerShiftEvents - Retrieves events for a specified cash drawer shift.
  • cashDrawerShifts - Retrieves cash drawer shifts for a specified location.

Entry points:

  • catalog - Retrieves catalog objects of any type.
  • catalogItems - Retrieves ITEM and ITEM_VARIATION catalog object types.

Entry point:

  • customers - Retrieves customer profiles from the Customer Directory.

Entry point:

  • giftCards - Retrieves gift cards. Gift card details include the gift card number (GAN), balance, state, and linked customers.

Entry point:

  • giftCardActivities - Retrieves activities that represent changes to the balance or state of gift cards.

Entry points:

  • inventoryChanges - Retrieves count, adjustment, and transfer-related changes to inventory items.
  • inventoryCounts - Retrieves the current count and state of inventory items.

Entry points:

  • breakTypes - Retrieves the break types that can be added to a shift.
  • shifts - Retrieves a list of labor shifts.
  • teamMemberWages - Retrieves available wage types for team members. Wage types include the title and pay rate for jobs that team members can perform for a shift.
  • workweekConfigs - Retrieves the day of the week and hour of the day that a business starts the workweek. This information is used to calculate overtime pay.

Entry points:

  • loyaltyAccounts - Retrieves loyalty accounts for customers who are enrolled in a loyalty program.
  • loyaltyEvents - Retrieves events that represent changes to the point balance of loyalty accounts.
  • loyaltyProgram - Retrieves the merchant's loyalty program.
  • loyaltyPromotions - Retrieves loyalty promotions associated with a loyalty program.
  • loyaltyRewards - Retrieves loyalty rewards that are used to redeem points for discounts.

Entry points:

  • currentMerchant - Retrieves information about the merchant associated with the access token provided in the request. You can query currentMerchant to get the merchant ID required by most queries.
  • merchants - Retrieves information about a specified seller.

Entry point:

  • orders - Retrieves orders.

Entry point:

  • payments - Retrieves payments.

Entry point:

  • paymentRefunds - Retrieves refunds.

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.

Link to section

How to access Square GraphQL

The open-source GraphQL standard defines both a query language and a runtime that retrieves data using queries.

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.

Link to section

Get started

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:

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

  • 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 }}}}" }'
Link to section

Getting the merchant ID for queries

Most queries require that you filter by a merchant ID. If you need to get the ID of the merchant (seller) associated with the access token, query currentMerchant for the id field.

{ currentMerchant { id } }
Link to section

Authorization process

GraphQL queries require 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. For example, a query that includes fields for an order and the customer who made the order requires both ORDERS_READ and CUSTOMERS_READ permissions to get full results. Fields you're not permitted to view are returned with null values. In addition, the errors list in the response contains SCOPE_MISSING errors with related information, such as the missing OAuth scope.

Production applications use OAuth access tokens to access a seller's data. You use an OAuth flow to obtain an access token for each seller who uses your application. Query results are scoped to the permissions that you request from sellers.

During development, you can use your personal access token to test with unrestricted access to your account data. Make sure to use the personal access token that's valid for the target Sandbox or production environment. To test with OAuth permissions, you can create and authorize Sandbox test accounts.

Link to section

Setting the access token in GraphQL Explorer

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.

Link to section

Rate limiting for Square GraphQL

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.

For testing or debugging purposes, you can direct Square to return the complexity score for a query. To do so, include the x-graphql-include-debug request header and set the value to 1. In GraphQL Explorer, add the header to the Request Headers pane.

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

Square returns the complexity score in the extensions object, as shown in the following excerpt:

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

You can calculate the cost of a query using the following point scale:

  • Two points for each graph entry point, connection object, and join relationship - A query contains at least one graph entry point and one connection object, so the minimum query cost is four points. For the following example query, add two points for the orders entry point, two points for the nodes connection object, and two points for the refunds join relationship:

    { orders(<args>) { # entry point to the Orders graph nodes { # connection object refunds { # join relationship reason } location { # object id } } } }

    The location object is counted next.

  • One point for each object, union, or interface - In a query, every specified field whose data type is an object, union, or interface costs one point. For the previous example query, add one point for the location object, which brings the total complexity score of the query to seven points.

    Note that when a query includes a first or last page size argument, the specified value also counts as points.

  • Zero points for scalars and enums - Scalars and enums don't incur a cost because they return a final value in query results. In the example query, reason is a String scalar value and id is an ID scalar value.

In a query, the first and last arguments can be used to specify the page size, which is the maximum number of results to include in a single page of the response. For queries that include a first or last argument, the specified page size value counts as points. For example, first: 20 adds 20 points to the complexity score.

The complexity score might also determine the maximum possible page size for a query. As the complexity score increases, the maximum possible page size decreases. For example, the most simple orders query costs four connection points, which effectively limits the maximum page size to 246. Adding location to the query reduces the limit to 245.

Some graphs enforce a lower maximum page size limit. For example, a customers query has a maximum page size of 20. In this case, the complexity score is less likely to result in rate limiting based on the query complexity.

Link to section


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.

Link to section

Get support for Square GraphQL

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

Link to section

Migration notes

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:

Effective date: 2023-05-23

The following CatalogItem field is changed:

Previous name and typeNew name and type
image: CatalogImageimages: [CatalogImage]

Effective date: 2023-04-12

The following OrderFilter fields are renamed:

Previous nameNew name

Effective date: 2023-04-12

The required merchant ID is now passed using the id filter.

Example: Previous argument

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

Example: Current argument

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

Effective date: 2023-04-12

The following CustomerFilter field is renamed:

Previous nameNew name

Effective date: 2023-04-01

Added a separate entry point for catalog items and the merchant ID is passed as a filter. The Catalog graph now provides separate entry points for querying catalog objects and catalog items. As part of this change, the all and items top-level fields are removed. In addition, the merchant ID is now passed as a filter.

Example: Previous catalog objects query

Example: Current catalog objects query

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

Example: Previous catalog items query (uses the catalog entry point)

Example: Current catalog items query (uses the catalogItems entry point)

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

Effective date: 2023-03-28

The following CatalogFilter fields are renamed:

Previous nameNew name


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

Link to section

See also