# Report families

Knowledge base of the report families exposed by
[ListReports](en-us/api-reference/operations/list-reports). Availability depends
on marketplace, account permissions, date and report variant (`daily`,
`last7days`, `last30days`). Filenames use the form
`<account>-<family>-<YYYYMMDD>.tsv.gz`.

> Source: consolidated from the `gclid-mapper` and `data-layer` projects, which
> consume these reports in production.

## Known families

| API/UI key | Filename marker | Primary dimension | Status |
| :--- | :--- | :--- | :--- |
| `bounty` | `-bounty-report-` | bounty event | Observed: bounty description, date, tag, earnings, quantity. |
| `bounty_earnings` | `-bounty_earnings-report-` | bounty/tracking attribution | Known; sample the schema when available. |
| `category` | `-category-report-` | category | Observed: clicks, orders, shipped/returned items, revenue, earnings. |
| `earnings` | `-earnings-report-` | shipped product line | Observed: Tracking ID, shipment date, revenue, earnings, Sub Tag. |
| `linked_product` | `-linked_product-report-` | linked ASIN/product | Known: Tracking ID, Subtag, clicks, orders, revenue, earnings. |
| `linked_product_tracking` | `-linked_product_tracking-report-` | linked product attribution | Known; sample the schema when available. |
| `orders` | `-orders-report-` | ordered product line | Observed: Tracking ID, direct clicks, order quantities, Sub Tag. |
| `subtag` | `-subtag-report-` | Subtag | Observed: clicks, orders, revenue, earnings. Not a Tracking ID report. |
| `tracking` | `-tracking-report-` | Tracking ID | Known: compact legacy tracking metrics. |
| `tracking_id` | `-tracking_id-report-` | Tracking ID | Confirmed: source for the daily Tracking ID data. |

The markers overlap. Match the more specific family first: `linked_product_tracking`
before `linked_product`, `tracking_id` before `tracking`, and `bounty_earnings`
before `bounty`. `ReportMetadata::family()` implements exactly this precedence.

## Tracking ID report schema

| TSV heading | Normalized field | Type |
| :--- | :--- | :--- |
| Tracking ID | `tracking_id` | string |
| Clicks | `clicks` | integer |
| Items Ordered | `items_ordered` | integer |
| Ordered Revenue | `ordered_revenue` | decimal |
| Items Shipped | `items_shipped` | integer |
| Items Returned | `items_returned` | integer |
| Items Shipped Revenue | `items_shipped_revenue` | decimal |
| Items Shipped Earnings | `items_shipped_earnings` | decimal |
| Items Returned Revenue | `items_returned_revenue` | decimal |
| Items Returned Earnings | `items_returned_earnings` | decimal |
| Bonus | `bonus` | decimal |
| Total Earnings | `total_earnings` | decimal |

The report date is derived from the `YYYYMMDD` filename suffix. Amazon TSV files
carry a title on row 1 and headings on row 2.

## Other confirmed schemas

- **Category / Subtag** — dimension (`Category` or `Subtag`), Clicks, Indirect/Direct
  Items Ordered, Items Ordered, conversion rates, Order Quantity, Commission Rate,
  Ordered Revenue, Items Shipped/Returned, Shipped/Returned Revenue and Earnings,
  Bonus, Total Earnings.
- **Earnings** — Product line, Seller, Tracking ID, Date shipped, Price, Referral
  fee rate, Quantity, Revenue, Earnings, Sub Tag.
- **Orders** — Product line, Date ordered, Link type, Tracking ID, Direct
  conversion, Direct clicks, Direct/Indirect/Total ordered quantity, Sub Tag.
- **Linked product** — Category, Product Title, ASIN, Tracking ID, Subtag, Clicks,
  Indirect/Direct Items Ordered, conversion rates, Order Quantity, Commission Rate,
  Ordered Revenue, Items Shipped/Returned, Shipped/Returned Revenue and Earnings,
  Total Earnings.
