Measure & Dimension Types

Understanding measure and dimension types is crucial for building correct queries and interpreting results.

Most monetary measures use sum aggregation:

{
  "name": "Orders.net_sales",
  "aggType": "sum",
  "type": "number",
  "format": "currency"
}

Examples:

• Orders.net_sales - Total sales after discounts and returns
• Orders.tips_amount - Total tips received
• Orders.sales_tax_amount - Total sales tax collected
• Orders.discounts_amount - Total discounts applied

Behavior: Values are summed across the selected dimensions and time range.

Example query:

{
  "measures": ["Orders.net_sales", "Orders.tips_amount"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "last 30 days"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns the sum of all net sales and tips for the last 30 days.

Count measures use count aggregation:

{
  "name": "Orders.count",
  "aggType": "count",
  "type": "number"
}

Examples:

• Orders.count - Number of orders
• Sales.order_count - Number of orders (via Sales view)
• PaymentAndRefunds.count - Number of payment/refund transactions

Behavior: Counts distinct entities (orders, payments, etc.).

Example query:

{
  "measures": ["Orders.count", "PaymentAndRefunds.count"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "last 30 days",
    "granularity": "day"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns daily order and payment counts for the last 30 days.

Average measures use avg aggregation:

{
  "name": "Orders.avg_net_sales",
  "aggType": "avg",
  "type": "number",
  "format": "currency"
}

Examples:

• Orders.avg_net_sales - Average net sales per order
• Orders.avg_total_sales - Average customer order value

Behavior: Calculates the mean value across the selected scope.

Example query:

{
  "measures": [
    "Orders.avg_net_sales",
    "Orders.count"
  ],
  "dimensions": ["Orders.location_id"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "last 30 days"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns average ticket size per location (with order count for context).

Some measures are derived from other measures:

Examples:

• Orders.net_sales = top_line_product_sales - discounts_amount - itemized_returns
• Orders.net_sales_with_tax = net_sales + sales_tax_amount

Behavior: Calculated on the fly during query execution using the underlying measures.

String-based attributes for grouping and filtering:

Examples:

• Orders.location_id - Location identifier
• Orders.sales_channel_id - Sales channel
• PaymentAndRefunds.payment_method - Payment method

Usage: Group by these to break down metrics.

Example query:

{
  "measures": ["Orders.net_sales"],
  "dimensions": ["Orders.sales_channel_id"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "last 30 days"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns sales by channel (online vs in-person).

Special dimensions for time-series analysis:

Examples:

• Orders.sale_timestamp - UTC sale time
• Orders.local_date - Local business date
• Orders.local_reporting_timestamp - Reporting day in local time

Usage: Use with timeDimensions array and granularity for time-series aggregation.

Example query:

{
  "measures": ["Orders.net_sales"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": ["2024-01-01", "2024-01-31"],
    "granularity": "day"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns daily sales for January.

Unique identifiers for drill-down analysis:

Examples:

• Orders.order_id - Unique order identifier
• Orders.customer_id - Customer identifier
• PaymentAndRefunds.payment_id - Payment identifier
• Orders.device_id - Device identifier

Usage: Drill down to individual entities or join cubes.

Example query:

{
  "measures": ["Orders.net_sales"],
  "dimensions": ["Orders.order_id"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "last 7 days"
  }],
  "segments": ["Orders.closed_checks"],
  "limit": 100
}

Returns individual order details for the last 7 days.

If you have 3 orders with net_sales of $10, $20, and $30:

{
  "measures": ["Orders.net_sales"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "today"
  }]
}

Result: {"Orders.net_sales": "60.00"} (10 + 20 + 30)

Same 3 orders:

{
  "measures": ["Orders.count"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "today"
  }]
}

Result: {"Orders.count": 3}

Same 3 orders:

{
  "measures": ["Orders.avg_net_sales"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": "today"
  }]
}

Result: {"Orders.avg_net_sales": "20.00"} ((10 + 20 + 30) / 3)

When you query /reporting/v1/meta, each measure and dimension includes its type:

Measure example:

{
  "name": "Orders.net_sales",
  "title": "Net Sales",
  "description": "Total sales after discounts and returns, excluding tax",
  "type": "number",
  "aggType": "sum",
  "format": "currency"
}

Dimension example:

{
  "name": "Orders.location_id",
  "title": "Location ID",
  "type": "string"
}

Time dimension example:

{
  "name": "Orders.sale_timestamp",
  "title": "Sale Timestamp",
  "type": "time"
}