GraphQL (alpha) New

Link to section

Overview

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 your application needs to perform both read and write operations, you should use the Square REST APIs.

Square GraphQL supports the following Square APIs:

• Orders API

• Catalog API

• Customers API

• Merchants API

• Payments API

• Refunds API

• Inventory API

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

Link to section

How to access Square GraphQL

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:

curl --location --request POST 'https://connect.squareup.com/alpha/graphql' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{\n  orders(\n    filter: {\n      id: { equalToAnyOf: [\"<ORDER_ID>\"]}\n      merchantId: { equalToAnyOf: [\"<MERCHANT_ID>\"] }\n    }\n  )\n  {\n    nodes {\n      state\n      updatedAt\n    }\n  }\n}","variables":{}}'

Link to section

Support for Square GraphQL

You can post feedback, issues, and questions on the Square Developer forum (tag your question with the graphql-api tag) or you can email [email protected]

Link to section

GraphQL basics

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.

Link to section

Queries

A typical query begins with a { character. Lines that begin with a # character are treated as comments and ignored. For example, a simple query might use the following format:

# This is a simple query format
{
  field(arg: "value") {
    subfield
  }
}

The following example query from GraphQL Explorer requests the status and mainLocation fields for a given merchant.

{
  merchants( filter: { id: { equalToAnyOf: ["<MERCHANT_ID>"]}}) {
    nodes {
      status
      mainLocation {
        id
        name
        createdAt
        capabilities
      }
    }
  }
}

Because mainLocation is a complex type, you must also specify the Location subfields that you want to retrieve. If successful, the query returns results similar to the following:

{
  "data": {
    "merchants": {
      "nodes": [
        {
          "status": "ACTIVE",
          "mainLocation": {
            "id": "M8AKAD8160ABC",
            "name": "Default Test Account",
            "createdAt": "2022-07-10T16:53:39.885Z",
            "capabilities": [
              "CREDIT_CARD_PROCESSING",
              "AUTOMATIC_TRANSFERS"
            ]
          }
        }
      ]
    }
  }
}

Link to section

Filters

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.

Link to section

Variables

You can use variables to replace static or dynamic values in query arguments. For example, by using a variable for the merchant ID that's required to access Square data, you can easily reuse the query for different merchants.

The format for a variable is $variableName (a dollar sign followed by the variable name). To use a variable in a query, you must:

The following example cURL query uses two variables, $merchantId and $searchText:

curl https://connect.squareupsandbox.com/alpha/graphql \
-X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "query": "query CatalogTextSearch($merchantId: ID!, $searchText: [String!]!) { catalog(filter: { merchantId: { equalToAnyOf: [$merchantId]}, text: { value: $searchText}}) { nodes { id ... on CatalogItem { name }}}}",
  "variables": { "merchantId": "8QJT7EXAMPLE", "searchText": ["gluten", "free"]}
}'

Note how the variables are used in the example query:

• The variables and their types are declared as arguments for the query operation:

  query CatalogTextSearch($merchantId: ID!, $searchText: [String!]!)

• The $merchantId variable is used by the merchantId filter in the query:

  merchantId: { equalToAnyOf: [$merchantId]}

• The $searchText variable is used by the text filter in the query:

  text: { value: $searchText}

• The values for both variables are defined in the variables object:

  "variables": { "merchantId": "8QJT7EXAMPLE", "searchText": ["gluten", "free"]}

  Values are passed in a separate, transport-specific (usually JSON) variables dictionary. You can also use a separate JSON file to pass in variable values.

Link to section

Using query variables in GraphQL Explorer

In Square GraphQL Explorer, you can declare and reference variables in query arguments using the $variableName format, similar to the preceding example. To define the values of variables, use the Query Variables tab.

The sample queries available in GraphQL Explorer show how to use variables in queries and pass in their values.

Link to section

Pagination

Square GraphQL uses the cursor method of pagination. You retrieve pages of data by specifying the page size and then use a pointer (cursor) to keep track of where the next page of data should be retrieved from.

The following example query from GraphQL Explorer uses pagination to retrieve all orders for a given merchant and location:

• The first field specifies the page size, which is the maximum number of items to return in each response page.

• The pageInfo field requests the hasNextPage and endCursor to use for forward pagination.

query PaginatedQuery {
  orders(
    filter: { merchantId: { equalToAnyOf: ["<MERCHANT_ID>"]}, location: { equalToAnyOf: ["<LOCATION_ID>"]}}
    first: 3
  ) {
    nodes {
      id
      customer {
        givenName
        familyName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

The following is an example paged response:

{
  "data": {
    "orders": {
      "nodes": [
        {
          "id": "kfn0S4F0rC765YIotVsguEA8taB",
          "customer": {
            "givenName": "Arjun",
            "familyName": "Mahanti"
          }
        },
        {
          "id": "O2ajrDfbyhPtAUAR64zzKNSouaB",
          "customer": {
            "givenName": "Jennifer",
            "familyName": "Shen"
          }
        },
        {
          "id": "a2VSRiNIsFXJ0rUvTfrBYkTkvaB",
          "customer": null
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "i7QRXHX2HKYqHrk...G4yFQ"
      }
    }
  }
}

If more pages of data are available, hasNextPage is true and endCursor contains the cursor.

In your next query, include the after field and provide the cursor from the previous response, as shown in the following example:

query PaginatedQuery {
  orders(
    filter: { merchantId: { equalToAnyOf: ["<MERCHANT_ID>"]}, location: { equalToAnyOf: ["<LOCATION_ID>"]}}
    first: 3
    after: "i7QRXHX2HKYqHrk...G4yFQ"
  ) {
    nodes {
      id
      customer {
        givenName
        familyName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Continue using the cursor from each response page in a subsequent query until you retrieve all response pages.

In the last response page, hasNextPage is false and endCursor is null, as shown in the following example:

{
  "data": {
    "orders": {
      "nodes": [
        {
          "id": "Yja9D6QK6NVI8br85QWFoaTDvaB",
          "customer": {
            "givenName": "Mio",
            "familyName": "Yoshigiwa"
          }
        },
        {
          "id": "YlvzJWQgEcmvT2zcEZHJMB3SuaB",
          "customer": {
            "givenName": "Elisa",
            "familyName": "Rizzo"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": null
      }
    }
  }
}

The pagination process might vary depending on the Square graph being queried. For example, payments and refunds can also be paginated in a backward direction using the last and before fields and the startCursor cursor.

Link to section

Working with Square GraphQL

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

Link to section

Authentication process

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.

Link to section

Rate limiting

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 10 queries per second (10 QPS).

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

• You can run 10 requests per second, putting an implicit limit on complexity points consumed per second to 2500.

Link to section

How to estimate the query cost

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.