Warning
Start with views, not cubes. For most reporting use cases, we recommend using views like Sales, ItemSales, and ModifierSales instead of querying cubes directly. Views pre-join data from multiple cubes, pre-filter to closed orders, and provide human-readable dimensions. See Metadata Discovery for details.
Use cubes directly only when you need raw, unfiltered data or fields not available in any view.
The two most commonly used cubes are Orders and PaymentAndRefunds. Understanding these cubes is essential for most reporting scenarios.
The Orders cube is the primary source for sales analytics, containing measures and dimensions for completed transactions.
- Data Freshness: ~15 minutes
- Use For: Historical analysis (yesterday and earlier), daily/weekly/monthly reports
- Critical Segment:
closed_checks(always use for sales reports)
| Measure | Type | Description |
|---|---|---|
net_sales | sum | Primary revenue metric (after discounts/returns, before tax) |
net_sales_with_tax | sum | Revenue including sales tax |
tips_amount | sum | Tips received (non-cash) |
sales_tax_amount | sum | Sales tax collected |
count | count | Number of orders |
avg_net_sales | avg | Average net sales per order |
discounts_amount | sum | Total discounts applied |
itemized_returns | sum | Returns and refunds |
| Dimension | Type | Description |
|---|---|---|
location_id | string | Location where order was placed |
sale_timestamp | time | UTC sale time |
local_date | string | Local business date (YYYY-MM-dd format) |
sales_channel_id | string | Sales channel (online, in-person) |
customer_id | string | Customer identifier |
device_id | string | Device that processed the order |
order_id | string | Unique order identifier |
| Segment | Description |
|---|---|
closed_checks | Fully paid orders (recommended for sales reports) |
open_checks | Orders awaiting payment |
awaiting_capture | Orders awaiting capture |
fully_paid | Fully paid orders |
has_tip | Orders with tips |
no_tip | Orders without tips |
has_customer | Orders with a linked customer |
{ "measures": [ "Orders.net_sales", "Orders.count", "Orders.avg_net_sales" ], "dimensions": ["Orders.location_id"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": "last 30 days" }], "segments": ["Orders.closed_checks"], "order": { "Orders.net_sales": "desc" } }
Returns sales performance by location for the last 30 days.
The PaymentAndRefunds cube provides detailed payment transaction data, including payment methods and refund information.
- Data Freshness: ~15 minutes
- Use For: Payment method analysis, refund tracking
- Relationship to Orders: One order can have multiple payments (split payments, partial payments)
| Measure | Type | Description |
|---|---|---|
total_amount | sum | Total payment amount including tips and tax |
tip_amount | sum | Tips on this payment |
count | count | Number of payment transactions |
refund_total_amount | sum | Total refunds |
| Dimension | Type | Description |
|---|---|---|
payment_id | string | Unique payment identifier |
order_id | string | Associated order identifier |
type | string | Payment type (CARD, CASH, etc.) |
reporting_timestamp | time | UTC payment time |
location_id | string | Location where payment was made |
payment_method | string | Payment method (CARD, CASH, etc.) |
{ "measures": [ "PaymentAndRefunds.total_amount", "PaymentAndRefunds.count" ], "dimensions": ["PaymentAndRefunds.type"], "timeDimensions": [{ "dimension": "PaymentAndRefunds.reporting_timestamp", "dateRange": "last 30 days" }], "order": { "PaymentAndRefunds.total_amount": "desc" } }
Returns payment totals by payment type (CARD, CASH, etc.) for the last 30 days.
| Feature | Orders | PaymentAndRefunds |
|---|---|---|
| Freshness | ~15 min | ~15 min |
| Best For | Sales analysis | Payment method analysis |
| Granularity | Order level | Payment level |
| Key Metric | Net sales | Payment amounts |
| Relationship | One order | Multiple payments per order |
- Building daily/weekly/monthly reports
- Analyzing sales trends and revenue
- You need order-level metrics
- Analyzing payment methods
- Monitoring refunds
- Understanding split payment patterns
- Comparing payment amounts to order amounts
{ "measures": ["Orders.net_sales", "Orders.count"], "dimensions": ["Orders.location_id"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-12-31"], "granularity": "month" }], "segments": ["Orders.closed_checks"] }
{ "measures": [ "PaymentAndRefunds.total_amount", "PaymentAndRefunds.count" ], "dimensions": ["PaymentAndRefunds.type"], "timeDimensions": [{ "dimension": "PaymentAndRefunds.reporting_timestamp", "dateRange": "this month" }] }