# NZ Price Monitor | $1.70/1K product checks (`architekture/nz-price-monitor`) Actor

NZ grocery price monitor for Woolworths NZ, PAK'nSAVE, New World, Four Square, FreshChoice and SuperValue: watch products by name, barcode or URL, get one price snapshot per run, price history, and drop, threshold and back-in-stock alerts by webhook or email.

- **URL**: https://apify.com/architekture/nz-price-monitor.md
- **Developed by:** [architek.earth](https://apify.com/architekture) (community)
- **Categories:** E-commerce
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.36 / 1,000 product checks

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## NZ Grocery Price Monitor API — Price History, Matching, Alerts

Free tier: watch up to 10 products weekly across all six New Zealand chains, 4 runs per account, never charged. Paid monitoring costs $0.0017 per product found at a chain, so 100 products checked daily at all six chains costs about $25 a month.

**Recorded run: 120 product checks from 20 products in 76 seconds** (2026-11-15, build 0.1.2, run `GQUfg3EPomPB3kGLu`). 99 of 120 matched; a bounded weekly-basket sample.

architek.earth — an independent data studio. Pay-per-result scrapers with recorded runs, published canaries and stable schemas, built for people and AI agents.

Watch a list of groceries at Woolworths NZ, PAK'nSAVE, New World, Four Square, FreshChoice and SuperValue. Each run saves one price snapshot per product and chain, keeps the history in your account, and raises alerts when a price drops, crosses your threshold or comes back in stock.

### ✅ Why choose this scraper

#### Six chains, one list

Give products by name ("anchor blue milk 2l"), barcode or product URL. Each run checks every product at every chain you pick and returns one row per product and chain.

#### Matching you can audit

Barcodes match first. Otherwise names and pack sizes are compared and every match carries a `confidence` score and `matchMethod`. Different pack sizes (1L vs 2L, 3 x 420g vs 420g) and different variants (Diet, Decaf, Unsalted) are not accepted as matches. Anything below your threshold comes back as `unmatched` with its best candidates, never silently dropped.

#### History and alerts without a database

Snapshots accumulate in a named dataset in your account, one per watchlist. Each row carries `previousPrice` and `change`. Alerts compare against the previous run: price drop of at least X%, price at or below a threshold, back in stock. Alerts land in the dataset and, if you want, at a webhook or an email address.

#### You pay for prices found, nothing else

One charge per product found at a chain. Unmatched products, a chain whose source failed, and free-tier runs cost nothing. A run with a failed source is marked `PARTIAL` and says which chain.

### ⚠️ Worth knowing up front

- **Four Square lists weekly specials only.** It has no online catalogue, so a product matches there only in a week it is on special (3 of 20 in the recorded basket).
- **SuperValue covers one store.** Only SuperValue Milton has an online catalogue.
- Each chain is checked at one store per run (defaults: PAK'nSAVE Royal Oak, New World Thorndon, Four Square Ohope Beach, FreshChoice Queenstown, SuperValue Milton; Woolworths NZ prices are national online prices). Set `stores` to choose others.
- Generic names ("potatoes", "sliced ham") match the closest product a chain sells. For precise tracking give brand and size ("pics peanut butter 380g") or a barcode.
- Prices are the online shelf prices each site shows. Club and loyalty prices are reported in `promo` where the source gives them, never in `price`.
- One run takes about one to three minutes for 20 products; larger lists take longer. Schedule it yourself (daily or weekly) or use the example tasks.
- A run that stops early writes one free status row (`"recordType": "status"`) that says why. `RUN_SUMMARY` records every source run, its cost and the history dataset ID.

### ⚡ Try the example

Turn on `freeTier`, paste a list and start the run:

```json
{
  "products": ["anchor blue milk 2l", "tip top bread white", "mainland butter 500g", "weet-bix 750g", "chelsea white sugar 1.5kg"],
  "watchlistName": "my-basket",
  "freeTier": true
}
```

#### Example task: weekly basket across NZ chains

Twenty everyday products, all six chains, weekly. Schedule it on Monday mornings and compare `price` and `unitPrice` by `item` across chains.

```json
{
  "products": ["anchor blue milk 2l", "tip top bread white", "mainland butter 500g", "eggs 12 pack", "bananas", "weet-bix 750g", "flour 1.5kg", "chelsea white sugar 1.5kg", "watties baked beans 420g", "pics peanut butter", "coca-cola 1.5l", "bell tea bags", "nescafe classic coffee", "long grain rice 1kg", "spaghetti 500g", "cheddar cheese 1kg", "frozen peas 1kg", "sliced ham", "apples", "potatoes"],
  "watchlistName": "weekly-basket",
  "frequency": "weekly",
  "freeTier": false
}
```

#### Example task: daily drop alerts on my 25 products

Your own 25 products, daily, with a 10% drop alert and a webhook.

```json
{
  "products": [{"name": "anchor blue milk 2l", "maxPrice": 4.5}, {"barcode": "9415007012345"}, "mainland butter 500g"],
  "watchlistName": "my-25",
  "frequency": "daily",
  "dropPercent": 10,
  "backInStock": true,
  "webhookUrl": "https://example.com/price-alerts",
  "freeTier": false
}
```

### ⚙️ Input

| Parameter | Type | Default | Description |
|---|---|---|---|
| `products` | array | prefilled basket | Up to 500. A name, or `{"name", "barcode", "url", "size", "maxPrice"}`. |
| `watchlistName` | string | `my-watchlist` | Names the history dataset and comparison store. Keep it the same across runs. |
| `chains` | array | all six | `woolworths-nz`, `paknsave`, `new-world`, `foursquare`, `freshchoice`, `supervalue`. |
| `stores` | object | `{}` | Store per chain, for example `{"new-world": "New World Queenstown", "freshchoice": "papamoa"}`. |
| `frequency` | select | `weekly` | `weekly` or `daily`; the free tier is weekly. |
| `dropPercent` | integer | `10` | Alert on a drop of at least this percent since the previous run. `0` turns it off. |
| `priceAtOrBelow` | number | none | Alert when a price crosses to this level or lower. Per-product `maxPrice` overrides it. |
| `backInStock` | boolean | `true` | Alert when a product that was unavailable or unmatched is found again. |
| `freeTier` | boolean | `false` (pre-selected in the form) | Up to 10 products, weekly, 4 runs per account, never charged. |
| `webhookUrl` | string | none | Alerts are POSTed here as JSON. |
| `notificationEmail` | string | none | Alerts are emailed here. |
| `matchThreshold` | number | `0.6` | Name and size matches below this confidence are reported as unmatched. |
| `candidatesPerProduct` | integer | `5` | Search results considered per product and chain. |
| `feedback` | string | none | Optional note for the maintainers. Read by a human; never changes output. |

### 🧱 Stable fields

Fields are only ever added, never renamed or removed.

| Field | Type | Meaning |
|---|---|---|
| `recordType` | string | `snapshot`, `alert` or `status`. |
| `watchId` | string | Stable ID of the watched product. |
| `item` | string | The product as you wrote it. |
| `chain` | string | Chain key, for example `paknsave`. |
| `chainLabel` | string | Chain name. |
| `status` | string | `matched`, `unmatched` or `source_failed`. |
| `confidence` | number | 1.0 for barcode or URL matches; otherwise the name and size score. |
| `matchMethod` | string | `barcode`, `url` or `name+size`. |
| `productName` | string | The chain's product name. |
| `size` | string | The chain's pack size. |
| `price` | number | Shelf price in NZD. |
| `unitPrice` | number | Unit price in NZD, where published. |
| `unitLabel` | string | Unit basis, for example `1L` or `per 100g`. |
| `wasPrice` | number | Price before a special, where published. |
| `promo` | string | Special, club price or promotion note. |
| `inStock` | boolean | Where the chain publishes stock. |
| `previousPrice` | number | Price in the previous run, when both matched. |
| `change` | number | `price - previousPrice`. |
| `productChanged` | boolean | True when a different product matched than last run; no comparison or price alert is made. |
| `url` | string | Product page. |
| `store` | string | Store the price applies to. |
| `reason` | string | Why a row is unmatched, failed or partial. |
| `observedAt` | string | ISO timestamp of the run. |
| `rule`, `message` | string | On alert rows: `price_drop`, `price_at_or_below` or `back_in_stock`, and a readable message. |

### 📦 Output example

A matched row from run `GQUfg3EPomPB3kGLu`:

```json
{
  "recordType": "snapshot",
  "item": "chelsea white sugar 1.5kg",
  "chain": "paknsave",
  "chainLabel": "PAK'nSAVE",
  "status": "matched",
  "confidence": 1.0,
  "matchMethod": "name+size",
  "productName": "White Sugar",
  "size": "1.5kg",
  "price": 3.29,
  "url": "https://www.paknsave.co.nz/shop/product/...",
  "observedAt": "2026-11-15T06:16:23+00:00"
}
```

An unmatched row keeps its candidates:

```json
{"recordType": "snapshot", "item": "anchor blue milk 2l", "chain": "foursquare", "status": "unmatched", "reason": "best candidate below 0.6 (Four Square lists weekly specials only)", "candidates": [{"name": "Pineapples", "price": 4.99, "confidence": 0.0}]}
```

### 🧠 Advanced usage

#### Price history for one product

Open the `historyDatasetId` from `RUN_SUMMARY` (dataset `nz-price-monitor-<watchlistName>` in your storage) and filter by `watchId` and `chain`.

#### Cheapest chain per product

Within one run, group `snapshot` rows by `item` and take the lowest `unitPrice` (or `price`) among `matched` rows.

#### Precise matching

Give barcodes where you have them, or a product URL from one chain plus a name. Raise `matchThreshold` to 0.8 to accept only close name and size matches.

### 🔌 Integrations

Snapshots and alerts are a standard dataset: download JSON, CSV or Excel, read them over the API, or trigger your own process from the webhook. A schedule makes the monitor hands-off.

### 💸 Pricing

| Event | Price | When |
|---|---|---|
| Product check | $0.0017 | One watched product found and priced at one chain in one run. |

100 products checked daily at six chains: about 495 matched checks per run, about $0.84 per run, about $25 a month. 25 products daily: about $6 a month. Unmatched products, failed sources, status rows and free-tier runs are free.

#### Store discounts

The primary `product-check` event keeps its full price for Free and Bronze users. Silver users receive 10% off; Gold, Platinum and Diamond users receive 20% off. Other event prices and free-preview limits are unchanged. The price applied to your run is shown in the Console.

### ❓ FAQ

#### Why did a product not match at a chain?

Either the chain does not sell it, the closest product is a different size or variant, or (Four Square) it is not on special this week. The row lists the best candidates so you can refine the name.

#### Can I watch AU supermarkets?

Not yet. The monitor reads each chain through a source adapter, so Australian chains can be added without changing how matching, history or alerts work.

#### Can an AI assistant run this?

Yes. AI assistants and agents can start it through the Apify API with the JSON input above and read the snapshot and alert rows back; the stable fields and free status rows are designed for that.

### 🤖 For AI agents & LLM apps

Use the published input schema to provide a watchlist and a persistent state key. Inspect match confidence and source status before acting on a price alert. Keep the same state key on recurring runs to compare prices with the previous snapshot.

### 🧰 More from architek.earth

**New Zealand prices:** [Woolworths NZ](https://apify.com/architekture/woolworths-nz-scraper), [PAK'nSAVE](https://apify.com/architekture/paknsave-nz-scraper), [New World](https://apify.com/architekture/new-world-nz-scraper), [Four Square](https://apify.com/architekture/foursquare-nz-scraper), [FreshChoice](https://apify.com/architekture/freshchoice-nz-scraper), [SuperValue](https://apify.com/architekture/supervalue-nz-scraper), NZ Price Monitor (this actor).

architek.earth · code like concrete

### 🙋 Support & legal

Questions or a product that will not match: open an issue on this page or use the `feedback` input. This monitor reads publicly available prices only, uses no login or account, and is not affiliated with the retailers.

architek.earth

### 📝 Changelog

- **2026-11-16** — Support approved primary-event Store discount tiers; retain exact event checks and existing preview limits.

- **2026-11-15** — 0.1 first release. Six NZ chains, barcode and name+size matching, history, drop, threshold and back-in-stock alerts, webhook and email delivery.

# Actor input Schema

## `products` (type: `array`):

Up to 500. Each is a name ("anchor blue milk 2l") or an object {"name", "barcode", "url", "size", "maxPrice"}. Barcode matches first; otherwise name and size with a confidence score.

## `watchlistName` (type: `string`):

Names the history dataset and comparison store in your account. Keep it the same across runs to get history and alerts.

## `chains` (type: `array`):

Which chains to check. Default: all six.

## `stores` (type: `object`):

Store per chain, for example {"paknsave": "<store id>", "new-world": "New World Thorndon", "freshchoice": "queenstown"}. Blank uses each chain's default store.

## `frequency` (type: `string`):

How often you schedule this monitor. The free tier is weekly.

## `dropPercent` (type: `integer`):

Alert when a price falls by at least this much since the previous run. 0 turns it off.

## `priceAtOrBelow` (type: `number`):

Optional. Alert when a price crosses to this level or lower. Per-product maxPrice overrides it.

## `backInStock` (type: `boolean`):

Alert when a product that was unavailable or unmatched is found again.

## `freeTier` (type: `boolean`):

Up to 10 products, weekly, 4 runs per account, never charged. Turn off for paid monitoring.

## `webhookUrl` (type: `string`):

Alerts are POSTed here as JSON when any fire.

## `notificationEmail` (type: `string`):

Alerts are emailed here when any fire.

## `matchThreshold` (type: `number`):

Name and size matches below this confidence are reported as unmatched, with candidates.

## `candidatesPerProduct` (type: `integer`):

Search results considered per product and chain.

## `feedback` (type: `string`):

Tell us what you needed and did not get. Read by a human; never changes the output.

## Actor input object example

```json
{
  "products": [
    "anchor blue milk 2l",
    "tip top bread white",
    "mainland butter 500g",
    "eggs 12 pack",
    "bananas",
    "weet-bix 750g",
    "flour 1.5kg",
    "chelsea white sugar 1.5kg",
    "watties baked beans 420g",
    "pics peanut butter"
  ],
  "watchlistName": "my-watchlist",
  "chains": [
    "woolworths-nz",
    "paknsave",
    "new-world",
    "foursquare",
    "freshchoice",
    "supervalue"
  ],
  "stores": {},
  "frequency": "weekly",
  "dropPercent": 10,
  "backInStock": true,
  "freeTier": true,
  "matchThreshold": 0.6,
  "candidatesPerProduct": 5
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

# 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 = {
    "products": [
        "anchor blue milk 2l",
        "tip top bread white",
        "mainland butter 500g",
        "eggs 12 pack",
        "bananas",
        "weet-bix 750g",
        "flour 1.5kg",
        "chelsea white sugar 1.5kg",
        "watties baked beans 420g",
        "pics peanut butter"
    ],
    "freeTier": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("architekture/nz-price-monitor").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 = {
    "products": [
        "anchor blue milk 2l",
        "tip top bread white",
        "mainland butter 500g",
        "eggs 12 pack",
        "bananas",
        "weet-bix 750g",
        "flour 1.5kg",
        "chelsea white sugar 1.5kg",
        "watties baked beans 420g",
        "pics peanut butter",
    ],
    "freeTier": True,
}

# Run the Actor and wait for it to finish
run = client.actor("architekture/nz-price-monitor").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 '{
  "products": [
    "anchor blue milk 2l",
    "tip top bread white",
    "mainland butter 500g",
    "eggs 12 pack",
    "bananas",
    "weet-bix 750g",
    "flour 1.5kg",
    "chelsea white sugar 1.5kg",
    "watties baked beans 420g",
    "pics peanut butter"
  ],
  "freeTier": true
}' |
apify call architekture/nz-price-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,architekture/nz-price-monitor"
        }
    }
}
```

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/hVzTsGMhlM6lyelnw/builds/NmlaQMfbgkTb3ujWn/openapi.json
