Streamline your application flow with fewer, faster, and more compact data transfers using Square GraphQL. ## Overview 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](/docs/oauth-api/overview) access management. * Support for testing in the [Square Sandbox](/docs/devtools/sandbox/overview) environment. * A statically typed schema that enables developer tooling. You can view the schema documentation when you sign in to [GraphQL Explorer](https://developer.squareup.com/explorer/graphql). ## Requirements and limitations * Square GraphQL supports query operations only; mutations and subscriptions aren't supported. Applications can use both GraphQL for faster querying and [Square APIs](https://developer.squareup.com/reference/square) or [Square SDKs](/docs/sdks) for write operations. Note that Square SDKs cannot be used to send GraphQL queries. * Applications that use [OAuth](/docs/oauth-api/overview) require specific READ permissions to access Square data in GraphQL queries. For more information, see [Authorization process](#authorization-process). * [Rate limits](#rate-limiting) are applied to Square GraphQL queries. * The API Logs feature in the Developer Console doesn't include GraphQL queries. * Not all Square APIs have corresponding GraphQL support. [Supported graphs](#supported-square-graphs) generally provide access to the same data as the corresponding Square APIs and might provide expanded direct access to referenced objects that cross API boundaries. However, supported graphs aren't always at parity with corresponding Square APIs. The following are examples of how Square GraphQL support might differ from Square APIs: * Deprecated fields might not be available. * Compared to corresponding list or search endpoints, GraphQL might provide more or fewer filters. * Only catalog and customer custom attributes are supported. Custom attributes for other objects (such as locations and orders) aren't currently accessible in GraphQL queries. 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](https://developer.squareup.com/explorer/graphql) or by using the introspection system, as shown in the following simple introspection query: ``` { __schema { types { name description kind } } } ``` For more information, see [Introspection](https://graphql.org/learn/introspection/) at graphql.org. ## 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: * `devices` - Retrieves all POS and peripheral devices associated with the merchant. 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. * `scheduledShifts` - Retrieves draft and published shifts from a team schedule. * `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. * `timecards` - Retrieves a list of labor shifts. **Note** - This entry point replaces the deprecated `shifts` entry point. * `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: * `payoutEntries` - Retrieves payout entries associated with payouts. * `payouts` - Retrieves payouts to a seller. 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 and might provide extended 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](https://developer.squareup.com/explorer/graphql), you can browse the full schema in the **Documentation Explorer** pane. ## 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: ```graphql { 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. ### Get started To get started with Square GraphQL: * Build and send queries in [GraphQL Explorer](https://developer.squareup.com/explorer/graphql). 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](/docs/devtools/graphqlexplorer). * Explore our documentation: * Read about concepts, patterns, and other [GraphQL basics](/docs/graphql/basics). * Learn how to use the find available data and valid syntax in the schema as you [build your first query](/docs/graphql/build-your-first-query) in GraphQL Explorer. * Check out some [query examples](/docs/graphql/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](https://github.com/square/connect-api-examples/tree/master/connect-examples/v2/graphql-sample-app) (Node.js) sample application. * See GraphQL used in a real-world scenario in the [Square Dev GraphQL and PKCE Example Application](https://github.com/square/squaredev-graphql-pkce-demo) (React Native) mobile application. * Send queries to Square GraphQL endpoints using third-party tools, such as Postman and [GraphiQL](https://github.com/graphql/graphiql). For example, the following cURL query retrieves an order and the customer who made the order: ```curl curl https://connect.squareupsandbox.com/public/graphql \ -X POST \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "query": "{ orders( filter: { id: { equalToAnyOf: [\"\"]} merchantId: { equalToAnyOf: [\"\"]}}) { nodes { state updatedAt customer { id emailAddress }}}}" }' ``` ### 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. ```graphql { currentMerchant { id } } ``` ## 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 permission. The schema documentation in [GraphQL Explorer](https://developer.squareup.com/explorer/graphql) shows required permissions for entry points and objects. Production applications use OAuth access tokens to access a seller's data. You use an [OAuth flow](/docs/oauth-api/overview) 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](/docs/devtools/sandbox/overview#create-a-sandbox-test-account). ### Setting the access token in GraphQL Explorer If you're using [GraphQL Explorer](https://developer.squareup.com/explorer/graphql), 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 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. ```json { "Authorization": "Bearer ", "x-graphql-include-debug": 1 } ``` Square returns the complexity score in the `extensions` object, as shown in the following excerpt: ```json { "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() { # 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](/docs/graphql/basics#pagination), 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. ## Get support for Square GraphQL Tag your feedback, issues, and questions with `graphql-api` and post them on the [Square Developer forums](https://developer.squareup.com/forums/tag/graphql-api) or email graphql-api@squareup.com. ## 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 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. **Example:** Previous argument ``` query MerchantsQuery { merchants( filter: { merchants: [ "" ] } ) { nodes { # requested fields } } } ``` **Example:** Current argument ``` query MerchantsQuery { merchants( filter: { id: { equalToAnyOf: [ "" ] } } ) { nodes { # requested fields } } } ``` Effective date: 2023-04-12 The following `CustomerFilter` field is renamed: |Previous name|New name| |:------|:------| |`ids`|`id`| 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 ``` query CatalogObjectsQuery { catalog( merchantId: { equalToAnyOf: [ "" ] } all { filter: { id: { equalToAnyOf: [ "" ] } } } ) { nodes { # requested fields } } } ``` **Example:** Current catalog objects query ``` query CatalogObjectsQuery { catalog( filter: { merchantId: { equalToAnyOf: [ "" ] } id: { equalToAnyOf: [ "" ] } } ) { nodes { # requested fields } } } ``` **Example:** Previous catalog items query (uses the `catalog` entry point) ``` query CatalogItemsQuery { catalog( merchantId: { equalToAnyOf: [ "" ] } items { filter: { id: { equalToAnyOf: [ "" ] } } } ) { nodes { # requested fields } } } ``` **Example:** Current catalog items query (uses the `catalogItems` entry point) ``` query CatalogItemsQuery { catalogItems( filter: { merchantId: { equalToAnyOf: [ "" ] } id: { equalToAnyOf: [ "" ] } } ) { nodes { # requested fields } } } ``` Effective date: 2023-03-28 The following `CatalogFilter` fields are renamed: |Previous name|New name| |:------|:------| |`ids`|`id`| |`itemVariationsForItemOptionValues`|`itemVariationsForItemOptionValue`| |`itemsForItemOptions`|`itemsForItemOption`| |`categoryIds`|`categoryId`| |`customAttributes`|`customAttribute`| |`enabledLocationIds`|`enabledLocationId`| |`productTypes`|`productType`| The sample applications in the following list include a script you can run to upload test data to your Square account. ## See also * [GraphQL Explorer](/docs/devtools/graphqlexplorer) * [GraphQL Basics](/docs/graphql/basics) * [Build your First GraphQL Query](/docs/graphql/build-your-first-query) * [GraphQL Query Examples](/docs/graphql/query-examples) * [Sample: Square and GraphQL - Code Example (Node.js)](https://github.com/square/connect-api-examples/tree/master/connect-examples/v2/graphql-sample-app) * [Sample: Square Dev GraphQL and PKCE Example Application (React Native)](https://github.com/square/squaredev-graphql-pkce-demo) * [Blog: Unlock a Better Mobile Experience with Square GraphQL and PKCE](https://developer.squareup.com/blog/unlock-a-better-mobile-experience-with-square-graphql-and-pkce)