Views are the recommended way to query the Reporting API. They pre-join data from multiple cubes, pre-filter to relevant records, and expose human-readable dimensions like location_name instead of raw IDs.
Note
For most reporting tasks, start with a view. Use cubes directly only when you need raw, unfiltered data or fields not exposed through any view.
| View | Measures | Dimensions | Segments | Primary Use Case |
|---|---|---|---|---|
| Sales | 23 | 23 | 7 | Order-level sales, revenue, tips, discounts |
| ItemSales | 37 | 42 | 5 | Item-level sales with discounts, modifiers, combos |
| ModifierSales | 10 | 18 | 2 | Modifier-level sales analysis |
| KDS | 22 | 42 | 4 | Kitchen ticket and item prep times |
| SpeedOfService | 25 | 21 | 8 | Order entry/service time + sales + KDS metrics |
| PeerBenchmarkHourlySales | 4 | 9 | 0 | Hourly sales distribution vs peers |
| PeerBenchmarkOrderValue | 4 | 7 | 0 | Average order value benchmarking vs peers |
| PeerBenchmarkSalesTrend | 10 | 7 | 0 | Year-over-year sales growth vs peers |
The Sales view is the recommended starting point for most sales reporting. It reports only on closed (fully settled) orders and includes dimensions for location, channel, customer, and employee analysis.
Note
No segment needed. The Sales view automatically filters to closed orders — you don't need to add segments: ["Orders.closed_checks"] like you would when querying the Orders cube directly.
| Measure | Type | Description |
|---|---|---|
top_line_product_sales | sum | Gross sales (default "sales" measure — use this unless you need a specific qualifier) |
net_sales | sum | Top-line sales minus discounts and itemized returns |
total_collected_amount | sum | Total collected from customer (includes tips, tax, gift cards, returns) |
total_sales_amount | sum | Total sales amount for the order |
order_count | count | Number of orders |
avg_net_sales | avg | Average net sales per order |
avg_top_line_product_sales | avg | Average gross sales per order |
avg_total_collected | avg | Average total collected per order |
avg_total_sales | avg | Average total sales per order |
discounts_amount | sum | Total discounts applied |
comps_amount | sum | Total comps applied |
itemized_returns | sum | Itemized returns (excludes refunds, discounts, comps) |
refunds_by_amount_amount | sum | Non-itemized refunds (money given back) |
tips_amount | sum | Total tips (excludes cash tips and auto-gratuity) |
sales_tax_amount | sum | Sales tax collected |
gift_card_sales_amount | sum | Revenue from Square Gift Card sales (not purchases made with gift cards) |
top_line_product_sales_count | sum | Orders contributing to gross sales |
net_sales_count | sum | Orders contributing to net sales |
total_sales_count | sum | Orders contributing to total sales |
location_count | count | Unique locations |
unique_customers | countDistinct | Unique customers |
customer_visit_count | count | Customer visits (purchases) |
employee_count | count | Unique team members |
| Dimension | Type | Description |
|---|---|---|
location_name | string | Location display name |
location_id | string | Location identifier |
local_reporting_timestamp | time | Timestamp in location's local timezone |
local_date | string | Date in YYYY-MM-dd format, local timezone |
local_day_of_week | string | Day of week name, local timezone |
local_hour | number | Hour of day (0-23), local timezone |
channel_name | string | Sales channel display name |
channel_category | string | High-level channel category |
customer_type | string | NEW or RETURNING |
customer_id | string | Customer identifier |
employee_full_name | string | Team member full name |
order_id | string | Order identifier |
merchant_id | string | Merchant identifier |
distinct_item_names | string | Comma-separated item names on order |
item_quantities | string | Items with quantities (e.g., "Beer x 2, Burger x 1") |
distinct_item_count | number | Number of distinct line items |
had_loyalty_at_purchase | boolean | Whether customer had active loyalty |
| Segment | Description |
|---|---|
in_store | In-store sales channels |
online | Online sales channels |
has_tip | Orders with tips |
no_tip | Orders without tips |
has_customer | Orders linked to a customer |
new_customers | First-time customers only |
returning_customers | Returning customers only |
{ "measures": ["Sales.net_sales", "Sales.order_count"], "dimensions": ["Sales.location_name"], "timeDimensions": [{ "dimension": "Sales.local_reporting_timestamp", "dateRange": "last 30 days", "granularity": "day" }] }
{ "measures": ["Sales.net_sales", "Sales.order_count"], "timeDimensions": [{ "dimension": "Sales.local_reporting_timestamp", "dateRange": "last 7 days" }], "segments": ["Sales.online"] }
The ItemSales view provides item-level sales data with related discounts, modifiers, and order-level metrics. Like the Sales view, it reports only on closed orders.
| Measure | Type | Description |
|---|---|---|
count | count | Item transaction count |
items_sold_count | sum | Items sold (handles fractional quantities) |
items_returned_count | sum | Items returned |
net_quantity | sum | Net quantity (sales minus returns) |
item_net_sales | sum | Net item sales |
item_net_sales_with_tax | sum | Net item sales including tax |
sales_gross_amount | sum | Gross sales for sold items |
returns_gross_amount | sum | Gross return amount (negative) |
avg_item_gross_sales | avg | Average gross sales per item |
avg_item_net_sales | avg | Average net sales per item |
discount_amount | sum | Net discount amount |
unique_customers | countDistinct | Unique customers |
| Dimension | Type | Description |
|---|---|---|
item_name | string | Item name |
category_name | string | Item category |
item_variation_name | string | Item variation name |
item_sku | string | SKU |
location_name | string | Location display name |
local_reporting_timestamp | time | Local timestamp |
local_date | string | Local date (YYYY-MM-dd) |
modifier_name | string | Modifier name |
modifier_list_name | string | Modifier list/group name |
discount_name | string | Discount or comp name |
channel_name | string | Sales channel |
customer_type | string | NEW or RETURNING |
transaction_type | string | SALE or RETURN |
payment_method | string | Payment method |
| Segment | Description |
|---|---|
sales | Sales transactions only |
returns | Return transactions only |
has_customer | Orders with a linked customer |
new_customers | First-time customers |
returning_customers | Returning customers |
{ "measures": ["ItemSales.items_sold_count", "ItemSales.item_net_sales"], "dimensions": ["ItemSales.item_name", "ItemSales.category_name"], "timeDimensions": [{ "dimension": "ItemSales.local_reporting_timestamp", "dateRange": "last 30 days" }], "order": { "ItemSales.item_net_sales": "desc" }, "limit": 20 }
The ModifierSales view provides modifier-level sales data for closed orders.
Note
Important: modifier_name is not unique across modifier lists. Always group by both modifier_list_name and modifier_name when analyzing individual modifiers. For example, "Large" could exist in both a "Size" list and a "Drink Size" list.
| Measure | Type | Description |
|---|---|---|
orders_count | countDistinct | Unique orders with modifiers |
quantity_sold | sum | Modifiers sold |
quantity_returned | sum | Modifiers returned |
net_quantity | sum | Net quantity (sales minus returns) |
gross_sales | sum | Gross modifier sales |
net_sales | sum | Net modifier sales |
returns_amount | sum | Returns amount |
avg_gross_sales | avg | Average gross sales per modifier |
avg_net_sales | avg | Average net sales per modifier |
avg_modifier_price | avg | Average modifier price |
| Dimension | Type | Description |
|---|---|---|
modifier_name | string | Modifier name (not unique — always pair with modifier_list_name) |
modifier_list_name | string | Modifier list/group name (e.g., "Size", "Toppings") |
item_name | string | Item the modifier was applied to |
location_name | string | Location display name |
local_reporting_timestamp | time | Local timestamp |
channel_name | string | Sales channel |
{ "measures": ["ModifierSales.quantity_sold", "ModifierSales.net_sales"], "dimensions": [ "ModifierSales.modifier_list_name", "ModifierSales.modifier_name", "ModifierSales.item_name" ], "timeDimensions": [{ "dimension": "ModifierSales.local_reporting_timestamp", "dateRange": "last 30 days" }], "order": { "ModifierSales.quantity_sold": "desc" }, "limit": 20 }
Kitchen ticket and item performance metrics. Measures include ticket counts, prep/completion times, on-time vs late percentages, and item-level timing.
Warning
Kitchen tickets are not the same as sales orders. Use the Sales view for sales reporting and KDS for kitchen operations analysis.
Combines speed-of-service metrics (order entry time, service time) with sales measures and optional KDS ticket metrics. Useful for analyzing operational efficiency alongside revenue.
Three views for benchmarking your sales against similar businesses in the same city and category:
- PeerBenchmarkHourlySales — Sales distribution by hour of day vs peers
- PeerBenchmarkOrderValue — Average order value vs peers
- PeerBenchmarkSalesTrend — Year-over-year sales growth vs peers
Note
Not all merchants have a matching peer cohort. These views use my_ prefix for your metrics and peer_ prefix for peer-group metrics. Filter cadence to exactly one value (weekly, monthly, or yearly).
| Views | Cubes | |
|---|---|---|
| Pre-filtered | Yes (e.g., Sales only includes closed orders) | No — you add segments yourself |
| Human-readable | Yes (location_name, channel_name) | IDs only (location_id) |
| Pre-joined | Yes (combines data from multiple cubes) | Single data domain |
| Recommended for | Standard reporting | Advanced/raw data access |
| Segment needed? | Optional (for further filtering) | Usually required (e.g., closed_checks) |