Skip to main content

​
Before Starting

The following information is important to know regarding Demand Side Analytics.

​
Asynchronous Workflow

POST /reports/performance, POST /reports/missed-opportunities, and POST /reports/attributed-transactions are all asynchronous: you submit a request, poll the returned reportId for status, and download the output once processing succeeds.
  1. Submit the report request — a successful call returns 200 OK with a reportId and a status of pending.
  2. Poll for status at GET /reports/{reportId}/status until status is success or failure.
  3. Download the output at GET /reports/{reportId}/output once status is success.
The Real-Time Performance API is the exception: it is a synchronous endpoint (POST /retail-media/reports/sync/real-time-performance) that returns data directly in the response, with no reportId, polling, or output step.

​
Granularity

Most reports are generated at a daily granularity, except for the Attributed Transactions report, which is provided at an hourly granularity.

​
Report Date Range

The report date range supports a maximum window of 100 days per report, regardless of whether you scope by account, campaign, or line item, with data retained for up to 3 years.

​
Report Row Limits

Reports are limited to 10MM rows. If a report reaches this limit, the data may be incomplete due to truncation. To avoid this, consider reviewing the following parameters for bulk requests:
  • Number of campaign or line item IDs
  • Start and end date range
  • Report type

​
Report Attribution

  • Report attribution windows and time-zones are fully configurable.
  • Data is processed and batched hourly. Same-day data may be partially available.
  • While reports with an end date of today or yesterday are cached for 1 hour, reports with an end date older than yesterday are cached for 24 hours.
  • The exact expiration time is provided in the expiresAt field of the /status response.

​
Rate Limits

You can find more details about rate limits on this page.

OAuth Method

Rate limit

Rate limit applies at level

Client Credentials

250 callsper minute for default endpoints

40 callsper minute for reporting endpoints

Application level

Authorization Code

10 callsper minute

Account

​
Data Latency

Please refer to our troubleshooting guide for more data latency details.
Different types of activity and attribution data become available at different times after the event or sale:
  • Onsite activity data is typically available within 6–8 hours of the event.
  • Offsite activity data is typically available within 24 hours of the event.
  • Initial attribution data is available within 7–9 hours of the sale.
  • Final attribution data is processed and posted within 74 hours after the sale.
  • Please note that potential minor updates can occur up to 120 hours before finalization
Learn more about our Attribution Rules in the Commerce Max Help Center.

​
Response Codes

All Demand Side Analytics reporting endpoints — POST /reports/performance, POST /reports/missed-opportunities, POST /reports/attributed-transactions, and the shared GET /reports/{reportId}/status / GET /reports/{reportId}/output — share the same set of response and status codes. For authentication, permission, and rate-limit errors (401, 403, 429, 500) common to all Retail Media API endpoints, see API Error Codes.

​
What changed in this version

This version introduces a major redesign of the Demand Side Analytics reporting API. If you have an integration built against a previous version, it will not work unchanged: the endpoints, the request shape, and the reportType field have all changed. See the migration guide before upgrading.
Previous versions exposed three aggregation-level endpoints — POST /reports/campaigns, POST /reports/line-items, and POST /reports/accounts — together with a reportType field that selected a preset report shape (summary, keyword, pageType, capout, attributedTransactions, and so on). That model has been replaced by a smaller, explicit, and more predictable set of endpoints. What is different from the previous model:
  • One performance endpoint instead of three. /reports/campaigns, /reports/line-items, and /reports/accounts are all replaced by POST /reports/performance. You choose the scope by which ID array you pass under filters, and the output granularity by the dimensions you select.
  • reportType is gone. You now always specify metrics and dimensions explicitly. The preset report types (keyword, pageType, productCategory, product, servedCategory, environment, …) are reproduced simply by adding the corresponding dimension to your request.
  • Scope moved into a filters object. Instead of top-level accountId / campaignId / lineItemId, provide exactly one of filters.accountIds[], filters.campaignIds[], or filters.lineItemIds[].
  • startDate, endDate, filters, metrics, and dimensions are all required on the new endpoints.
  • Two purpose-built use cases are split into their own endpoints. capout and attributedTransactions are no longer reportType values — they are dedicated endpoints, each with a few field/metric renames documented on its own page.
For the full old → new endpoint mapping, every reportType value, before/after request examples, and the legacy support timeline, see Migrating from the Legacy Reporting API.