Measures and Dimensions Reference

A query in Upstack has three parts. Measures are the numbers, such as orders.net_revenue. Dimensions break a measure into rows, such as one row per utm_source. Filters narrow the data first, such as only new customer orders. The ids on this page are the ones the analytics API and the CLI accept.

Measures

Every measure id starts with a group prefix. The group tells you where the data comes from and which dimensions can break it down.

Prefix	What it measures	Example ids	Reference
`orders.`	Shopify orders: revenue, AOV, order and customer counts, refunds and discounts, costs, contribution margin, and ROAS, MER and RAAD against your ad spend	`orders.net_revenue`, `orders.count`, `orders.new_customers`, `orders.cm2`, `orders.total_roas`	Orders metrics
`tracked.`	Events collected by the Upstack Pixel and server-side sources: page views, add to carts, purchases, funnel rates, and traffic quality	`tracked.page_views`, `tracked.add_to_carts`, `tracked.purchases`, `tracked.session_conversion_rate`	Funnel metrics
`channel.`	Spend and platform-reported results added up across all your connected ad accounts. Cost per action counts spend only from platforms that report that action	`channel.spend`, `channel.roas`, `channel.cpa`	Blended metrics
`meta.`, `google.`, `tiktok.`	Spend and results as one ad platform reports them	`meta.spend`, `google.spend`, `tiktok.spend`	Advertising metrics
`emq.`	Meta Event Match Quality for your datasets	`emq.score`	EMQ metrics
`core.`	Conversions in event attribution reports. Not available in custom dashboards	`core.conversions`, `core.conversion_value`

To see every measure you can pick, with its title and formula, call List available measures or run upstack measures. Need a number that isn’t there? Build it from these ids with Custom Measures. Money measures are converted to your reporting currency. See Reporting currency.

Dimensions

Send up to five dimension ids in dimensions on Run an analytics query. In a dashboard view, Group by offers Customer type and Order type. A dimension only breaks down measures whose data has that field. The Breaks down column says which. Pick dimensions that match your measures: a dimension the measure doesn’t have won’t split it, and with granularity none the measure can fail and come back with success: false.

Traffic dimensions

Dimension id	What it holds	Breaks down
`utm_source`	UTM source of the visit	`tracked.`, `orders.`
`utm_medium`	UTM medium	`tracked.`, `orders.`
`utm_campaign`	UTM campaign	`tracked.`, `orders.`
`utm_term`	UTM term	`tracked.`, `orders.`
`utm_content`	UTM content	`tracked.`, `orders.`
`click_network`	Ad network matched from the click ID on the landing page URL	`tracked.`, `orders.`
`referrer_medium`	Kind of referring site	`tracked.`, `orders.`
`referrer_source`	Referring site	`tracked.`
`discount_code`	Discount code used. Orders without a code are left out of the breakdown	`tracked.`, `orders.`

Visitor dimensions

Dimension id	What it holds	Breaks down
`device_type`	Device category from the browser’s user agent	`tracked.`
`browser`	Browser name	`tracked.`
`is_mobile`	Whether the device is a mobile device	`tracked.`
`country`	Country from IP geolocation	`tracked.`
`province`	State or region from IP geolocation	`tracked.`
`city`	City from IP geolocation	`tracked.`
`carrier_name`	Mobile carrier from the IP address	`tracked.`

Page and event dimensions

Dimension id	What it holds	Breaks down
`path`	Page path	`tracked.`
`event_name`	Event name, such as `purchase`	`tracked.`
`is_webhook_fired`	`1` when the event came server-side directly from Shopify, `0` otherwise	`tracked.`

Order dimensions

Dimension id	What it holds	Breaks down
`customer_type`	New or returning customer order. See Customer type	`orders.`
`order_type`	One-time or subscription order. See Order type	`orders.`

Ad dimensions

Dimension id	What it holds	Breaks down
`ad_source`	Ad platform	`channel.`, `meta.`, `google.`, `tiktok.`
`ad_account`	Ad account	`channel.`, `meta.`, `google.`, `tiktok.`
`campaign`	Campaign	`channel.`, `meta.`, `google.`, `tiktok.`
`adset`	Ad set or ad group	`channel.`, `meta.`, `google.`, `tiktok.`
`ad`	Ad	`channel.`, `meta.`, `google.`, `tiktok.`

EMQ dimensions

emq.dataset_id, emq.event_name and emq.event_source break down every emq. measure. emq.identifier, emq.issue_category, emq.dedupe_key, emq.data_freshness, emq.diagnostic_name and emq.severity each break down the EMQ measures they belong to, such as emq.diagnostic_name for diagnostics counts.

