Time Handling

The Reporting API provides both UTC and local time dimensions to support different reporting needs. Understanding when to use each is crucial for accurate time-based analysis.

UTC time dimensions store timestamps in Coordinated Universal Time (UTC), providing a consistent global reference.

• Orders.sale_timestamp - UTC time when order was placed
• PaymentAndRefunds.reporting_timestamp - UTC time when payment was processed
• Orders.created_at - UTC time when order was created

Use UTC time dimensions when you need:

• Consistent global time across all locations
• Cross-timezone aggregation (e.g., total sales across all locations globally)
• Precise timestamp ordering without timezone ambiguity
• API integration where systems expect UTC

{
  "measures": ["Orders.net_sales"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": ["2024-01-01T00:00:00Z", "2024-01-01T23:59:59Z"],
    "granularity": "hour"
  }],
  "segments": ["Orders.closed_checks"]
}

Returns hourly sales for January 1st in UTC time—may span multiple business days for locations in different timezones.

Local time dimensions adjust timestamps to the location's timezone, providing business-day alignment.

• Orders.local_date - Business date in location's timezone
• Orders.local_reporting_timestamp - Reporting timestamp in location's timezone

Use local time dimensions when you need:

• Business day alignment (e.g., "What were sales on January 1st at this location?")
• Location-specific reporting that matches what staff see in the dashboard
• Day-of-week analysis (e.g., "Which day of the week is busiest?")
• Service period tracking (e.g., lunch vs dinner at local time)

{
  "measures": ["Orders.net_sales"],
  "dimensions": ["Orders.local_date"],
  "filters": [{
    "member": "Orders.local_date",
    "operator": "inDateRange",
    "values": ["2024-01-01", "2024-01-31"]
  }],
  "segments": ["Orders.closed_checks"]
}

Returns sales for each business day in January, aligned to each location's local timezone.

You have locations in New York (EST), Los Angeles (PST), and London (GMT).

UTC Query:

{
  "measures": ["Orders.net_sales"],
  "timeDimensions": [{
    "dimension": "Orders.sale_timestamp",
    "dateRange": ["2024-01-01T00:00:00Z", "2024-01-01T23:59:59Z"],
    "granularity": "hour"
  }]
}

Result: Sales from 12am-11:59pm UTC, which includes:

• New York: 7pm Jan 1 - 6:59pm Jan 2
• Los Angeles: 4pm Jan 1 - 3:59pm Jan 2
• London: 12am Jan 1 - 11:59pm Jan 1

Local Date Query:

{
  "measures": ["Orders.net_sales"],
  "dimensions": ["Orders.location_id", "Orders.local_date"],
  "filters": [{
    "member": "Orders.local_date",
    "operator": "equals",
    "values": ["2024-01-01"]
  }]
}

Result: Sales for January 1st business day at each location:

• New York: 12am-11:59pm EST on Jan 1
• Los Angeles: 12am-11:59pm PST on Jan 1
• London: 12am-11:59pm GMT on Jan 1

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

Returns daily totals in UTC—consistent global view.

{
  "measures": ["Orders.net_sales", "Orders.count"],
  "dimensions": ["Orders.location_id", "Orders.local_date"],
  "filters": [{
    "member": "Orders.local_date",
    "operator": "inDateRange",
    "values": ["2024-01-01", "2024-01-31"]
  }],
  "segments": ["Orders.closed_checks"]
}

Returns sales by location and business day—matches location dashboards.

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

Returns hourly sales patterns—use local time dimensions if you want to analyze service periods (lunch, dinner) at local time.

{
  "dimensions": ["Orders.local_date"],
  "filters": [{
    "member": "Orders.local_date",
    "operator": "inDateRange",
    "values": ["2024-01-01", "2024-01-31"]
  }]
}

This ensures January 1st means "January 1st business day" at each location.

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

This provides consistent global time buckets.

Don't mix UTC and local time dimensions in the same query—choose one approach and stick with it.

When building reports, document whether you're using UTC or local time so future developers understand the semantics.