Skip to main content

Integration API

Exploring the schema​

GraphQL APIs are self-documenting: once you have an access token, any GraphQL client (such as GraphiQL, Postman, Altair or Insomnia) can explore the available queries, mutations and types through introspection.

Introspection is only available with a valid access token. Without one, you can browse the API reference, which is continuously updated to match the schema.

GraphQL Access Token​

An access token is a credential that is bound to a certain set of permissions. The set of permissions is decided during token generation. It is not bound to any specific user, but may be issued with a specific user in mind.

Access token always has an expiration time after which it will no longer authorize any requests.

Obtaining Access Token via AMS​

For GraphQL access you need user token with correct permissions. This could be done in the backend AMS. Navigate to System -> Api Tokens and then add a new token by clicking + Integration API TOKEN button.

Here we are able to provide restrictions, select permissions, and expiration time. Requirements for generating token are:

  • Providing a description that allows unambiguous identification of the token
  • At least one permission

Setting an expiration time is optional – if you don't set it, the token expires after 30 days.

Token Revocation​

Access tokens can be revoked in the AMS when necessary. Navigate to System -> Api Tokens and select the token that you want to invalidate. This demonstrates the value of naming tokens unambiguously. When token details are displayed use the X Revoke button.

Authorizing Requests​

One way to authorize the request is to provide an Authorization header:

POST *base*/graphql

Authorization: Bearer <access token>

CURL example:

curl "${BASE_URL}/graphql" \
-X POST \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"query":"{ __schema { types { name } } }"}'

Another way to authorize request to GraphQL API is to add a cookie named graphql-access with only the access token as value.

POST *base*/graphql

Cookie: graphql-access=<access token>

CURL example:

curl "${BASE_URL}/graphql" \
-X POST \
-H "Cookie: graphql-access=${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"query":"{ __schema { types { name } } }"}'

For instructions on how to attach a header or cookie in your API client refer to the client's documentation.

Missing, invalid or expired token​

If the token is missing, invalid or expired, the request is rejected with HTTP status 403 and one of the following error messages: "Access denied.", "Your token is invalid. Please double-check it.", or "Your token is expired. Please create a new one.". For more information, see Handling errors.

Permissions​

The list of permissions is changing as new permissions are added to match new queries and mutations.

info

During your integration's initial tests in QA, it's worth to note all the information returned in extensions.permissionsUsed, so that you know exactly which permissions are required for use cases covered in your integration. This way you can later use API tokens with minimal permissions when you move to Production, which we highly recommend. Running Production integrations on tokens with full admin permissions is considered bad practice, and a potential security vulnerability.

If you call the API without required permissions, you will be informed about this explicitly:

Request:

{
orderConnection(
last: 10
before: "bnVtYmVyOjE2Ng=="
where: { storeType: WHOLESALE }
) {
totalCount
pageInfo {
hasPreviousPage
hasNextPage
startCursor
endCursor
}
edges {
node {
number
status
grandTotal {
value
currency {
code
}
}
orderDate
}
cursor
}
}
}

Response (with HTTP status 400):

{
"errors": [
{
"message": "You need Order:read permission to access orderConnection.",
"extensions": {
"category": "authorization"
},
"locations": [
{
"line": 2,
"column": 3
}
],
"path": ["orderConnection"]
}
],
"extensions": {
"complexity": 40,
"permissionsUsed": []
}
}

Deprecations in the latest GQL API versions​

We're making some changes to our GraphQL Integration API because we want it to reflect business concepts better and need to align the naming.

We are doing our best not to introduce breaking changes so that existing queries still work, but you can switch to using new names at any time. For example, when a field is renamed, a new field is added, and the old one still works. When a returned type changes, the old type is turned into an interface so that fragments explicitly specifying types are not broken.

Moreover, we are now returning a list of deprecated fields used under extensions, so you can see exactly whether your queries use deprecated fields and when they will be deleted. If no removal date is scheduled yet, the entry says date of removal: to be determined.

Example response:

{
"data": {
...
},
"extensions": {
"deprecatedFieldsUsed": [
"Field: Query.displays, reason: Use ObjectWithTranslations instead of Localizable, date of removal: 2023-09-04",
"Field: Display.localized, reason: Renamed localized to translations, date of removal: 2023-09-04",
"Field: LanguageTranslation.translations, reason: Renamed to fields, date of removal: 2023-09-04"
]
}
}

User warnings - not required, but important!​

GraphQL mutations return HTTP 200 response, and the way issues are communicated is through the userErrors field in payloads. However, not all issues are equal, and some non-critical ones actually don't prevent mutations from succeeding.

This is especially important for batch actions like price updates (setPrices), where it is really important to save all other prices rather than failing because of one that is wrong for some trivial reason, e.g.:

  • "Duplicate product ID 123 skipped"
  • "Duplicate variant ID 456 skipped"
  • "Product variant with id 789 not assigned to product 123"
  • "Product ID 345 is a bundle with dynamic price type, changing its prices has no effect, skipped"

Sometimes warnings are purely informative, like "Weight unit has been changed from KILOGRAMS to POUNDS", or "Weight has been rounded to 3 decimal places".

userErrors from now on contain only errors, and userWarnings - all other issues. They both have a message and a path.

mutation updateProductWeight {
updateProduct(id: 1, input: { weight: { value: 11, unit: POUNDS } }) {
product {
id
weight {
formattedValue
}
}
userErrors {
message
path
}
userWarnings {
message
path
} # NEW!
}
}

It makes sense to add userWarnings to all mutations, even if you don’t expect anything like mentioned above. New warnings can be added in the future.