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_id	record_date	campaign_name	impressions	clicks	spend
ABC123	2025-01-01	Summer Sale	1000	50	$25.00
ABC123	2025-01-02	Summer Sale	1200	60	$30.00
ABC123	2025-01-03	Summer Sale	800	40	$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_id	period_start	period_end	granularity	parent_asin	sessions	units	revenue
ABC123	2025-01-01	2025-01-07	weekly	B0ABC123	500	25	$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 Format	Stored As	Example
10.5%	0.105 (decimal)	ACOS, CTR, conversion rate
$1,234.56	1234.56 (float)	Spend, sales, CPC
1,234	1234 (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.