GraphQL Admin API reference​

Use GraphQL Admin APIs to extend SHOPLINE's built-in features. These APIs enable you to read and write merchants' data, allowing you to build your app to expand and enhance SHOPLINE's admin functionality.
This page introduces how to use SHOPLINE GraphQL Admin APIs.

Authentication​

To ensure the security of all transactions on the SHOPLINE platform, every app must be authenticated when making a GraphQL Admin API request.
OAuth 2.0 is employed for the authentication of public and custom apps. After authentication, you can obtain a valid access token. To learn how to use OAuth 2.0 to get an access token, see the Authorization mechanism.
The access token for a private app is obtained from the SHOPLINE Admin. Go to Apps > Develop Apps > Edit > API certificate, and find Admin API access token.

The access token for a private app is valid for three years. Before it expires, you will receive an email reminder that the access token is about to expire. You need to go to the SHOPLINE Admin to refresh the access token. The original access token will expire 30 minutes after it has been refreshed. If you want to revoke the authorization of your private app from the store, you must go to the SHOPLINE Admin to delete the app, which will then render the access token invalid.
When querying a GraphQL Admin API, add the access token to the Authorization parameter of the HTTP header. The format is as follows:

"Authorization":"Bearer {Your Token}"

Endpoint​

All GraphQL Admin APIs are accessed via the HTTP POST method by sending requests to the following endpoint:
POST https://{store_domain}.myshopline.com/admin/graph/{version}/graphql.json.

Replace the values of the following variables:

• store_domain: indicates the handle of the merchant store.
• version: indicates the API version that you use.

Versioning​

GraphQL Admin API provides different API versions based on the continuous iteration of SHOPLINE products. Refer to the API versioning guide to obtain the list of available API versions.

Global ID​

A global ID is a unique identifier for a GraphQL object.
The structure of a global ID is gid://shopline/{object_name}/{id}, in which object_name is the name of a GraphQL object. For example, the global ID for the object Customer with an ID of 1 is gid://shopline/Customer/1.
You can fetch global IDs of objects through GraphQL queries, and use them in GraphQL queries and mutations.

Request limits​

Rate limit​

The rate limit for GraphQL Admin API is measured by cost points. The response to each request costs a certain number of points. If a request exceeds the point limit, the HTTP status code 429 is returned. The code sample is as follows:

HTTP status code: 429

{"errors":"Too many request"}

A simple GraphQL Admin API request costs fewer points, allowing for multiple requests simultaneously. However, if your request is too complex, the subsequent request likely waits for a long time.

Field layer limit​

The GraphQL Admin API supports a maximum of 13 field layers in a request, as shown in the following code sample.

query {
	 field1 {
		 field2 {
       field3 {
         ......
			     field13 {
         }
		   }
     }
   }
}

If your request exceeds the limit, an HTTP result code of 200 and a system error are returned. For example, if you send a request containing 14 field layers, the following error is returned.

HTTP status code: 200

{
  "errors": [
    {
      "message": "maximum query depth exceeded 14 > 13",
      "extensions": {
        "classification": "ExecutionAborted"
      }
    }
  ]
}

Status and error codes​

All GraphQL Admin API responses include HTTP status codes, often accompanied by specific error codes.

200​

When the API is called successfully, the status code 200 is returned. In certain conditions, the business error code may also be returned due to some server-side problems, such as missing data. You can obtain the specific error from the errors.extensions.code field, and errors.message represents the meaning of the error code. An example is as follows:

HTTP status: 200

{
  "errors": [
    {
      "message": "DATA_NOT_EXIST",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "field"
      ],
      "extensions": {
        "code": "DATA_NOT_EXIST"
      }
    }
  ],
  "data": {
    "api": null
  }
}

Error codes​

The following table shows common business error codes and their corresponding descriptions.

Table 1. Common error codes

Common error codes​

HTTP status: 200

4XX and 5XX status codes​

In some cases, 4XX and 5XX status codes may be returned. 4XX status codes generally indicate client-side issues, whereas 5XX status codes typically signify server-side problems. For instance, when a store is closed or frozen, you receive the following response:

HTTP status: 402

{
	"errors": "Store has been frozen or closed"
}

Common error codes​

For more information about HTTP status codes, see HTTP status codes.

API Explorer​

Start exploring SHOPLINE GraphQL Admin APIs using the API Explorer. The API Explorer provides demo shop data. You can use the API Explorer to do the following:

• Learn about the shop resources that SHOPLINE provides.
• Make queries and mutations to get or modify demo shop data.
• Explore different versions of GraphQL API.