My Account

New: Time-based aggregation for Item Performance reports

Date: July 22, 2026

We updated the Item Performance report API to support time-based aggregation with the new dateGranularity request parameter. This update is available for ITEM_PERFORMANCE v3 and introduces new reporting options, request requirements, and report fields.

What changed

  • Time-based aggregation

    • Added the dateGranularity request body parameter.
    • Supported values are DAILY, WEEKLY, MONTHLY, and QUARTERLY.
    • Report data is aggregated based on the selected time granularity.

  • Request parameters

    • For ITEM_PERFORMANCE v3 only, the dataStartTime, dataEndTime, and dateGranularity request body parameters are required.
    • ITEM_PERFORMANCE v1 and v2 behavior is unchanged.

  • Report output

    • Added the Data Start Time and Data End Time columns to identify the reporting period represented by each row.
    • Reports may include partial weeks, months, or quarters when the requested date range does not align with the beginning or end of the selected reporting period.

  • Reporting windows

    • Maximum reporting periods now depend on the selected dateGranularity.
      • DAILY: 15 days
      • WEEKLY: 7 weeks
      • MONTHLY: 15 months
      • QUARTERLY: 4 quarters
    • The maximum lookback period for dataStartTime is 2 years from the current date.

Scope

These updates apply only to ITEM_PERFORMANCE v3. The updates are documented in the Request an item performance report guide.

Why it matters

Time-based aggregation reduces the need for downstream data processing by returning report data grouped at the requested reporting interval. The new Data Start Time and Data End Time report fields identify the reporting period represented by each row, including partial reporting periods.

Next steps

  • Update ITEM_PERFORMANCE v3 requests to include dataStartTime, dataEndTime, and dateGranularity.
  • Update integrations to consume the new Data Start Time and Data End Time report columns.
  • Verify that requested date ranges do not exceed the maximum reporting period for the selected dateGranularity.
  • Review the updated Item Performance report documentation for request examples, reporting windows, and partial reporting period behavior.
  • Begin updating your code to use ITEM_PERFORMANCE v3 , as v1 and v2 will be deprecated. The expected deprecation date will be announced soon.