Segment query language
Use ShopifyQL to query the GraphQL Admin API for segmentation data. Segmentation data represents data subsets, which merchants have created according to some criteria.
Segmentation data corresponds to saved search queries in the Shopify admin. For example, a merchant can save a search for customers that are subscribed to email marketing. These customers are the segment members.
The following guide explains the syntax for forming queries.
Segment queries
Anchor link to section titled "Segment queries"Segmentation queries in API requests are precise definitions of segments. The queries indicate the condition or conditions that data must satisfy to be selected. The syntax performs a similar function to WHERE statements in SQL. Query syntax acts as a filter to determine the data returned.
For example, a segment query can retrieve segment members that have left a checkout without completing their purchase in the last 30 days.
You can query a maximum of 250 segments. The maximum value that first and last arguments accept is 250.
Query syntax
Anchor link to section titled "Query syntax"Segment queries are composed of a clause, or multiple clauses, specifying facts about the segment. The clauses specify a segment by applying a condition to an attribute using an operator.
An individual clause consists of the following components:
<attribute>: The properties that define all items in a specific category.<operator>: A reserved character pattern that performs tasks such as comparisons and arithmetic operations.<condition>: The state required for data to be either selected or filtered out.
Clause format
Anchor link to section titled "Clause format"The following is the query clause format:
For example, in the following clause, email_subscription_status is the attribute, = is the operator, and SUBSCRIBED is the condition:
You can also group clauses.
An attribute's data type determines the valid operators and conditions for defining segment queries.
The following are supported attributes and their data types:
| Attribute | Data type | Description |
|---|---|---|
abandoned_checkout_date |
Date | The date of segment member's abandoned checkout. |
amount_spent |
Float | The total amount spent (all time). |
customer_cities |
Enum | The segment member's city. |
customer_countries |
Enum | The segment member's country or region (shipping/billing). |
customer_account_status |
Enum | The segment member's account status. |
customer_added_date |
Date | The date when the segment member was added as a customer on Shopify. |
customer_language |
String | The segment member's language. |
customer_tags |
Association | The segment member's assigned customer tags. Queries are invalid if the customer tag doesn't exist. |
email_domain |
String | The segment member's email domains. |
email_subscription_status |
Enum | The segment member's email subscription status. |
first_order_date |
Date | The date of the segment member's first order. |
last_order_date |
Date | The date of the segment member's last order. |
number_of_orders |
Integer | The number of the segment member's orders (all time). |
products_purchased() |
Function | The products that the segment member purchased (all time). |
product_subscription_status |
Enum | The segment member's status for product subscriptions. |
customer_regions |
Enum | The segment member's region. |