Skip to main content

Reports

Product overview​

The Smart Placement Reports API lets partners and portals regularly export Smart Placement statistics to their own BI systems, analytics tools, or data warehouses.

The API provides data on advertising activity, placement performance, attributed sales, and placement traffic. The data is available in a single JSON format with daily granularity.

The API is intended for server-side integration. The partner configures a regular export on its side, such as a scheduled daily pull, and loads the data into its own storage without manual exports or additional requests to Retail Rocket Group.

Authentication uses a Personal Access Token. The token must be stored on the partner's server and must not be passed to the client browser. The integration uses a server-to-server model; CORS and client-side tracking are not used in this scenario.

Use cases​

  1. Aggregated advertising activity analytics The partner regularly exports the Daily portal advert report to its own data warehouse to build dashboards for advert, advertiser, and placement performance.
  2. Financial reporting and attribution analysis The partner exports the Daily attributed orders report to associate attributed orders with specific adverts and placements. This data can be used for financial reporting, reconciliation, and custom attribution models.
  3. Placement inventory and fill-rate analysis The partner exports the Daily placement report to analyze demand and advert match statistics for each placement and placement group. The requests and adRequests metrics help assess available inventory, fill rate, and potential optimization areas.
  4. Integration with internal analytics processes The partner configures regular report exports to a BI system, data warehouse, or internal analytics pipelines. This makes it possible to use Smart Placement data together with the partner's other data sources.

Using third-party SSO​

If a portal or publisher uses a third-party SSO provider, the authentication rules are defined by that provider's settings. The response contract for reports remains the same and does not depend on the portal user's authentication method.

Technical limitations​

  • Date range. The request date must be within the last 60 days. If the date is outside this window, the API returns 400 INVALID_DATE_RANGE. This limit allows backfills without loading cold data.
  • Rate limit. Requests are subject to a 10-second rate-limit window. When it is exceeded, the API returns 429 RATE_LIMIT_EXCEEDED and a Retry-After header in seconds. The client must implement backoff and retry the request after the specified pause.
  • Granularity. The Daily portal advert report returns one line for each combination of advert, placement, advertiser, and date. The Daily attributed orders report returns one line for each order line item. The Daily placement report returns one line for each combination of placement, hour, and deviceType; a full day can contain up to 24 lines per placement.
  • Response format. The Daily portal advert report and Daily attributed orders report return application/json with a { "value": [...] } wrapper. The Daily placement report returns application/json-seq: a line-delimited stream of JSON objects without a value wrapper. Parse this response line by line.
  • Timezone. The tz query parameter in IANA format is required. It defines the day boundary for data grouping. Explicitly provide the partner time zone, for example Europe/Moscow.
  • Monetary values. The spent, purchase, postViewRevenue, and postClickRevenue fields are passed as decimal values with two digits after the decimal point. The currency matches the partner account currency.