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: