Choose a version:

sessions

The sessions schema captures online store sessions, with one row per session. Use it to report on storefront behavior, traffic, engagement, devices, geography, and the conversion funnel.

Anchor to Use casesUse cases

Traffic by geography: Group sessions and online_store_visitors by session_country or session_region to break traffic and distinct visitors down by location.
Engagement: Show pageviews, pageviews_per_session, and average_session_duration together to gauge how deeply visitors engage with the store.
Closed funnel: Use sessions_with_cart_additions, sessions_that_reached_checkout, and sessions_that_completed_checkout to trace where sessions drop out of the purchase funnel.
Conversion breakdown: Break down bounce_rate or conversion_rate by session_device_browser, session_device_os, or session_api_client to see which devices and clients convert best.

Examples

ShopifyQL

View in adminView query results in the ShopifyQL editor

FROM sessions

SHOW sessions, online_store_visitors, sessions_with_cart_additions,

sessions_that_reached_checkout, sessions_that_completed_checkout,

conversion_rate

WHERE human_or_bot_session = 'human'

TIMESERIES day WITH PERCENT_CHANGE

DURING this_month

COMPARE TO previous_period

ORDER BY day ASC

VISUALIZE sessions, conversion_rate TYPE line

Examples

Description

Track the session-to-checkout funnel day by day this month, against the prior period. This example uses [`WHERE`](/docs/api/shopifyql/latest/syntax/where) `human_or_bot_session = 'human'` to filter out bots.

ShopifyQL

FROM sessions
  SHOW sessions, online_store_visitors, sessions_with_cart_additions,
    sessions_that_reached_checkout, sessions_that_completed_checkout,
    conversion_rate
  WHERE human_or_bot_session = 'human'
  TIMESERIES day WITH PERCENT_CHANGE
  DURING this_month
  COMPARE TO previous_period
  ORDER BY day ASC
VISUALIZE sessions, conversion_rate TYPE line

Description

