Time dimensions enable time-series analysis with automatic date grouping.
Note
Tip: Views like Sales and ItemSales support the same time dimension patterns shown below. For most reporting, use Sales.local_reporting_timestamp for time-series analysis on the Sales view.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"], "granularity": "day" }] }
{ "dimension": "Cube.time_dimension", // Required: which time field "dateRange": ["start", "end"], // Required: date range "granularity": "day" // Optional: grouping level }
| Granularity | Description | Example Use Case |
|---|---|---|
hour | Hourly buckets | Intra-day analysis |
day | Daily buckets | Daily sales reports |
week | Weekly buckets | Weekly trends |
month | Monthly buckets | Monthly performance |
quarter | Quarterly buckets | Quarterly reports |
year | Yearly buckets | Year-over-year analysis |
{ "dateRange": ["2024-01-01", "2024-01-31"] }
{ "dateRange": "today" }
{ "dateRange": "yesterday" }
{ "dateRange": "this week" }
{ "dateRange": "last 7 days" }
{ "dateRange": "last 30 days" }
{ "dateRange": "this month" }
{ "dateRange": "last month" }
Note
All relative date formats tested: We've verified that all the relative date formats shown above work with the Square Reporting API, including today, yesterday, this week, last 7 days, last 30 days, this month, last month, this year, last year, last week, this quarter, and last quarter.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"], "granularity": "day" }] }
Returns net sales for each day in January—one row per day with the date and sales total.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": "today", "granularity": "hour" }] }
Returns net sales for each hour of today—useful for intra-day monitoring and real-time dashboards.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-12-31"], "granularity": "month" }] }
Returns net sales for each month in 2024—one row per month showing monthly totals.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"] // No granularity = single total for the range }] }
Returns a single total for all of January—no time breakdown, just one aggregated value for the entire period.
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.location_id"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"], "granularity": "day" }] }
This returns daily sales by location (one row per day per location).
The Reporting API offers two approaches to time-based queries, and choosing the right one is important for matching merchant expectations.
Approach 1: UTC timestamps (sale_timestamp)
Orders.sale_timestamp stores the sale time in UTC. When you use this with timeDimensions, the API groups data by UTC time boundaries.
{ "measures": ["Orders.net_sales"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"], "granularity": "day" }], "segments": ["Orders.closed_checks"] }
When to use: Backend analytics, cross-timezone aggregation, or when UTC alignment is acceptable.
Caveat: For merchants in non-UTC timezones, UTC-based daily grouping won't match what they consider a "business day." A sale at 11pm local time might fall into the next day in UTC. This can cause discrepancies of ~7% or more compared to the Square Dashboard for multi-timezone merchants.
Approach 2: Local time dimensions (local_date, local_reporting_timestamp)
The Orders.local_date dimension (type: string) represents the date in the location's local timezone. This aligns with what merchants see in the Square Dashboard.
{ "measures": ["Orders.net_sales"], "dimensions": ["Orders.local_date"], "timeDimensions": [{ "dimension": "Orders.sale_timestamp", "dateRange": ["2024-01-01", "2024-01-31"] }], "segments": ["Orders.closed_checks"] }
When to use: Building reports that should match the Square Dashboard, or any merchant-facing reporting where "today's sales" should align with the merchant's local day.
Additional local time dimensions are available for finer-grained local time analysis:
Orders.local_day_of_week— Day of the week in local timezoneOrders.local_hour— Hour of the day in local timezoneOrders.local_month— Month in local timezoneOrders.local_year— Year in local timezone
| Scenario | Recommended Approach | Dimension |
|---|---|---|
| Match Square Dashboard | Local time | Orders.local_date |
| Merchant-facing daily reports | Local time | Orders.local_date |
| Hourly analysis (local business hours) | Local time | Orders.local_hour |
| Cross-timezone backend analytics | UTC | Orders.sale_timestamp |
| Time-series with granularity grouping | UTC | Orders.sale_timestamp |
Note
Tip: If your reports need to match the Square Dashboard closely, use Orders.local_date for daily grouping rather than Orders.sale_timestamp with day granularity.