Working with Cubes Overview

The Reporting API data model is organized into cubes—logical groupings of related metrics and dimensions. Each cube contains:

• Measures - What to calculate (e.g., net_sales, count, tips_amount)
• Dimensions - How to slice and group (e.g., location_id, sale_timestamp, customer_id)
• Segments - Predefined filters for common scenarios (e.g., closed_checks, online_orders)

Think of a cube as a pre-built data mart optimized for specific analytical questions:

• Orders cube - Answers questions about sales, revenue, and order patterns
• PaymentAndRefunds cube - Answers questions about payment methods, tender types, and refunds
• CustomerSnapshots cube - Answers questions about customer behavior and lifetime value
• ItemTransactions cube - Answers questions about product performance and inventory

Each cube is designed around a specific business entity and includes all the measures and dimensions relevant to analyzing that entity.

Measures are pre-aggregated metrics with defined calculation logic:

{
  "name": "Orders.net_sales",
  "aggType": "sum",
  "description": "Total sales after discounts and returns, excluding tax"
}

You select measures by name; the API applies the correct aggregation automatically.

Dimensions are attributes you can group by or filter on:

{
  "name": "Orders.location_id",
  "type": "string",
  "description": "Location where the order was placed"
}

Use dimensions to break down your measures (e.g., sales by location, by channel, by customer).

Segments encapsulate common business logic:

{
  "name": "Orders.closed_checks",
  "description": "Only fully paid and settled orders"
}

Use segments to ensure consistent filtering across all queries.

The Reporting API currently provides 43 cubes and 8 views for different analytical needs. For complete details, interactive exploration, and the most up-to-date list, visit the Schema Explorer.

Here's a simple query using the Orders cube:

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

This returns total sales and order count for each location over the last 30 days.

The schema is dynamic and evolves over time. Always use the /v1/meta endpoint or Schema Explorer to discover:

• Available cubes
• Measures and their aggregation types
• Dimensions and their data types
• Available segments

See Schema Discovery for details.

Cubes can be combined in queries through automatic joins. The API handles join logic based on common dimensions like order_id, location_id, or customer_id.

See Multi-Cube Joins for details.

Cubes provide both UTC and local time dimensions for different reporting needs:

• UTC - Consistent global time
• Local - Business day alignment

See Time Handling for details.