Rank the top 50 referrer-and-device pairs by `sessions_that_completed_checkout` since the start of last year. This example uses [`GROUP_TOTALS`](/docs/api/shopifyql/latest/syntax/with#group-total-columns) to subtotal each referrer across its devices.

ShopifyQL

FROM sessions
  SHOW sessions, conversion_rate, sessions_that_completed_checkout,
    average_session_duration
  GROUP BY referrer_source, session_device_type WITH TOTALS, GROUP_TOTALS
  HAVING sessions > 100
  SINCE last_year UNTIL today
  ORDER BY sessions_that_completed_checkout DESC
  LIMIT 50
VISUALIZE sessions_that_completed_checkout TYPE stacked_horizontal_bar

Description
Track daily `pageviews` for human sessions, with `pageviews_per_session` and `bounces`, last month. This example uses [`WHERE`](/docs/api/shopifyql/latest/syntax/where) `human_or_bot_session = 'human'` to exclude bot traffic.
ShopifyQL
```
FROM sessions
  SHOW pageviews, pageviews_per_session, bounces
  WHERE human_or_bot_session = 'human'
  TIMESERIES day
  DURING last_month
  ORDER BY day ASC
VISUALIZE pageviews TYPE line
```
Description
Rank `average_session_duration` by `session_device_type` last month. This example uses [`GROUP BY`](/docs/api/shopifyql/latest/syntax/group-by) `session_device_type` to split session duration across device types.
ShopifyQL
```
FROM sessions
  SHOW average_session_duration
  GROUP BY session_device_type WITH TOTALS
  DURING last_month
  ORDER BY average_session_duration DESC
  LIMIT 10
VISUALIZE average_session_duration TYPE horizontal_bar
```

Anchor to MetricsMetrics

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

Anchor to added_to_cart_rate added_to_cart_rate: The share of online store visits where a visitor added at least one item to the cart.

Added to cart rate = sessions with cart additions / sessions
Anchor to average_session_duration average_session_duration: Average duration, in seconds, of online store visits
Anchor to bounce_rate bounce_rate: Percentage of online store visits that ended after a single pageview

Bounce rate = bounces / sessions
Anchor to bounces bounces: Online store visits that ended after a single pageview
Anchor to checkout_conversion_rate checkout_conversion_rate: For visits that reached checkout, the share that completed a purchase.

Checkout conversion rate = sessions that completed checkout / sessions that reached checkout
Anchor to completed_checkout_rate completed_checkout_rate: For visits where a visitor added items to cart and reached checkout, the share that completed a purchase.

Completed checkout rate = sessions with cart additions that reached checkout and completed checkout / sessions with cart additions that reached checkout
Anchor to conversion_rate conversion_rate: Percentage of online store visits (sessions) that resulted in a sale

Conversion rate = sessions that completed checkout / sessions
Anchor to online_store_visitors online_store_visitors: The number of unique visitors to your online store. A visitor might have multiple sessions.
Anchor to pageviews pageviews: Total pageviews across all online store visits
Anchor to pageviews_per_session pageviews_per_session: Average number of pageviews per online store visit

Pageviews per session = pageviews / sessions
Anchor to reached_checkout_rate reached_checkout_rate: Online store visits that reached checkout relative to total visits

Reached checkout rate = sessions that reached checkout / sessions
Anchor to sessions sessions: Number of online store visits
Anchor to sessions_that_completed_checkout sessions_that_completed_checkout: Online store visits in which a purchase was completed
Anchor to sessions_that_reached_and_completed_checkout sessions_that_reached_and_completed_checkout: Online store visits in which the checkout page was reached, then purchase was completed
Anchor to sessions_that_reached_checkout sessions_that_reached_checkout: Online store visits in which the checkout page was reached
Anchor to sessions_with_cart_additions sessions_with_cart_additions: Online store visits in which a visitor added an item to cart

PERCENT

A percentage value represented as a decimal, where 0.25 represents 25%.

SECOND_DURATION

A duration measured in seconds.

INTEGER

A whole number without decimal places, used for counts, quantities, and other discrete numeric values.

DECIMAL

A precise decimal number used for calculations where fixed-point precision matters.

Anchor to DimensionsDimensions

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.

Dimensions you can use when querying FROM sessions.

Anchor to customer_id customer_id: The unique Shopify identifier for the customer associated with the online store visit. Use customer_id to break results down by customer, or use it with customer_name or customer_email to show readable labels.
Anchor to day day: The day an online store visit started.
Anchor to day_of_week day_of_week: The day of the week an online store visit started, with values Monday through Sunday.
Anchor to hour hour: The hour an online store visit started.
Anchor to hour_of_day hour_of_day: The hour of day an online store visit started, with values 0 through 23.
Anchor to human_or_bot_session human_or_bot_session: Whether an online store visit comes from a human visitor (Human) or an automated bot (Bot).
Anchor to landing_page_path landing_page_path: Values contain only the page path, such as /products/shirt, and the homepage appears as /.
Anchor to landing_page_type landing_page_type: The type of page a visitor first landed on, such as a product page, collection page, or homepage.
Anchor to landing_page_url landing_page_url: Values include the domain and page path for the page where the visit begins.
Anchor to minute minute: The minute an online store visit started.
Anchor to month month: The month an online store visit started.
Anchor to month_of_year month_of_year: The month of the year an online store visit started, with values 1 through 12.
Anchor to quarter quarter: The quarter an online store visit started.
Anchor to referrer_domain referrer_domain: Values are referring site domains such as google.com, facebook.com, or pinterest.com.
Anchor to referrer_name referrer_name: Name of the site that led to the online store visit
Anchor to referrer_path referrer_path: The page path on the external site that sent the visitor to your online store. Use referrer_path to inspect which pages on a referrer drove visits.
Anchor to referrer_site referrer_site: Site that led to the online store visit
Anchor to referrer_source referrer_source: Referrer type that led to the online store visit (organic, email, etc.)
Anchor to referrer_terms referrer_terms: The search terms from the external search referral that led to the visit, when available. Use referrer_terms to see which free-text queries brought visitors to your store.
Anchor to referrer_url referrer_url: The external page that sent the visitor to your online store. The same referring page groups together regardless of query parameters.
Anchor to rollout_ids rollout_ids <>: A session might include more than one rollout ID when the visitor is exposed to multiple active rollouts.
Anchor to rollout_treatment_ids rollout_treatment_ids <>: A session might include more than one rollout treatment ID when the visitor is exposed to multiple active treatments.
Anchor to second second: The second an online store visit started.
Anchor to session_api_client session_api_client: The storefront client used for the online store visit, such as Hydrogen, headless, or Online Store.
Anchor to session_bounced session_bounced: Values are true when the online store visit ended after a single pageview and false when it continued past the first pageview.
Anchor to session_city session_city: City from which a visitor browsed your online store
Anchor to session_country session_country: Country from which a visitor browsed your online store
Anchor to session_country_code session_country_code: Country code of the country from which a visitor browsed your online store
Anchor to session_device_browser session_device_browser: Browser used to visit your online store
Anchor to session_device_browser_version session_device_browser_version: Version number of the browser used to visit your online store
Anchor to session_device_os session_device_os: Operating system of the device used for visiting your online store
Anchor to session_device_os_version session_device_os_version: Operating system version of the visitor's device
Anchor to session_device_type session_device_type: The kind of device a visitor uses to browse your store, such as Desktop, Mobile, Tablet, or Smart TV.
Anchor to session_duration session_duration: Duration, in seconds, of the online store visit
Anchor to session_id session_id: Shopify identifier for a visit to your online store
Anchor to session_region session_region: State or province from which a visitor browsed your online store (e.g., California, Ontario)
Anchor to shop_id shop_id: The unique Shopify identifier for your store. Use shop_id with shop_name to show readable store labels.
Anchor to utm_campaign utm_campaign: The UTM campaign value on the link that led to the online store visit. Values are the campaign names you use in your tracking links. Use utm_campaign to compare traffic from specific campaigns.
Anchor to utm_content utm_content: The UTM content value on the link that led to the online store visit. Values are the content labels you set in tracking links, often used to distinguish ads, links, or creatives. Use utm_content to compare campaign variants.
Anchor to utm_medium utm_medium: The UTM medium value on the link associated with the online store visit. Values are the medium labels you set, such as email, social, or cpc. Use utm_medium to compare traffic by marketing medium.
Anchor to utm_source utm_source: The UTM source value on the link that led to the online store visit. Values are the source labels you set, such as google, newsletter, or instagram. Use utm_source to compare traffic by source.
Anchor to utm_term utm_term: The UTM term value on the link that led to the online store visit. Values are the term labels you set, often used for keywords or audience terms. Use utm_term to compare traffic by tracked term.
Anchor to week week: The week an online store visit started.
Anchor to week_of_year week_of_year: The week of the year an online store visit started, with values 1 through 53.
Anchor to year year: The year an online store visit started.
Anchor to abandoned_checkout_date abandoned_checkout_date: Date the customer most recently abandoned a cart
Anchor to customer_account_status customer_account_status: The customer's account state, with values Declined, Disabled, Enabled, and Invited.
Anchor to customer_added_date customer_added_date: The day the customer record was added, reported in your store's time zone.
Anchor to customer_created_by_app_id customer_created_by_app_id: The Shopify identifier for the app that created the customer.
Anchor to customer_email customer_email: Email address of the customer
Anchor to customer_email_domain customer_email_domain: The part of the customer's email address after the @ symbol, such as gmail.com or your company's domain.
Anchor to customer_language customer_language: Language associated with the customer
Anchor to customer_name customer_name: Full name of the customer
Anchor to shop_name shop_name: Name of your store
Anchor to customer_email_subscription_status customer_email_subscription_status: The customer's email marketing subscription state, with values such as Invalid, Not subscribed, Pending, and Subscribed.
Anchor to customer_cities customer_cities <>: All cities in the customer's history of addresses
Anchor to customer_countries customer_countries <>: All countries from the customer's address history. Values are country codes such as US, CA, GB, and AU.
Anchor to customer_regions customer_regions <>: 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.
Anchor to customer_amount_spent customer_amount_spent: The customer's all-time spend is shown in your store's currency.
Anchor to customer_last_order_date customer_last_order_date: The day the customer most recently placed an order, reported in your store's time zone.
Anchor to customer_number_of_orders customer_number_of_orders: Number of orders the customer has placed across all time
Anchor to first_order_sales_channel first_order_sales_channel: The sales channel where the customer's first order was placed, shown as a channel name such as Online Store or POS.
Anchor to customer_cohort_month customer_cohort_month: The month of the customer's first order, reported in your store's time zone.
Anchor to customer_cohort_quarter customer_cohort_quarter: The quarter of the customer's first order, reported in your store's time zone.
Anchor to customer_cohort_week customer_cohort_week: The week of the customer's first order, reported in your store's time zone.
Anchor to customer_first_order_date customer_first_order_date: The day the customer placed their first order, reported in your store's time zone.
Anchor to predicted_spend_tier predicted_spend_tier: The customer's predicted spend tier for the next year, with values Low, Medium, and High.
Anchor to customer_sms_subscription_status customer_sms_subscription_status: The customer's SMS marketing subscription state, with values such as Not subscribed, Pending, Redacted, and Subscribed.
Anchor to customer_tag customer_tag: Tag associated with the customer
Anchor to customer_tags customer_tags <>: Set of tags associated with the customer
Anchor to rfm_group rfm_group: A customer relationship label based on recency, frequency, and monetary spend. Values include Champions, Loyal, Needs attention, and At risk.
Anchor to agentic_referring_channel agentic_referring_channel: The AI agent or assistant that referred the session to your online store, with values ChatGPT, Google AI Mode and Gemini, Microsoft Copilot, and Shop.
Anchor to referring_channel referring_channel: Channel that led to an online store session
Anchor to referring_medium referring_medium: The category of referring channel that led to an online store session, such as email, social, search, or affiliate.
Anchor to referring_platform referring_platform: Platform that led to an online store session
Anchor to traffic_type traffic_type: The type of traffic that led to an online store session, with values Direct, Paid, Organic, Unknown, and Unattributed.
Anchor to channel_handle channel_handle: Name of the marketing channel or platform that drove the marketing engagement
Anchor to created_at created_at: Date and time the marketing activity was created
Anchor to ended_at ended_at: Date and time the marketing activity ended
Anchor to manage_url manage_url: URL for managing the marketing activity in the external marketing platform
Anchor to marketing_activity_channel marketing_activity_channel: The marketing channel category for the activity, such as social media, email, or search.
Anchor to marketing_activity_id marketing_activity_id: The unique Shopify identifier for the marketing activity. Use marketing_activity_id with marketing_activity_title to show readable activity labels.
Anchor to marketing_activity_status marketing_activity_status: Current status of the marketing activity (such as Active or Paused)
Anchor to marketing_activity_title marketing_activity_title: Name of the marketing activity
Anchor to marketing_api_client marketing_api_client: Unique identifier Shopify uses for the API client
Anchor to marketing_automation_id marketing_automation_id: Unique ID that Shopify uses to identify the marketing automation
Anchor to marketing_budget marketing_budget: The budget allocated to the marketing activity, in your store's currency.
Anchor to marketing_budget_type marketing_budget_type: The type of budget allocated to the marketing activity, such as daily, lifetime, or monthly.
Anchor to marketing_delivery_channel marketing_delivery_channel: Channel through which the marketing activity is delivered
Anchor to marketing_event_id marketing_event_id: Unique number for the marketing event in Shopify's system
Anchor to marketing_platform marketing_platform: The marketing platform that created the marketing activity, shown as a platform name.
Anchor to preview_url preview_url: URL for previewing the marketing activity
Anchor to remote_id remote_id: External identifier of the marketing activity on the marketing channel
Anchor to scheduled_to_end_at scheduled_to_end_at: Date and time the marketing activity is scheduled to end
Anchor to started_at started_at: Date and time the marketing activity became active
Anchor to rollout_id rollout_id: Unique identifier for the rollout that was exposed to the buyer in the session
Anchor to rollout_treatment_id rollout_treatment_id: Unique identifier for the specific treatment exposed to the session

IDENTITY

A unique identifier for a Shopify resource such as a customer, product, or order.

DAY_TIMESTAMP

A date value truncated to day precision.

DAY_OF_WEEK

A day within a week, used for weekday-based grouping and filtering.

HOUR_TIMESTAMP

A timestamp truncated to hour precision.

HOUR_OF_DAY

An hour within a day, typically represented as an integer from 0 to 23.

STRING

A sequence of characters representing text data.

MINUTE_TIMESTAMP

A timestamp truncated to minute precision.

MONTH_TIMESTAMP

A date value representing the start of a month.

MONTH_OF_YEAR

A month number within a year.

QUARTER_TIMESTAMP

A date value representing the start of a fiscal quarter.

ARRAY

A list of values. The element type appears inside angle brackets, such as ARRAY<STRING>.

SECOND_TIMESTAMP

A timestamp truncated to second precision.

BOOLEAN

A true or false value representing binary states.

WEEK_TIMESTAMP

A date value representing the start of a week.

WEEK_OF_YEAR

A week number within a year.

YEAR_TIMESTAMP

A date value representing the start of a year.

MONEY

A monetary amount representing currency values such as prices, revenue, costs, and discounts.

TIMESTAMP

A full-precision timestamp including date and time.

Anchor to MATCHES expressionsMATCHES expressions

Use these expressions inside a MATCHES filter to keep sessions rows that have at least one related record matching the parameters. Each parameter filters on a dimension or metric of the related records.

Anchor to customer.orders_placed customer.orders_placed: Orders the customer placed, filterable by order date, source app, location, order count, and spend.
Anchor to customer.products_purchased customer.products_purchased: Products the customer bought, filterable by product ID, purchase date, quantity per order, and total quantity.
Anchor to customer.shopify_email.bounced customer.shopify_email.bounced: Emails that bounced for the customer, filterable by marketing activity, bounce date, and bounce count.
Anchor to customer.shopify_email.clicked customer.shopify_email.clicked: Emails the customer clicked, filterable by marketing activity, click date, and click count.
Anchor to customer.shopify_email.delivered customer.shopify_email.delivered: Emails delivered to the customer, filterable by marketing activity, delivery date, and delivery count.
Anchor to customer.shopify_email.marked_as_spam customer.shopify_email.marked_as_spam: Emails the customer marked as spam, filterable by marketing activity, spam-report date, and spam-report count.
Anchor to customer.shopify_email.opened customer.shopify_email.opened: Emails the customer opened, filterable by marketing activity, open date, and open count.
Anchor to customer.shopify_email.unsubscribed customer.shopify_email.unsubscribed: Email unsubscribe events for the customer, filterable by marketing activity, unsubscribe date, and unsubscribe count.
Anchor to customer.store_credit_accounts customer.store_credit_accounts: Store credit accounts for the customer, filterable by balance, currency, expiry date, and most recent credit date.
Anchor to customer.storefront_event.collection_viewed customer.storefront_event.collection_viewed: Collection pages the customer viewed, filterable by collection ID, view date, and view count.
Anchor to customer.storefront_event.product_viewed customer.storefront_event.product_viewed: Product pages the customer viewed, filterable by product ID, view date, and view count.
Anchor to customer.within_distance customer.within_distance: Customers with an address within a distance of a location, filterable by coordinates and radius.

SessionsCustomerOrdersPlacedConditions

Fields you can use inside `customer.orders_placed MATCHES (...)` when querying `FROM sessions`.

amount
Filter. Amount spent per order.
```
MONEY
```
app_id
Filter. App ID associated with the order.
```
IDENTITY
```
date
Filter. Date the order was placed.
```
TIMESTAMP
```
location_id
Filter. Location ID associated with the order.
```
IDENTITY
```
count
Metric. Number of orders placed.
```
INTEGER
```
sum_amount
Metric. Amount spent in the date range.
```
MONEY
```

SessionsCustomerProductsPurchasedConditions

Fields you can use inside `customer.products_purchased MATCHES (...)` when querying `FROM sessions`.

date
Filter. Date the product(s) were purchased.
```
TIMESTAMP
```
id
Filter. Product IDs.
```
IDENTITY
```
quantity
Filter. Number purchased per order.
```
INTEGER
```
sum_quantity
Metric. Number purchased within the date range.
```
INTEGER
```

SessionsCustomerShopifyEmailBouncedConditions

Fields you can use inside `customer.shopify_email.bounced MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was bounced.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was bounced.
```
INTEGER
```

SessionsCustomerShopifyEmailClickedConditions

Fields you can use inside `customer.shopify_email.clicked MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was clicked.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was clicked.
```
INTEGER
```

SessionsCustomerShopifyEmailDeliveredConditions

Fields you can use inside `customer.shopify_email.delivered MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was delivered.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was delivered.
```
INTEGER
```

SessionsCustomerShopifyEmailMarkedAsSpamConditions

Fields you can use inside `customer.shopify_email.marked_as_spam MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was marked as spam.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was marked as spam.
```
INTEGER
```

SessionsCustomerShopifyEmailOpenedConditions

Fields you can use inside `customer.shopify_email.opened MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was opened.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was opened.
```
INTEGER
```

SessionsCustomerShopifyEmailUnsubscribedConditions

Fields you can use inside `customer.shopify_email.unsubscribed MATCHES (...)` when querying `FROM sessions`.

activity_id
Filter. Marketing activity ID of the email campaign.
```
IDENTITY
```
date
Filter. Date on which the email was unsubscribed.
```
TIMESTAMP
```
count
Metric. Exact number of times an email was unsubscribed.
```
INTEGER
```

SessionsCustomerStoreCreditAccountsConditions

Fields you can use inside `customer.store_credit_accounts MATCHES (...)` when querying `FROM sessions`.

balance
Filter. Amount available to spend.
```
FLOAT
```
currency
Filter. Currency associated with the account.
```
STRING
```
last_credit_date
Filter. Date when credits were last added.
```
TIMESTAMP
```
next_expiry_date
Filter. Date when credits expire.
```
TIMESTAMP
```

FLOAT

A floating-point number used for measurements, rates, and other continuous numeric values.

SessionsCustomerStorefrontEventCollectionViewedConditions

Fields you can use inside `customer.storefront_event.collection_viewed MATCHES (...)` when querying `FROM sessions`.

date
Filter. Date collection was viewed.
```
TIMESTAMP
```
id
Filter. Collection ID.
```
IDENTITY
```
count
Metric. Times collection was viewed.
```
INTEGER
```

SessionsCustomerStorefrontEventProductViewedConditions

Fields you can use inside `customer.storefront_event.product_viewed MATCHES (...)` when querying `FROM sessions`.

date
Filter. Date product was viewed.
```
TIMESTAMP
```
id
Filter. Product ID.
```
IDENTITY
```
count
Metric. Times product was viewed.
```
INTEGER
```

SessionsCustomerWithinDistanceConditions

Fields you can use inside `customer.within_distance MATCHES (...)` when querying `FROM sessions`.

coordinates
Filter. Latitude and longitude of location. Required.
```
GEO_COORDINATE
```
distance_km
Filter. Maximum distance from location, in kilometers. Required: provide one of the `distance_km/mi` group.
```
FLOAT
```
distance_mi
Filter. Maximum distance from location, in miles. Required: provide one of the `distance_km/mi` group.
```
FLOAT
```

GEO_COORDINATE

A geographic coordinate value.

Anchor to Related schemasRelated schemas

searches: Storewide search volume and intent for what shoppers look for during sessions.
search_conversions: Search-driven funnel volume for isolating sessions that included a search.
web_performance: Page load metrics to pair session behavior with performance signals.

Was this page helpful?