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.
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 points:
bookings - Retrieves a merchant's bookings (appointments).
bookingAvailability - Retrieves information about time slots that can be booked.
locationBookingProfiles - Retrieves booking information for business locations, such as whether the location is enabled for booking.
businessBookingProfile - Retrieves booking information for a merchant, such as whether bookings are allowed and the cancellation policy.
teamMemberBookingProfiles - Retrieves booking information for team members, such as whether the team member is enabled for booking.
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:
customerCustomAttributeDefinitions - Retrieves the definitions of custom attributes that can be applied to customer profiles. Only definitions that are visible to your application are returned.
To retrieve custom attribute values that are set on customer profiles, query the customers entry point and include the customAttributes field.
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 merchant (seller).
Entry point:
orders - Retrieves orders.
Entry point:
payments - Retrieves payments.
Entry point:
paymentRefunds - Retrieves refunds.
Entry points:
subscriptions - Retrieves subscriptions.
subscriptionEvents - Retrieves information about changes to subscriptions.
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. After signing in to GraphQL Explorer, you can browse the full schema in the Documentation Explorer pane.
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:
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:
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.
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:
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 token in the Authorization header, just like Square API requests. The access token you provide 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.
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
Limitations
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.
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 type
New name and type
image: CatalogImage
images: [CatalogImage]
Effective date: 2023-04-12
The following OrderFilter fields are renamed:
Previous name
New name
customers
customer
ids
id
locations
location
merchants
merchantId
sourceNames
sourceName
states
state
Effective date: 2023-04-12
The required merchant ID is now passed using the id filter.
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.