# Retail Price Exception Auditor (`sah-designs/retail-price-exception-auditor`) Actor

Compare authorized retailer observations with your reference catalog. Flag below-reference prices, stale data, pack or currency mismatches, and conflicting records for human review. No scraping or enforcement actions.

- **URL**: https://apify.com/sah-designs/retail-price-exception-auditor.md
- **Developed by:** [SAH-Designs](https://apify.com/sah-designs) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 audited observations

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Retail Price Exception Auditor

Compare price observations you already collect with a reference catalog. Get a
JSON dataset and an HTML review report separating below-reference prices from
data that cannot safely be compared.

For brand operators and agencies with an existing price feed. Supply data you
are authorized to process. This Actor does not collect retailer websites.

### Quick start

1. Supply `references` and `observations` in the input form or JSON editor.
   The prefilled single-observation demo is synthetic; replace it with your data.
2. Keep `maxAgeHours` at 24, or choose the age appropriate to your workflow.
3. Start the Actor. Open **Output** for the dataset. Under **Storage → Key-value
   store**, open **REVIEW** for the HTML report or **REPORT** for full JSON.

Example input (synthetic; update `observedAt` to the actual observation time):

```json
{
  "references": [{
    "sku": "001", "variant": "blue", "market": "US", "currency": "USD",
    "unitCount": 1, "referencePrice": "10.00"
  }],
  "observations": [{
    "sku": "001", "variant": "blue", "market": "US", "currency": "USD",
    "unitCount": 1, "seller": "Example retailer", "advertisedPrice": "9.99",
    "sourceUrl": "https://example.com/product",
    "observedAt": "2026-10-20T11:00:00Z", "sourceHealthy": true,
    "priceType": "public_advertised", "availability": "in_stock"
  }],
  "maxAgeHours": 24
}
```

### How results work

| Status | Meaning |
| --- | --- |
| `BELOW_REFERENCE` | Eligible supplied price is below the supplied reference. |
| `AT_OR_ABOVE_REFERENCE` | Eligible supplied price meets or exceeds the reference. |
| `REVIEW` | Incompatible, missing, stale or conflicting data needs review. |

Reference matching requires exact SKU, variant and market. Leading zeros are
preserved. Currency and pack size must match. Prices use decimal arithmetic.
The result includes the original observation, reference price, review reasons
and, for eligible comparisons, shortfall amount and percentage.

Review cases include unknown references, currency/pack mismatches, observations
older than the age limit or more than five minutes in the future, unhealthy or
unconfirmed sources, unavailable stock and nonpublic advertised-price types.
Conflicting observations for the same SKU, variant, market, seller and URL all
require review. Exact repeated rows are coalesced and counted in the summary.

Inputs require nonempty arrays, valid positive prices and unit counts, and
observation URLs/timestamps. Maximum 10,000 rows per input list. Invalid
reference catalogs fail rather than returning an all-clear report.

### Scope and limitations

Source health, stock status and price type are assertions supplied by the caller.
URLs are retained as supplied evidence references; they are not visited or
independently verified. Supply comparable price bases. There is no currency
conversion, shipping/tax adjustment, coupon calculation, fuzzy product matching
or bundle inference. Currency syntax is checked, not a complete ISO registry.

A below-reference result is a numerical comparison, not a legal or policy
determination. Review the underlying evidence before acting. The Actor does not
discover sellers, change prices or send enforcement messages.

### Cost and verification

Pilot price: **$0.50 per 1,000 unique audited observations** ($0.0005 each),
including records classified REVIEW. Exact duplicate rows are omitted and do
not create result charges. No website collection is included. An automatic
Actor start event costs $0.00005 at up to 1 GB RAM, with an additional start
event for each extra GB. Standard-run platform usage is included in these event
prices. Check the current Pricing tab before running. No schedule is created
automatically. Choose a maximum run budget; very small budgets may truncate
the dataset. The HTML/JSON audit reports can contain the full computed input
audit even when the dataset is limited. Charges apply only to dataset rows
actually saved by Apify plus the start event.

On October 20, 2026, the private cloud sample completed with eight expected
results: two below-reference, one at/above-reference and five requiring review,
with one exact duplicate omitted. The sample was synthetic, not customer data.
This is an early pilot; no customer outcome or independently verified price
evidence is claimed.

# Actor input Schema

## `references` (type: `array`):

1–10,000 objects: sku, variant, market, currency, unitCount (integer), referencePrice. Identity must be unique. Default is a synthetic example, not a real retailer finding.

## `observations` (type: `array`):

1–10,000 supplied observations. Default is a synthetic example.com row; its fixed timestamp will eventually produce REVIEW for staleness. Replace with your own authorized data. No website collection or independent evidence verification is performed.

## `maxAgeHours` (type: `number`):

Older observations go to review rather than being classified against the reference price.

## Actor input object example

```json
{
  "references": [
    {
      "sku": "001",
      "variant": "blue",
      "market": "US",
      "currency": "USD",
      "unitCount": 1,
      "referencePrice": "10.00"
    }
  ],
  "observations": [
    {
      "sku": "001",
      "variant": "blue",
      "market": "US",
      "currency": "USD",
      "unitCount": 1,
      "seller": "Synthetic demo retailer",
      "advertisedPrice": "9.99",
      "sourceUrl": "https://example.com/product",
      "observedAt": "2026-10-20T11:00:00Z",
      "sourceHealthy": true,
      "priceType": "public_advertised",
      "availability": "in_stock"
    }
  ],
  "maxAgeHours": 24
}
```

# Actor output Schema

## `results` (type: `string`):

One row per unique observation, including review records.

## `report` (type: `string`):

Counts, results and the evidence notice.

## `review` (type: `string`):

Readable results and review reasons.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "references": [
        {
            "sku": "001",
            "variant": "blue",
            "market": "US",
            "currency": "USD",
            "unitCount": 1,
            "referencePrice": "10.00"
        }
    ],
    "observations": [
        {
            "sku": "001",
            "variant": "blue",
            "market": "US",
            "currency": "USD",
            "unitCount": 1,
            "seller": "Synthetic demo retailer",
            "advertisedPrice": "9.99",
            "sourceUrl": "https://example.com/product",
            "observedAt": "2026-10-20T11:00:00Z",
            "sourceHealthy": true,
            "priceType": "public_advertised",
            "availability": "in_stock"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sah-designs/retail-price-exception-auditor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "references": [{
            "sku": "001",
            "variant": "blue",
            "market": "US",
            "currency": "USD",
            "unitCount": 1,
            "referencePrice": "10.00",
        }],
    "observations": [{
            "sku": "001",
            "variant": "blue",
            "market": "US",
            "currency": "USD",
            "unitCount": 1,
            "seller": "Synthetic demo retailer",
            "advertisedPrice": "9.99",
            "sourceUrl": "https://example.com/product",
            "observedAt": "2026-10-20T11:00:00Z",
            "sourceHealthy": True,
            "priceType": "public_advertised",
            "availability": "in_stock",
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("sah-designs/retail-price-exception-auditor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "references": [
    {
      "sku": "001",
      "variant": "blue",
      "market": "US",
      "currency": "USD",
      "unitCount": 1,
      "referencePrice": "10.00"
    }
  ],
  "observations": [
    {
      "sku": "001",
      "variant": "blue",
      "market": "US",
      "currency": "USD",
      "unitCount": 1,
      "seller": "Synthetic demo retailer",
      "advertisedPrice": "9.99",
      "sourceUrl": "https://example.com/product",
      "observedAt": "2026-10-20T11:00:00Z",
      "sourceHealthy": true,
      "priceType": "public_advertised",
      "availability": "in_stock"
    }
  ]
}' |
apify call sah-designs/retail-price-exception-auditor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sah-designs/retail-price-exception-auditor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UsdaKSZevdXhc3yZ5/builds/jq58eezFBgcAgUzIj/openapi.json