Connector name: Amazon Selling Partner

Table name: sku_economics. This is the SKU Economics report from Seller Central, served through the SP-API Data Kiosk Economics dataset (analytics_economics_2024_03_15, query economics).

API documentation link:
- Schema definition: https://github.com/amzn/selling-partner-api-models/blob/main/schemas/data-kiosk/analytics_economics_2024_03_15.graphql
- Data Kiosk API: https://developer-docs.amazon.com/sp-api/docs/data-kiosk-api
- Data Kiosk API reference: https://developer-docs.amazon.com/sp-api/reference/data-kiosk-v2023-11-15
- Schema Explorer (Seller Central login required): https://sellercentral.amazon.com/datakiosk-schema-explorer
- Amazon confirming SKU Economics is available through Data Kiosk: https://github.com/amzn/selling-partner-api-models/discussions/3973

Additional details:

Use case: We use SKU Economics for per-unit fees that Amazon charges at the shipment or account level and doesn't assign to individual products anywhere else: FBA inbound placement service fees, inbound transportation fees, and labeling/polybagging fees. We use it alongside the existing Finance tables to calculate per-ASIN margin. Today we download the report from Seller Central by hand every settlement period and load it through an S3 connector. That's slow and error-prone (duplicate or renamed uploads, restated values).

Why existing tables don't cover it: In the Finance Events tables, these fees (FBAInboundTransportationFee, FBAInboundConvenienceFee, LabelingFee) have no ASIN or SKU, only a shipment ID or nothing at all. The new Transactions API tables (transaction_item_context) don't appear to fill that gap either. See https://github.com/amzn/selling-partner-api-models/issues/2038 and https://github.com/amzn/selling-partner-api-models/issues/4237. The connector also has no inbound shipment item data, so we can't split these fees across products ourselves.

Requested behavior:
- Query the economics dataset with aggregateBy.productId = MSKU (or CHILD_ASIN) and a configurable date granularity (DAY, WEEK or MONTH). If feasible, also support RANGE aligned to settlement periods.
- Keep the key fields: startDate, endDate, marketplaceId, parentAsin, childAsin, msku, fnsku.
- Include fees as a child table with one row per fee type and charge: feeTypeName, startDate/endDate, and aggregatedDetail (amount, promotionAmount, taxAmount, totalAmount, quantity, amountPerUnit, amountPerUnitDelta), plus components where they exist.
- Optionally include sales, netProceeds and ads as columns or child tables.
- Re-sync recent periods on each sync, because Amazon restates SKU Economics values after the fact (quantities and per-unit amounts change between pulls).

Notes: Data Kiosk needs an additional seller role. Amazon's docs mention both Brand Analytics and Selling Partner Insights; see https://developer-docs.amazon.com/sp-api/changelog/correction-data-kiosk-role-requirements. Query results can be downloaded for 30 days. With the Finance Events API tables being discontinued on December 16, 2026, this table would give sellers a supported source for product-level fee economics that the Transactions API doesn't provide.