Skip to main content

Reporting Structure

Reports use one of two temporal models based on how Amazon provides the data.

Row Model (Daily Snapshots)​

Used by Sponsored Products reports only. Each row represents metrics for a single day.

Example: SP Campaign Report

If you upload campaign data for Jan 1-3, you get 3 separate rows:

seller_idrecord_datecampaign_nameimpressionsclicksspend
ABC1232025-01-01Summer Sale100050$25.00
ABC1232025-01-02Summer Sale120060$30.00
ABC1232025-01-03Summer Sale80040$20.00

Re-uploading Jan 2 with updated data replaces only that day's row - Jan 1 and Jan 3 remain unchanged.

Range Model (Period Summaries)​

Used by Business Reports and Search Query Performance reports. Each row represents aggregated metrics over a date range.

Example: BR Detail Page Sales (Weekly)

If you upload weekly data, you get 1 row covering the entire period:

seller_idperiod_startperiod_endgranularityparent_asinsessionsunitsrevenue
ABC1232025-01-012025-01-07weeklyB0ABC12350025$1,250.00

Re-uploading the same week replaces the entire period's row. The period boundaries define what gets updated.

Uniqueness Keys​

Each report type defines a set of fields that together uniquely identify a row. These determine whether an upload creates a new row or updates an existing one.

Row Model Keys always include record_date:

sp_campaign_report: [seller_id, marketplace, record_date, campaign_name, portfolio_name, program_type]
sp_search_term_report: [seller_id, marketplace, record_date, campaign_name, ad_group_name, targeting, match_type, customer_search_term]

Range Model Keys always include the date range + granularity:

br_detail_page_sales_traffic: [seller_id, marketplace, period_start_date, period_end_date, period_granularity, parent_asin, child_asin, sku]
search_query_performance_asin: [seller_id, marketplace, asin, period_granularity, period_start_date, search_query]

When uploading:

  • If all uniqueness key fields match an existing row → UPDATE
  • If no match found → INSERT
  • If match found and all fields identical → UNCHANGED (no write)

Field Transformations​

Data is normalized during ingestion:

CSV FormatStored AsExample
10.5%0.105 (decimal)ACOS, CTR, conversion rate
$1,234.561234.56 (float)Spend, sales, CPC
1,2341234 (int)Impressions, clicks, units

Schema Definitions​

Report schemas are defined in YAML files. You can view them on GitHub:

View Report Schemas on GitHub →

The folder is organized by report category:

  • business/ - Business Reports (BR)
  • sponsored_products/ - Sponsored Products (SP) reports
  • search_query/ - Search Query Performance reports

Each YAML file specifies:

  • temporal_config - Row vs Range model
  • uniqueness_keys - Fields that identify a unique row
  • required_columns - CSV columns with data types and validations
  • metadata_schema - Required metadata for upload

All changes are tracked in report_row_changes for complete audit trail and upload reversal.