Square GraphQL

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

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 can use both GraphQL for faster querying and Square APIs or Square SDKs for write operations. Note that Square SDKs cannot be used to send GraphQL queries.

• Applications that use OAuth require specific READ permissions to access Square data in GraphQL queries. For more information, see Authorization process.

• 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.
  • Only catalog and customer custom attributes are supported. Custom attributes for other objects (such as locations and orders) aren't accessible using 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 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 Console doesn't include GraphQL queries.

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. After signing in to GraphQL Explorer, you can browse the full schema in the Documentation Explorer pane.

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.

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.

• 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 ID of the merchant (seller) associated with the access token, query currentMerchant for the id field.

{
  currentMerchant {
    id
  }
}

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 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 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.

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
  }
}

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
• 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