VOOZH about

URL: https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api

⇱ ShopifyQL with the GraphQL Admin API

Skip to main content

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:

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

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:

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

GraphQL Admin API reference

API documentation for the shopifyqlQuery endpoint.

ShopifyQL syntax reference

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

ShopifyQL syntax reference

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

Was this page helpful?