Skip to main content

About ShopifyQL for analytics

Note

The ShopifyQL API is being sunset as of version 2024-07. Please consider using alternative sources of data in the Admin GraphQL API for your use-cases, such as the Orders API, and the Web Pixels API. You can continue using ShopifyQL API on GraphQL API version 2024-04.

You can use the GraphQL Admin API to query data from a Plus merchant store using ShopifyQL. The ShopifyQL API enables you to write analytical queries to find insights in merchants' store data.

You can use the ShopifyQL API to create reporting apps that provide business insights for Plus merchants. The ShopifyQL API also enables you to export data from a Plus merchant store, so you can import the data into data warehouses.

For a complete reference of the ShopifyQL language, refer to the ShopifyQL reference.

Anchor to Access scopesAccess scopes

To use ShopifyQL, you need to request access to protected customer data in the Partner Dashboard. Your app also needs to meet certain requirements to ensure customer privacy and security. You will need to request access for protected customer data including name, email, address, and phone fields.

You also need to request access to authenticated access scopes for the following access scopes read_reports, read_customers, read_fulfillments, read_inventory, read_orders, read_products, and read_all_orders.

Anchor to How it worksHow it works

Plus Merchant stores contain data in a format that can be read by ShopifyQL. The store data is organized as a table, which has columns that contain details about the data. The following store data is available, grouped into datasets:

  • orders dataset - Available for Plus Merchants

  • products dataset - Available for Plus Merchants

  • payment attempts dataset - Available for Plus Merchants

    You can use the specific details to sort or filter store data.

    The GraphQL Admin API enables you to interact with store data using ShopifyQL. You can compose queries that sort and filter store data, so you can create interfaces or visuals that merchants can use to find patterns in their stores.

Anchor to Segment query languageSegment query language

The segment query language is a different implementation of ShopifyQL that uses a subset of ShopifyQL. The segment query language only uses the WHERE clause from ShopifyQL to filter customers by their attributes.

You can use the segment query language to create a collection of customers that are filtered out by specific criteria. Filtered customers in a collection are called "segment members", and the collections of filtered customers are called "segments". Merchants can create segments in the Shopify admin.

For a complete reference of the segment query language, refer to the segment query language reference.

Anchor to ExampleExample

The following example shows how to use shopifyqlQuery in the GraphQL Admin API to retrieve the total sales for each month from the start of the year until today.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

{
# The example below sends a ShopifyQL query to the Admin GraphQL API.
shopifyqlQuery(query: "FROM orders SHOW sum(net_sales) AS monthly_net_sales GROUP BY month SINCE -3m ORDER BY month") {
__typename
... on TableResponse {
tableData {
unformattedData
rowData
columns {
# Elements in the columns section describe which column properties you want to return.
name
dataType
displayName
}
}
}
# parseErrors specifies that you want errors returned, if there were any, and which error properties you want to return.
parseErrors {
code
message
range {
start {
line
character
}
end {
line
character
}
}
}
}
}

JSON response

{
"data": {
"shopifyqlQuery": {
"__typename": "TableResponse",
"tableData": {
"unformattedData": [
[
"2022-08-01T00:00:00-04:00",
2174587.26
],
[
"2022-09-01T00:00:00-04:00",
790295.86
],
[
"2022-10-01T00:00:00-04:00",
184255.86
],
[
"2022-11-01T00:00:00-04:00",
786740.54
]
],
"rowData": [
[
"Aug 2022",
"$2,174,587.26"
],
[
"Sep 2022",
"$790,295.86"
],
[
"Oct 2022",
"$184,255.86"
],
[
"Nov 2022",
"$786,740.54"
]
],
"columns": [
{
"name": "month",
"dataType": "month",
"displayName": "Month"
},
{
"name": "monthly_net_sales",
"dataType": "price",
"displayName": "Monthly net sales"
}
]
},
"parseErrors": null
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?