--- title: customers description: >- Reference for the ShopifyQL `customers` schema. Every metric and dimension, paired with worked example queries. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/shopifyql/latest/schemas/customers/customers' md: 'https://shopify.dev/docs/api/shopifyql/latest/schemas/customers/customers.md' api_name: shopifyql --- # customers The `customers` [schema](https://shopify.dev/docs/api/shopifyql/latest/schemas) gives you one row per customer, organized by when they first bought. Use it for customer summaries, reporting on when customers were acquired, and segmenting by lifetime spend or how recently someone ordered. ### Use cases * **New customers**: Count [`new_customer_records`](#customersmetric-propertydetail-newcustomerrecords) by month or week to report new customers by first purchase period. * **Recency**: Show [`days_since_last_order`](#customersmetric-propertydetail-dayssincelastorder) next to [`total_number_of_orders`](#customersmetric-propertydetail-totalnumberoforders) to see how recently your repeat customers last ordered. * **Value summary**: Show [`total_amount_spent_per_order`](#customersmetric-propertydetail-totalamountspentperorder) beside [`total_number_of_orders`](#customersmetric-propertydetail-totalnumberoforders) to see whether customers spend more per order or order more often. * **Distribution**: Use [`percent_of_customers`](#customersmetric-propertydetail-percentofcustomers) to size each segment as a share of your customer base instead of a raw count. * **Custom metafields**: Group [`total_amount_spent`](#customersmetric-propertydetail-totalamountspent) by a [custom metafield](#custom-metafields) to compare spend across attributes specific to your store, such as membership level. Examples ### Examples * #### ##### Description Compare monthly \`new\_customer\_records\` for the year to date against the same months last year. This example uses \[\`WITH PERCENT\_CHANGE\`]\(/docs/api/shopifyql/latest/syntax/with#percent-change-columns) for the year-over-year change column, with \[\`COMPARE TO previous\_year\`]\(/docs/api/shopifyql/latest/syntax/compare-to) setting the comparison baseline. ##### ShopifyQL ```shopifyql FROM customers SHOW new_customer_records, percent_of_customers TIMESERIES month WITH CUMULATIVE_VALUES, TOTALS, PERCENT_CHANGE DURING this_year COMPARE TO previous_year ORDER BY month ASC VISUALIZE new_customer_records TYPE bar ``` * #### ##### Description Show the 100 highest-spending customers over the last 30 days by \[\`total\_amount\_spent\`]\(#customersmetric-propertydetail-totalamountspent). This example also returns subscription status and first-order date for each top spender. ##### ShopifyQL ```shopifyql FROM customers SHOW total_number_of_orders, total_amount_spent GROUP BY customer_name, customer_email_subscription_status, customer_first_order_date WITH TOTALS SINCE startOfDay(-30d) UNTIL today ORDER BY total_amount_spent DESC LIMIT 100 VISUALIZE total_amount_spent TYPE horizontal_bar ``` * #### ##### Description Compare \`total\_amount\_spent\_per\_order\` and \`days\_since\_last\_order\` over the last 30 days against the 30 days before. This example pairs \[\`SINCE startOfDay(-30d) UNTIL today\`]\(/docs/api/shopifyql/latest/syntax/since-until-during) with \[\`COMPARE TO previous\_period\`]\(/docs/api/shopifyql/latest/syntax/compare-to) to benchmark each metric against the previous 30 days. ##### ShopifyQL ```shopifyql FROM customers SHOW total_amount_spent_per_order, days_since_last_order WITH PERCENT_CHANGE SINCE startOfDay(-30d) UNTIL today COMPARE TO previous_period ``` * #### ##### Description Break down \`new\_customer\_records\` by \`customer\_email\_subscription\_status\` last month. This example uses \[\`GROUP BY\`]\(/docs/api/shopifyql/latest/syntax/group-by) \`customer\_email\_subscription\_status\` to compare subscribed and unsubscribed customers. ##### ShopifyQL ```shopifyql FROM customers SHOW new_customer_records GROUP BY customer_email_subscription_status WITH TOTALS DURING last_month ORDER BY new_customer_records DESC VISUALIZE new_customer_records TYPE horizontal_bar ``` *** ## Metrics Counts and calculations that let you track key business indicators. Metrics show up as the columns when queried. Metrics you can use when querying `FROM customers`. * **days\_​since\_​last\_​order** **DAY\_DURATION** Number of days since the customer's last order * **new\_​customer\_​records** **INTEGER** Number of customers whose first purchase is within the given time period * **percent\_​of\_​customers** **PERCENT** The share of all customers represented by each result group. * **total\_​amount\_​spent** **MONEY** The combined lifetime spend for the customers returned by your query. * **total\_​amount\_​spent\_​per\_​order** **MONEY** The average lifetime spend per order across the customers returned by your query. `Total amount spent per order = total amount spent / total customer orders` * **total\_​number\_​of\_​orders** **INTEGER** The combined number of orders placed across all time by the customers returned by your query. ### DAY\_DURATION A duration measured in days. ```ts ``` ### INTEGER A whole number without decimal places, used for counts, quantities, and other discrete numeric values. ```ts ``` ### PERCENT A percentage value represented as a decimal, where 0.25 represents 25%. ```ts ``` ### MONEY A monetary amount representing currency values such as prices, revenue, costs, and discounts. ```ts ``` *** ## Dimensions Attributes of your data that let you look more granularly at aspects of the data. Group and filter by dimensions to shape the rows your query returns. **Note:** You can also group by or filter on [custom metafields](#custom-metafields). Dimensions you can use when querying `FROM customers`. * **customer\_​id** **IDENTITY** The unique Shopify identifier for the customer. Use [`customer_id`](#customersdimension-propertydetail-customerid) with [`customer_name`](#customersdimension-propertydetail-customername) or [`customer_email`](#customersdimension-propertydetail-customeremail) to show readable labels. * **day** **DAY\_TIMESTAMP** Day the customer placed their first order * **day\_​of\_​week** **DAY\_OF\_WEEK** The weekday a customer placed their first order, with values Monday through Sunday. * **first\_​order\_​date** **DAY\_TIMESTAMP** Date of the customer's first order * **hour** **HOUR\_TIMESTAMP** Hour the customer placed their first order * **hour\_​of\_​day** **HOUR\_OF\_DAY** The hour of day a customer placed their first order, with values 0 through 23. * **last\_​order\_​date** **DAY\_TIMESTAMP** Date of the customer's last order * **minute** **MINUTE\_TIMESTAMP** Minute the customer placed their first order * **month** **MONTH\_TIMESTAMP** Month the customer placed their first order * **month\_​of\_​year** **MONTH\_OF\_YEAR** The month of year a customer placed their first order, with values 1 through 12. * **quarter** **QUARTER\_TIMESTAMP** Quarter the customer placed their first order * **second** **SECOND\_TIMESTAMP** Second the customer placed their first order * **shop\_​id** **IDENTITY** The unique Shopify identifier for your store. Use [`shop_id`](#customersdimension-propertydetail-shopid) with [`shop_name`](#customersdimension-propertydetail-shopname) to show readable store labels. * **week** **WEEK\_TIMESTAMP** Week the customer placed their first order * **week\_​of\_​year** **WEEK\_OF\_YEAR** The week of year a customer placed their first order, with values 1 through 53. * **year** **YEAR\_TIMESTAMP** Year the customer placed their first order * **abandoned\_​checkout\_​date** **DAY\_TIMESTAMP** Date the customer most recently abandoned a cart * **customer\_​account\_​status** **STRING** The customer's account state, with values Declined, Disabled, Enabled, and Invited. * **customer\_​added\_​date** **DAY\_TIMESTAMP** The day the customer record was added, reported in your store's time zone. * **customer\_​created\_​by\_​app\_​id** **IDENTITY** The Shopify identifier for the app that created the customer. * **customer\_​email** **STRING** Email address of the customer * **customer\_​email\_​domain** **STRING** The part of the customer's email address after the @ symbol, such as gmail.com or your company's domain. * **customer\_​language** **STRING** Language associated with the customer * **customer\_​name** **STRING** Full name of the customer * **shop\_​name** **STRING** Name of your store * **customer\_​email\_​subscription\_​status** **STRING** The customer's email marketing subscription state, with values such as Invalid, Not subscribed, Pending, and Subscribed. * **customer\_​cohort\_​month** **MONTH\_TIMESTAMP** The month of the customer's first order, reported in your store's time zone. * **customer\_​cohort\_​quarter** **QUARTER\_TIMESTAMP** The quarter of the customer's first order, reported in your store's time zone. * **customer\_​cohort\_​week** **WEEK\_TIMESTAMP** The week of the customer's first order, reported in your store's time zone. * **customer\_​first\_​order\_​date** **DAY\_TIMESTAMP** The day the customer placed their first order, reported in your store's time zone. * **customer\_​cities** **ARRAY\** All cities in the customer's history of addresses * **customer\_​countries** **ARRAY\** All countries from the customer's address history. Values are country codes such as US, CA, GB, and AU. * **customer\_​regions** **ARRAY\** All states or provinces from the customer's address history. Values are region codes such as US-CA, US-NY, CA-ON, and GB-ENG. * **customer\_​city** **STRING** Individual cities in the customer's history of addresses * **customer\_​country** **STRING** A country from the customer's address history. Values are country codes such as US, CA, GB, and AU. * **customer\_​region** **STRING** A state or province from the customer's address history. Values are region codes such as US-CA, US-NY, CA-ON, and GB-ENG. * **customer\_​amount\_​spent** **MONEY** The customer's all-time spend is shown in your store's currency. * **customer\_​last\_​order\_​date** **DAY\_TIMESTAMP** The day the customer most recently placed an order, reported in your store's time zone. * **customer\_​number\_​of\_​orders** **INTEGER** Number of orders the customer has placed across all time * **predicted\_​spend\_​tier** **STRING** The customer's predicted spend tier for the next year, with values Low, Medium, and High. * **customer\_​sms\_​subscription\_​status** **STRING** The customer's SMS marketing subscription state, with values such as Not subscribed, Pending, Redacted, and Subscribed. * **customer\_​tag** **STRING** Tag associated with the customer * **customer\_​tags** **ARRAY\** Set of tags associated with the customer * **rfm\_​group** **STRING** A customer relationship label based on recency, frequency, and monetary spend. Values include Champions, Loyal, Needs attention, and At risk. ### IDENTITY A unique identifier for a Shopify resource such as a customer, product, or order. ```ts ``` ### DAY\_TIMESTAMP A date value truncated to day precision. ```ts ``` ### DAY\_OF\_WEEK A day within a week, used for weekday-based grouping and filtering. ```ts ``` ### HOUR\_TIMESTAMP A timestamp truncated to hour precision. ```ts ``` ### HOUR\_OF\_DAY An hour within a day, typically represented as an integer from 0 to 23. ```ts ``` ### MINUTE\_TIMESTAMP A timestamp truncated to minute precision. ```ts ``` ### MONTH\_TIMESTAMP A date value representing the start of a month. ```ts ``` ### MONTH\_OF\_YEAR A month number within a year. ```ts ``` ### QUARTER\_TIMESTAMP A date value representing the start of a fiscal quarter. ```ts ``` ### SECOND\_TIMESTAMP A timestamp truncated to second precision. ```ts ``` ### WEEK\_TIMESTAMP A date value representing the start of a week. ```ts ``` ### WEEK\_OF\_YEAR A week number within a year. ```ts ``` ### YEAR\_TIMESTAMP A date value representing the start of a year. ```ts ``` ### STRING A sequence of characters representing text data. ```ts ``` ### ARRAY A list of values. The element type appears inside angle brackets, such as ARRAY\. ```ts ``` *** ## Custom metafields Custom metafields act as dimensions that are specific to your store. You can group by or filter on them for customers. Reference a metafield as `customer.metafields..`. To query a metafield, its definition must have the [`analyticsQueryable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#analytics-queryable) capability enabled. [Learn more about metafields](https://shopify.dev/docs/apps/build/metafields). Examples ### Examples * #### ##### Description Compare \[\`total\_amount\_spent\`]\(#customersmetric-propertydetail-totalamountspent) across the values of a \`membership\_level\` metafield on customers, keeping the top 20. \[\`IS NOT NULL\`]\(/docs/api/shopifyql/latest/syntax/where) drops customers that don't have the metafield set. ##### ShopifyQL ```shopifyql FROM customers SHOW total_amount_spent WHERE customer.metafields.custom.membership_level IS NOT NULL GROUP BY customer.metafields.custom.membership_level WITH TOTALS ORDER BY total_amount_spent DESC LIMIT 20 VISUALIZE total_amount_spent TYPE horizontal_bar ``` * #### ##### Description Track monthly \[\`new\_customer\_records\`]\(#customersmetric-propertydetail-newcustomerrecords) for customers that a \`wholesale\_account\` metafield marks as wholesale. This example filters on a boolean customer metafield with \[\`WHERE\`]\(/docs/api/shopifyql/latest/syntax/where), then buckets the results with \[\`TIMESERIES\`]\(/docs/api/shopifyql/latest/syntax/timeseries). ##### ShopifyQL ```shopifyql FROM customers SHOW new_customer_records WHERE customer.metafields.custom.wholesale_account IS TRUE TIMESERIES month WITH TOTALS DURING last_year ORDER BY month ASC VISUALIZE new_customer_records TYPE bar ``` *** ## MATCHES expressions Use these expressions inside a [`MATCHES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/where#matches) filter to keep `customers` rows that have at least one related record matching the parameters. Each parameter filters on a dimension or metric of the related records. The unprefixed `storefront.collection_viewed` and `storefront.product_viewed` are available only on `customers`. From other schemas, use the `customer.storefront_event.*` forms. * **orders\_​placed** **CustomersOrdersPlacedConditions** Orders the customer placed, filterable by order date, source app, location, order count, and spend. * **products\_​purchased** **CustomersProductsPurchasedConditions** Products the customer bought, filterable by product ID, purchase date, quantity per order, and total quantity. * **shopify\_​email.​bounced** **CustomersShopifyEmailBouncedConditions** Emails that bounced for the customer, filterable by marketing activity, bounce date, and bounce count. * **shopify\_​email.​clicked** **CustomersShopifyEmailClickedConditions** Emails the customer clicked, filterable by marketing activity, click date, and click count. * **shopify\_​email.​delivered** **CustomersShopifyEmailDeliveredConditions** Emails delivered to the customer, filterable by marketing activity, delivery date, and delivery count. * **shopify\_​email.​marked\_​as\_​spam** **CustomersShopifyEmailMarkedAsSpamConditions** Emails the customer marked as spam, filterable by marketing activity, spam-report date, and spam-report count. * **shopify\_​email.​opened** **CustomersShopifyEmailOpenedConditions** Emails the customer opened, filterable by marketing activity, open date, and open count. * **shopify\_​email.​unsubscribed** **CustomersShopifyEmailUnsubscribedConditions** Email unsubscribe events for the customer, filterable by marketing activity, unsubscribe date, and unsubscribe count. * **store\_​credit\_​accounts** **CustomersStoreCreditAccountsConditions** Store credit accounts for the customer, filterable by balance, currency, expiry date, and most recent credit date. * **storefront.​collection\_​viewed** **CustomersStorefrontCollectionViewedConditions** Collection pages the customer viewed, filterable by collection ID, view date, and view count. * **storefront.​product\_​viewed** **CustomersStorefrontProductViewedConditions** Product pages the customer viewed, filterable by product ID, view date, and view count. * **storefront\_​event.​collection\_​viewed** **CustomersStorefrontEventCollectionViewedConditions** Collection pages the customer viewed, filterable by collection ID, view date, and view count. * **storefront\_​event.​product\_​viewed** **CustomersStorefrontEventProductViewedConditions** Product pages the customer viewed, filterable by product ID, view date, and view count. * **within\_​distance** **CustomersWithinDistanceConditions** Customers with an address within a distance of a location, filterable by coordinates and radius. ### CustomersOrdersPlacedConditions Fields you can use inside \`orders\_placed MATCHES (...)\` when querying \`FROM customers\`. * amount Filter. Amount spent per order. ```ts MONEY ``` * app\_id Filter. App ID associated with the order. ```ts IDENTITY ``` * date Filter. Date the order was placed. ```ts TIMESTAMP ``` * location\_id Filter. Location ID associated with the order. ```ts IDENTITY ``` * count Metric. Number of orders placed. ```ts INTEGER ``` * sum\_amount Metric. Amount spent in the date range. ```ts MONEY ``` ### TIMESTAMP A full-precision timestamp including date and time. ```ts ``` ### CustomersProductsPurchasedConditions Fields you can use inside \`products\_purchased MATCHES (...)\` when querying \`FROM customers\`. * date Filter. Date the product(s) were purchased. ```ts TIMESTAMP ``` * id Filter. Product IDs. ```ts IDENTITY ``` * quantity Filter. Number purchased per order. ```ts INTEGER ``` * sum\_quantity Metric. Number purchased within the date range. ```ts INTEGER ``` ### CustomersShopifyEmailBouncedConditions Fields you can use inside \`shopify\_email.bounced MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was bounced. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was bounced. ```ts INTEGER ``` ### CustomersShopifyEmailClickedConditions Fields you can use inside \`shopify\_email.clicked MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was clicked. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was clicked. ```ts INTEGER ``` ### CustomersShopifyEmailDeliveredConditions Fields you can use inside \`shopify\_email.delivered MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was delivered. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was delivered. ```ts INTEGER ``` ### CustomersShopifyEmailMarkedAsSpamConditions Fields you can use inside \`shopify\_email.marked\_as\_spam MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was marked as spam. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was marked as spam. ```ts INTEGER ``` ### CustomersShopifyEmailOpenedConditions Fields you can use inside \`shopify\_email.opened MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was opened. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was opened. ```ts INTEGER ``` ### CustomersShopifyEmailUnsubscribedConditions Fields you can use inside \`shopify\_email.unsubscribed MATCHES (...)\` when querying \`FROM customers\`. * activity\_id Filter. Marketing activity ID of the email campaign. ```ts IDENTITY ``` * date Filter. Date on which the email was unsubscribed. ```ts TIMESTAMP ``` * count Metric. Exact number of times an email was unsubscribed. ```ts INTEGER ``` ### CustomersStoreCreditAccountsConditions Fields you can use inside \`store\_credit\_accounts MATCHES (...)\` when querying \`FROM customers\`. * balance Filter. Amount available to spend. ```ts FLOAT ``` * currency Filter. Currency associated with the account. ```ts STRING ``` * last\_credit\_date Filter. Date when credits were last added. ```ts TIMESTAMP ``` * next\_expiry\_date Filter. Date when credits expire. ```ts TIMESTAMP ``` ### FLOAT A floating-point number used for measurements, rates, and other continuous numeric values. ```ts ``` ### CustomersStorefrontCollectionViewedConditions Fields you can use inside \`storefront.collection\_viewed MATCHES (...)\` when querying \`FROM customers\`. * date Filter. Date collection was viewed. ```ts TIMESTAMP ``` * id Filter. Collection ID. ```ts IDENTITY ``` * count Metric. Times collection was viewed. ```ts INTEGER ``` ### CustomersStorefrontProductViewedConditions Fields you can use inside \`storefront.product\_viewed MATCHES (...)\` when querying \`FROM customers\`. * date Filter. Date product was viewed. ```ts TIMESTAMP ``` * id Filter. Product ID. ```ts IDENTITY ``` * count Metric. Times product was viewed. ```ts INTEGER ``` ### CustomersStorefrontEventCollectionViewedConditions Fields you can use inside \`storefront\_event.collection\_viewed MATCHES (...)\` when querying \`FROM customers\`. * date Filter. Date collection was viewed. ```ts TIMESTAMP ``` * id Filter. Collection ID. ```ts IDENTITY ``` * count Metric. Times collection was viewed. ```ts INTEGER ``` ### CustomersStorefrontEventProductViewedConditions Fields you can use inside \`storefront\_event.product\_viewed MATCHES (...)\` when querying \`FROM customers\`. * date Filter. Date product was viewed. ```ts TIMESTAMP ``` * id Filter. Product ID. ```ts IDENTITY ``` * count Metric. Times product was viewed. ```ts INTEGER ``` ### CustomersWithinDistanceConditions Fields you can use inside \`within\_distance MATCHES (...)\` when querying \`FROM customers\`. * coordinates Filter. Latitude and longitude of location. Required. ```ts GEO_COORDINATE ``` * distance\_km Filter. Maximum distance from location, in kilometers. Required: provide one of the \`distance\_km/mi\` group. ```ts FLOAT ``` * distance\_mi Filter. Maximum distance from location, in miles. Required: provide one of the \`distance\_km/mi\` group. ```ts FLOAT ``` ### GEO\_COORDINATE A geographic coordinate value. ```ts ``` *** ## Related schemas * [`sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/sales): Sale-level data when you need to attribute revenue back to specific customers. * [`profitability`](https://shopify.dev/docs/api/shopifyql/latest/schemas/orders/profitability): Pairs customer spend with cost to show margin per buyer. ***