Datasets
Every PQL dataset, measure and dimension.
This is the full list of datasets, measures and dimensions you can query. MCP clients can call describe_analytics to get the live list, including whether website data is available for the store.
All money values are integer cents. All datasets also have the time dimensions.
orders
Placed orders (excludes unpaid checkouts and deleted orders). One row per order. Time is when the order was placed.
Measures
| Measure | Type | Description |
|---|---|---|
order_count | integer | Number of placed orders. |
revenue | money | Net revenue: order totals (incl. shipping) minus refunds. |
gross_sales | money | Order totals before refunds (incl. shipping, after discounts). |
product_revenue | money | Net revenue excluding shipping. |
shipping_revenue | money | Shipping charged to customers. |
discounts | money | Discounts given on orders (promotions and codes). |
refunds | money | Amount refunded. |
aov | money | Average order value (net revenue ÷ orders). |
customers | integer | Distinct customers who placed orders (guests counted by email). |
registered_buyers | integer | Distinct registered customers (accounts) who placed orders. |
new_buyers | integer | Registered customers whose first-ever order was placed in the range. |
returning_buyers | integer | Registered customers who ordered in the range and had ordered before it. |
repeat_buyer_rate | percent | Returning buyers ÷ registered buyers × 100. |
discounted_orders | integer | Orders with a discount applied. |
discount_usage_rate | percent | Discounted orders ÷ orders × 100. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
status | string | Fulfilment status of the order. Values: PENDING, PROCESSING, AWAITING_SHIPMENT, AWAITING_COLLECTION, COLLECTED, SHIPPED, DELIVERED, CANCELLED. |
payment_status | string | Payment status of the order. Values: AWAITING_PAYMENT, PAID, PARTIALLY_PAID, REFUNDED, PARTIALLY_REFUNDED. |
payment_provider | string | Payment provider used, e.g. paystack. |
delivery_method | string | Delivery or collection method name chosen at checkout. |
province | string | Delivery province (falls back to billing province). |
promotion_code | string | Promotion code entered at checkout, if any. |
customer_type | string | 'new' for a customer's first placed order, 'returning' if they ordered before, 'guest' for orders without an account. Values: new, returning, guest. |
customer_id | string | Customer account UUID (null for guests). Use with entity links. |
customer | string | Customer name (account name, or the name on the order for guests). |
customer_email | string | Customer email (account email, or the email on the order for guests). |
Plus the time dimensions.
products
Order line items on placed orders (cancelled lines excluded). Use for best sellers and product performance.
Measures
| Measure | Type | Description |
|---|---|---|
units_sold | integer | Units sold. |
item_revenue | money | Line revenue: unit price × quantity minus line discounts. |
item_discounts | money | Discounts applied to lines. |
order_count | integer | Distinct orders containing the product. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
product | string | Product name. |
product_id | string | Product UUID (use with entity links). |
product_slug | string | Product URL slug. Matches web.product_slug for blending. |
product_image_id | string | Product's primary image id (for rendering thumbnails). |
variant | string | Variant options, e.g. 'Large / Blue'. |
product_type | string | physical, digital or gift_card. Values: physical, digital, gift_card. |
order_status | string | Fulfilment status of the order. Values: PENDING, PROCESSING, AWAITING_SHIPMENT, AWAITING_COLLECTION, COLLECTED, SHIPPED, DELIVERED, CANCELLED. |
customer_type | string | 'new' for a customer's first placed order, 'returning' if they ordered before, 'guest' for orders without an account. Values: new, returning, guest. |
Plus the time dimensions.
customers
Customer accounts. Time is when the account was created. For buying behaviour use orders.customers and orders.customer_type.
Measures
| Measure | Type | Description |
|---|---|---|
new_customers | integer | Accounts created. |
marketing_subscribers | integer | Accounts created that accept marketing email. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
marketing_consent | boolean | Whether the customer accepts marketing email. |
email_verified | boolean | Whether the customer verified their email. |
Plus the time dimensions.
carts
Shopping carts. Time is the cart's last activity. A cart is abandoned if it was not converted or emptied and has been idle for over an hour.
Measures
| Measure | Type | Description |
|---|---|---|
carts | integer | Carts with activity in the period. |
converted_carts | integer | Carts that became an order. |
abandoned_carts | integer | Carts left idle for over an hour without converting. |
cart_conversion_rate | percent | Converted carts ÷ carts × 100. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
cart_owner | string | Whether the cart belongs to a signed-in customer or a guest. Values: customer, guest. |
Plus the time dimensions.
web
Storefront web traffic: pageviews, visitors, visits, bounces and custom events.
Measures
| Measure | Type | Description |
|---|---|---|
pageviews | integer | Page views. |
visitors | integer | Unique visitors (sessions). |
visits | integer | Visits (a session can have several visits). |
bounces | integer | Visits with a single pageview. |
bounce_rate | percent | Bounces ÷ visits × 100. |
avg_visit_seconds | duration | Average visit duration in seconds. |
events | integer | Custom events (group by event_name). |
event_visitors | integer | Unique visitors who triggered a custom event. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
path | string | Page path, e.g. /products/linen-shirt. |
page_title | string | Page title. |
hostname | string | Site hostname. |
referrer | string | Referring domain (null for direct traffic). |
utm_source | string | utm_source parameter. |
utm_medium | string | utm_medium parameter. |
utm_campaign | string | utm_campaign parameter. |
utm_content | string | utm_content parameter. |
utm_term | string | utm_term parameter. |
event_name | string | Custom event name (null for pageviews). Use with the events measure. |
product_slug | string | Product slug for /products/:slug pages, else null. Matches products.product_slug. |
device | string | desktop, laptop, tablet or mobile. |
browser | string | Browser name. |
os | string | Operating system. |
country | string | ISO country code, e.g. ZA. |
region | string | ISO region code, e.g. ZA-GP. |
city | string | City name. |
language | string | Browser language. |
Plus the time dimensions.
blend
Combines commerce and web data. Use derived measures below, or any measure of the orders, products and web datasets as dataset.measure (e.g. orders.revenue, web.visitors). Only conformed dimensions can be used.
Measures
| Measure | Type | Description |
|---|---|---|
conversion_rate | percent | Orders ÷ web visits × 100. |
revenue_per_visitor | money | Net revenue ÷ unique visitors. |
view_to_purchase_rate | percent | Orders containing a product ÷ visits to product pages × 100. Group by product_slug for per-product rates. |
orders.<measure> | number | Any measure of the 'orders' dataset. |
products.<measure> | number | Any measure of the 'products' dataset. |
web.<measure> | number | Any measure of the 'web' dataset. |
Dimensions
| Dimension | Type | Description |
|---|---|---|
time.hour | date | Hour (store timezone). |
time.day | date | Day (store timezone). |
time.week | date | ISO week, labelled by its Monday. |
time.month | date | Month. |
time.year | date | Year. |
time.day_of_week | integer | 1 = Monday … 7 = Sunday. |
time.hour_of_day | integer | 0–23. |
product_slug | string | Product slug. Only valid with product-level measures (products., web., view_to_purchase_rate). |
How blending works
A blend query is split into one sub-query per dataset. Each is scoped to the store and uses the same range, filters and dimensions. The rows are merged on the dimension values, and derived measures are then computed per row. A dataset with no row for a key counts as 0. A ratio with a zero denominator is null.
Only conformed dimensions (the same key on both sides) can be used: the time dimensions, and product_slug for product-level measures. Each sub-query is capped at 5,000 rows before merging.