Supplier Price-Change Bot

Compare two supplier price lists and identify price increases, pack-size changes, and changes in cost per gram, millilitre, or item. Supply CSV text or structured rows. Download a readable HTML report, changes CSV, exceptions CSV, and full JSON.

Useful for purchasing teams, small retailers, restaurant operators, and workflows that receive recurring supplier exports. No calls, onboarding meeting, supplier login, or AI model key is needed.

Quick start

Run the prefilled fictional example, then replace both lists with your own. For each snapshot provide exactly one of previousRows/previousCsv and currentRows/currentCsv.

{
  "previousRows": [{"sku":"001","price":"12.00","currency":"USD","pack":"12 x 330 ml"}],
  "currentRows": [{"sku":"001","price":"12.00","currency":"USD","pack":"12 x 300 ml"}]
}

This example detects an unchanged pack price and a 10% increase in price per millilitre. Numeric amounts are calculated with decimal arithmetic. Percentages from an old price of zero are undefined and returned as null.

CSV and matching

Use columns such as sku,price,currency,pack. Column maps translate your exact header names, for example previousColumnMap: {"sku":"Item Number","price":"Net Cost"}. Explicit maps are required if several headers could represent the same field. Specify decimalSeparator and delimiter explicitly for decimal-comma files. Prices must be nonnegative plain numbers without currency symbols; supply a three-letter currency or defaultCurrency.

Products match by supplier, SKU, and optional variant. Leading zeroes and SKU case are preserved; caseSensitiveSku: false is an explicit option. Duplicate identities and invalid records are reported as exceptions. Missing product identifiers prevent reliable addition/removal conclusions. A product removed from a list is not necessarily discontinued or unavailable.

Packs and limitations

Supported examples include 500 g, 0.5 kg, 12 x 330 ml, and 24 each. Structured pack_count, unit_size, and unit fields are also supported. Explicit us_fl_oz is available; ambiguous labels such as case, bottle, and fl oz are withheld from unit-cost comparisons. Mass and volume are never compared against each other. Currency changes are flagged without exchange-rate conversion.

Maximum per snapshot: 5,000 rows, 4 MiB of CSV, 60 columns, and 2,000 characters per cell. Empty snapshots are rejected. This version does not extract PDFs, perform OCR, fetch URLs, scrape supplier websites, infer fuzzy product matches, or save a customer's baseline between separate runs. Customers supply both snapshots and may invoke the Actor from their own recurring workflow.

Outputs

The default key-value store contains OUTPUT (JSON), REPORT (HTML), CHANGES (CSV), and EXCEPTIONS (CSV). The dataset contains one comparison report, including summary, changes, exceptions, and a comparison fingerprint. Review exceptions before acting on results. HTML text is escaped; spreadsheet-formula prefixes are escaped in CSV exports.

Pricing and billing

Consult the live Store pricing panel for the actual price. The intended billable event is comparison-completed: one event for a completed valid comparison, including comparisons with no changes. It is not charged per row or per change. Invalid inputs are rejected before this custom charge. Separate new runs are separate comparisons and may be billed again.

Charging is disabled by default in this source package. When enabled, the runtime requires pay-per-event pricing and checks the available event budget. Same-run recovery records prevent ordinary duplicate charges. An uncertain charge outcome stops for reconciliation rather than automatically charging again. Local test charges are simulations and are not revenue. Platform usage charges, if applicable, follow Apify's live pricing.

Local verification

Python 3.11+ is required; the cloud image uses Python 3.13.

python3 -m unittest discover -s tests -v
python3 -m supplier_bot.cli --input samples/demo-input.json --output reports/demo
pip install -r requirements.txt
python scripts/verify_sdk.py --storage /tmp/supplier-price-bot-test

No external API calls are needed by the comparison engine. Uploaded inputs and outputs are stored in the user's Apify run storage and follow that account's retention and access settings. Never publish confidential supplier data as a public sample. All bundled examples are fictional.