Other dimension ids

upstack dimensions also lists ids such as device_model, country_code and financial_status. The API accepts them, but no measure in the measure picker breaks down by them. Attribution queries take their own dimension: utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_adset, utm_ad, utm_source_medium or utm_source_campaign.

Customer type

customer_type splits Shopify order measures into first orders and repeat orders. You can group by it as a dimension, or filter on it with the Customer type filter (field id orders.customer_type).

Value	Meaning
`new_customer`	The customer’s first order: their earliest non-cancelled order Upstack has for your store, matched on the Shopify customer ID. Each customer has exactly one.
`returning_customer`	Any other order from a Shopify customer who already has a first order on record.
`not_defined`	Shown only when grouping. The order has no new or returning flag, for example because it has no Shopify customer attached.

The classification looks at the customer’s whole order history, not the date range you selected. The filter isn’t offered on LTV cohort views, where every cohort is already made of new customers.

Order type

order_type splits Shopify orders by subscription status, based on the order’s tags and source. Group by it, or filter with the Order type filter (field id orders.order_type).

Value	Label in the app	An order gets it when
`subscription_recurring_order`	Subscription recurring order	Its source is `subscription_contract` or `subscription_contract_checkout_one`, or its tags contain `Subscription Recurring Order`
`subscription_first_order`	Subscription first order	Its tags contain `Subscription First Order`, `First Subscription`, `subscription_start` or `subscription checkout`
`one_time_order`	One-time order	Neither of the above

If your subscription app tags its orders differently, those orders count as one-time orders.

Filters

A filter field narrows the data before measures are calculated. Each field works in some places and not others, listed under Used in. List filter fields and upstack filters return the same set with every supported operator.

Field id	Label	Values	Used in
`orders.source_name`	Order source	Text, such as `web` or `pos`	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`orders.customer_type`	Customer type	`new_customer`, `returning_customer`	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`orders.order_type`	Order type	`one_time_order`, `subscription_first_order`, `subscription_recurring_order`	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`orders.value`	Order value	Number, compared with the order total	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`orders.payment_gateway`	Payment gateway	Text	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`orders.tags`	Order tags	List of tags, matched with `array_includes`, `array_includes_all` or `array_includes_any`	`query_measures`, `query_ads`, `attribution`, `cohort_analysis`, `products_report`
`events.event_name`	Event name	Text	`query_measures`, `query_ads`
`channel.resource_source`	Source	Ad platform	`query_measures`, `query_ads`, `channel_details`
`channel.account_id`, `channel.campaign_id`, `channel.adset_id`, `channel.ad_id`	Account ID, Campaign ID, Adset ID, Ad ID	IDs	`query_measures`, `query_ads`, `channel_details`
`channel.account_name`, `channel.campaign_name`, `channel.adset_name`, `channel.ad_name`	Account name, Campaign name, Adset name, Ad name	Text	`query_measures`, `query_ads`
`channel.resource_name`, `channel.resource_status`, `channel.resource_configured_status`, `channel.resource_effective_status`	Name, Status, Configured status, Effective status	Text or platform status	`query_ads`, `channel_details`
`attribution.utm_source`, `attribution.utm_medium`, `attribution.utm_campaign`, `attribution.utm_adset`, `attribution.utm_term`, `attribution.utm_ad`, `attribution.utm_content`	UTM source, UTM medium, and so on	Text	`attribution`
`emq.dataset_id`, `emq.event_name`, `emq.diagnostic_name`	Dataset ID, Event name, Diagnostic name	IDs or text	`query_measures`, `query_ads`, `emq_analytics`

query_measures is Run an analytics query and custom dashboards. The other values are listed under FilterContext in the API reference.

Combining measures and dimensions

Goal	Measure	Dimension
Revenue by traffic source	`orders.net_revenue`	`utm_source`
New vs. returning revenue	`orders.net_revenue`	`customer_type`
Subscription vs. one-time orders	`orders.count`	`order_type`
Purchases by device	`tracked.purchases`	`device_type`
Visitors by country	`tracked.visitors`	`country`
Spend by campaign	`channel.spend`	`campaign`

Query Guide

Build queries, set date ranges, and apply filters.

Custom Measures

Define your own metrics from a formula over these measures.

​Measures

​Dimensions

​Traffic dimensions

​Visitor dimensions

​Page and event dimensions

​Order dimensions

​Ad dimensions

​EMQ dimensions

​Other dimension ids

​Customer type

​Order type

​Filters

​Combining measures and dimensions