KEYXE Data Foundation
Seller and advertising data differ in meaning, timing and the way results are attributed. KEYXE is being designed to preserve those differences instead of collapsing them into misleading totals.
Five concepts
KEYXE is designed for two Amazon sources with different purposes: the Selling Partner API for seller operations and the Amazon Ads API for advertising. Each record keeps a reference to its source, report and connection, so any figure can be traced back. In the public demo the source is a seeded synthetic generator, and every export says so.
Many Amazon reports are produced asynchronously: a report is requested, processed by Amazon, then downloaded. KEYXE’s design tracks each request through those states, retries transient failures with limits, and records when data actually arrived. Nothing is described as “real-time” unless it is.
Seller ordered sales and ad-attributed sales are not additive. Ordered sales count what shoppers ordered in a period. Attributed sales count sales an ad report credits to ad interactions within an attribution window — they can include orders also counted in seller sales, and can arrive later. Adding them double-counts; dividing one by the other mixes definitions.
| Metric | Formula | Zero denominator |
|---|---|---|
| CTR | clicks ÷ impressions | N/A |
| CPC | spend ÷ clicks | N/A |
| ACoS | ad spend ÷ attributed ad sales | N/A |
| ROAS | attributed ad sales ÷ ad spend | N/A |
| Unit session % | Σ units ÷ Σ sessions | N/A |
| Est. days of cover | available units ÷ avg daily units (30 days) | N/A |
Every view states its period and an “as of” time. Lineage links a business figure back to the normalized rows and the source report that produced them. Report availability varies by account, marketplace and report type, and KEYXE shows “not available” rather than guessing.
Three layers
Expand a layer to see example fields. Field names are illustrative design examples.
Reports and records as an Amazon service returns them, kept intact for traceability.
report_type, report_id, data_start_time, data_end_timemarketplace identifier, currency codesku, asin, units_ordered, ordered_product_sales (seller)campaign_id, impressions, clicks, cost, attributed sales (ads)Consistent names, types, currencies and dates across marketplaces and report versions.
org_id, connection_id, source (seller | advertising)date (marketplace local), currency (ISO 4217)amount_minor (integer minor units, no floating-point money)ingested_at, source_report_id, freshness_statusQuestion-ready summaries with documented formulas and explicit unknowns.
ordered_sales, units, sessions, unit_session_pctspend, attributed_sales, ctr, cpc, acos, roasest_days_of_cover (labeled estimate)warnings[] (late data, partial period, N/A ratios)This diagram describes the intended architecture. It is not a claim that live ingestion from Amazon is active. Currency, marketplace and report availability differ by account and are respected per source.
Every KPI in the demo has an “Explain metric” control with its formula and a sample calculation.