Skip to main content

ShopifyQL with the GraphQL Admin API

You can send ShopifyQL queries via the GraphQL Admin API, allowing you to build reporting directly into your apps or programmatically extract data for further analysis.

Build apps that query analytics data programmatically using the shopifyqlQuery endpoint:

GraphQL query

{
shopifyqlQuery(
query: "FROM sales SHOW total_sales, orders SINCE last_week GROUP BY day ORDER BY day DESC"
) {
tableData {
columns {
name
dataType
displayName
}
rows
}
parseErrors
}
}

Anchor to Required access scopesRequired access scopes

To use the ShopifyQL API, your app requires the following access scopes:

ScopePurpose
read_reportsAccess to analytics and reporting data.
read_customersAccess to customer data in queries.
Protected customer data

ShopifyQL queries require level 2 access to protected customer data. Your app must meet Shopify's protected customer data requirements.

Anchor to API response formatAPI response format

The API returns data in a structured JSON format:

JSON response

{
"data": {
"shopifyqlQuery": {
"tableData": {
"columns": [
{
"name": "day",
"dataType": "DAY_TIMESTAMP",
"displayName": "Day"
},
{
"name": "total_sales",
"dataType": "MONEY",
"displayName": "Total sales"
}
],
"rows": [
{ "day": "2024-01-15", "total_sales": "2547.83" },
{ "day": "2024-01-14", "total_sales": "1892.45" }
]
},
"parseErrors": []
}
}
}

Anchor to Rate limitingRate limiting

The ShopifyQL API uses complexity-based rate limiting rather than fixed queries-per-second. Query complexity is determined by factors including:

  • Number of metrics requested
  • Number of dimensions in GROUP BY
  • Date range size
  • Use of comparisons and modifiers

Anchor to Next stepsNext steps

GraphQL Admin API reference

API documentation for the shopifyqlQuery endpoint.

ShopifyQL syntax reference

Complete reference for all ShopifyQL keywords, operators, and functions.

Was this page helpful?