Amazon Competitor Offer Matrix

Turn vendor offer rows you already have (exports from spreadsheets, other datasets or your own tools) into one comparison row per product: all prices in a single currency, your own fee estimates applied, the cheapest all-in vendor highlighted, and explicit warnings wherever data is missing.

This Actor does not visit Amazon or any other website. It makes no network requests and uses no proxies or paid APIs. It only processes the rows you pass in.

What you get

One dataset item per product:

• bestVendor, bestAllInCost, highestAllInCost, savingsVsHighest, spreadPercent
• cells: one entry per vendor with converted price, shipping, estimatedFee, allInCost, sourceCurrency, feeSource and per-offer warnings
• warnings: human-readable list such as MISSING_FX_RATE, MISSING_SHIPPING, AMBIGUOUS_SYMBOL, CURRENCY_ASSUMED, SHIPPING_ASSUMED, DUPLICATE_VENDOR_OFFER, UNAVAILABLE, SMALL_SAMPLE, NO_COMPARISON
• sampleSizeNote

A SUMMARY record in the key-value store lists skipped rows and warning counts.

All-in cost = converted price + shipping + estimated fee.

Sample input

{
  "offers": [
    {"asin": "EXAMPLE-001", "title": "Example Widget 2-Pack", "vendor": "Vendor A", "price": "$24.99", "shipping": "free"},
    {"asin": "EXAMPLE-001", "title": "Example Widget 2-Pack", "vendor": "Vendor B", "price": "21,50 €", "shipping": "3,00 €"},
    {"asin": "EXAMPLE-001", "title": "Example Widget 2-Pack", "vendor": "Vendor C", "price": 26.4, "currency": "USD"}
  ],
  "targetCurrency": "USD",
  "fxRates": {"EUR": 1.08},
  "vendorFees": {"Vendor A": {"percent": 15, "fixed": 0.3}, "Vendor B": {"percent": 8}},
  "defaultShipping": 4.0
}

The values above are illustrative placeholders, not real market data. Vendor C has no shipping, so defaultShipping is used and flagged with SHIPPING_ASSUMED.

Input notes

• offers: array of row objects. Recognized columns include asin/productId/sku/gtin, vendor/seller/merchant, title/name, price, currency, shipping, url, availability. Use fieldMap for other column names.
• fxRates: rates you provide (target-currency units per one unit of the listed currency). Nothing is downloaded, so you control the rate date.
• Fees: defaultFeePercent, defaultFeeFixed and vendorFees are your own estimates, applied to the item price. The fixed part is in the target currency. They are not official fee schedules.
• Rows are grouped by product id, or by a normalized title when no id is present.

How offers are ranked

Only offers with a readable price, a known currency, an FX rate, a shipping value and an in-stock status are ranked. Everything else stays in cells with comparable: false and a warning. If a vendor appears several times for one product, the lowest comparable row is shown.

Pricing

The Actor reports one matrix-row event per matrix row written to the dataset, after the rows are stored. Invalid input fails before anything is written or charged. No payable plan is configured in this repository.

Limitations

• Results reflect only the rows you supply. A matrix built from two or three vendors is a small sample; the Actor warns when fewer than three vendors are comparable and cannot compare with fewer than two.
• Input prices may be stale; the Actor cannot verify them or check live availability.
• Price parsing is heuristic. 1,234 is read as one thousand two hundred thirty-four, 12,50 as 12.50. Ranges such as 10 - 20 are rejected. The symbols $ and ¥ are ambiguous and are flagged; put an explicit currency on each row when it matters.
• Same-product matching relies on identical ids or identical normalized titles. Different titles for the same item will not merge.
• Fees are simple percentage plus fixed estimates; real marketplace fees can depend on category, size, tax and fulfillment, which are not modeled. Taxes and duties are not included.
• Output is not financial or pricing advice.

Local tests

Tests are offline and use only the Python standard library:

python -m unittest discover -s tests