# Coles Stock Checker & API: Prices & Specials by Store (`s_actors/coles-stock-checker`) Actor

Coles stock checker and API: exact stock count, price, specials, half price and multibuy deals and unit price at every Coles store near your postcode or suburb. Search, categories, the whole specials catalogue or product links. Scheduled runs = restock and price drop alerts.

- **URL**: https://apify.com/s_actors/coles-stock-checker.md
- **Developed by:** [Superior Actors](https://apify.com/s_actors) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.63 / 1,000 product rows

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

### Coles Stock Checker & API: Prices & Specials by Store

**See how many units of a product each Coles store near any Australian postcode or suburb has right now, with that store's price, special and unit price.** Check a search (`tim tam`, `nappies`, `coffee pods`), a category, the whole specials catalogue (`specials`, `half price`, `multibuy`) or exact product links at up to 50 nearest Coles supermarkets per postcode, nearest first, with store address, phone, opening hours and distance.

Every row also has the shelf price, was price, savings and % off, promotion text ("1/2 Price", "Pick any 2 for $9"), unit price ($1.75 per 100 g), purchase limits, brand, size, category and image, so the same Actor is a full **Coles scraper** for prices and the weekly specials. Turn on **Barcode, ingredients and nutrition** for EAN barcodes, ingredients, allergens, nutrition per 100 g and country of origin.

Scheduled runs with **Only report changes** become **Coles restock and price drop alerts**: a row only when a store gets a product back in stock or restocked, sells out, a special starts or ends, the price changes, or a new product appears in your search or category.

Use cases: track products & prices, get deal & restock alerts, compare stock between stores, build grocery price datasets. No login, no browser: a **Coles stock checker** and **Coles API** that returns JSON, CSV or Excel.

#### What makes it different

| | |
| --- | --- |
| 🏬 **Exact units at every store near you** | `stockQuantity` = the units Coles has at that store (e.g. 16 at Wynyard, 1 at York Street), up to 50 nearest stores per postcode or suburb, nearest first with distance in km |
| 💲 **The store's own price** | Prices, specials and range are read for each store, so regional prices (Darwin, Perth, Hobart) and store-only ranges are right |
| 🔔 **Restock alerts** | `back_in_stock`, `restocked`, `out_of_stock`, `special_started`, `special_ended`, `price_drop`, `price_rise`, `new_product`, store by store; unchanged rows are free |
| 🏷️ **Whole specials catalogue** | `specials` (~8 000 products a week), `half price`, `multibuy`, `online only`, plus a minimum % off filter |
| 📍 **Postcode or suburb in, stores out** | `2000`, `3000`, `Bondi Junction`, `Parramatta`: store number, address, suburb, state, phone, hours, coordinates |
| 🧾 **Barcode and nutrition** | EAN barcode, ingredients, allergens, nutrition per 100 g, serving size and country of origin on request |

#### Example

Input: search `tim tam`, postcode `2000` (Sydney CBD), 5 nearest stores. Real run, 15 Oct 2026, units in stock:

| Product | Price | Wynyard 0.6 km | York St 1.1 km | Pyrmont 1.1 km | World Square 1.8 km | Kings Cross 2.4 km |
| --- | --- | --- | --- | --- | --- | --- |
| Tim Tam Original Large Pack 365g | $6.40 (was $8) | 16 | 1 | 11 | 62 | 11 |
| Tim Tam Original 200g | $6.00 | 223 | 172 | 154 | 505 | 277 |
| Tim Tam Double Coat 200g | $6.00 | 23 | 112 | 135 | 304 | 237 |
| Tim Tam Deluxe Triple Choc 175g | $5.00 | 6 | 10 | 27 | 11 | 21 |
| Tim Tam Deluxe Salted Caramel Brownie 175g | $5.00 | 21 | 1 | 24 | 52 | 20 |
| Tim Tam Iced Vovo 175g | $6.00 | 0 | 149 | 45 | 135 | 23 |

8 products × 5 stores = 40 rows in about 30 seconds.

#### Input

| Field | What it does |
| --- | --- |
| **Search terms** | e.g. `tim tam`, `milk`, `coffee pods`; each term is searched at every chosen store |
| **Postcodes or suburbs (store stock)** | e.g. `2000`, `Bondi Junction`; empty = Coles online prices and stock without a store |
| **Stores per postcode**, **Radius (km)** | 3 stores within 25 km by default; up to 50 stores |
| **Coles store numbers** | Exact stores by number (`853`), from the `storeId` column of an earlier run |
| **Categories and specials** | A category link (`https://www.coles.com.au/browse/dairy-eggs-fridge/milk`), path (`dairy-eggs-fridge/milk`), top category (`Pantry`), or `specials`, `half price`, `multibuy`, `online only` |
| **Products** | Product links (`https://www.coles.com.au/product/arnott-s-tim-tam-original-chocolate-biscuit-large-pack-365g-6634760`) or ids (`6634760`) |
| **Max products per query and store**, **Sort by** | 100 by default, 0 = all; relevance, price, unit price or best sellers |
| **Only specials**, **Minimum discount %**, **Only in stock** | Filters: you pay only for returned rows |
| **Barcode, ingredients and nutrition** | One extra request per product |
| **Only report changes**, **Monitor name** | Restock and price alerts for scheduled runs |

#### Output

| Field | Example |
| --- | --- |
| `name`, `brand`, `size`, `productId` | Tim Tam Original Chocolate Biscuit Large Pack, Arnott's, 365g, 6634760 |
| `stockQuantity`, `inStock`, `availabilityType` | 16, true, InStoreAndOnline |
| `price`, `wasPrice`, `savings`, `discountPercent` | 6.4, 8, 1.6, 20 |
| `isOnSpecial`, `promotion`, `multibuy`, `isOnlineSpecial` | true, 1/2 Price (or "Pick any 2 for $9"), Pick any 2 for $9, false |
| `unitPrice`, `unitMeasure`, `unitPriceText` | 1.75, 100 g, $1.75/ 100g |
| `purchaseLimit`, `specialLimit` | 20, 12 |
| `storeId`, `storeName`, `storeAddress`, `storeSuburb`, `storeState`, `storePostcode` | 840, Coles Central Wynyard Express, Wynyard St & Carrington St, Sydney, NSW, 2000 |
| `storePhone`, `storeHours`, `distanceKm`, `storeLatitude`, `storeLongitude`, `location` | (02) 7231 7900, Mon-Fri: 6am - 10pm…, 0.59, -33.87, 151.21, 2000 (what you gave) |
| `department`, `category`, `subcategory` | Chips, Chocolates & Snacks, Biscuits & Cookies, Chocolate Biscuits |
| `barcode`, `ingredients`, `allergens`, `nutritionPer100`, `countryOfOrigin` | 9310072010816, Milk Chocolate (38%)…, Contains Gluten, Milk, Soy…, {"Energy": "2200 kJ", …}, Australia |
| `url`, `imageUrl` | coles.com.au product page, image |
| `query`, `position`, `scrapedAt` | the search, category or product the row came from, its place in the results |
| `change`, `previousStockQuantity`, `previousPrice`, `priceChange` | restocked, 4, 6.4, 0 (monitoring) |

With postcodes each row is one product at one store; without, one product with Coles online prices and stock.

#### Pricing

Pay per event: **$0.001** per run and **$0.00079** per returned row ($0.79 per 1 000 rows). Apify Scale plan: $0.711 per 1 000, Business plan and above: $0.632 per 1 000.

| Example | Cost |
| --- | --- |
| 20 products at 5 stores near a postcode (100 rows) | ~$0.08 |
| This week's half price specials at one store (~1 900 rows) | ~$1.50 |
| Restock alert: 10 products at 3 stores every hour, 5 changes a day | ~$0.028 a day (~$0.85 a month) |

#### FAQ

**How do I check Coles stock in store?** Put the product link (or a search such as `tim tam`) and your postcode or suburb in the input. Each row is one nearby Coles store with the number of units it has, its price and its special.

**Is the stock number exact?** It is the available quantity Coles itself uses for that store's online orders and click & collect, updated by Coles through the day. Shelves can differ by a few units from the system count.

**Does Coles have an API for prices and stock?** coles.com.au runs on JSON endpoints, and this Actor calls them for you and returns clean rows, so you get a ready Coles product, price and stock API without keys or setup. Call it from your code with the Apify API, or schedule it and download CSV / Excel.

**How do I get this week's Coles half price specials?** Put `half price` (or `specials` for every special) in **Categories and specials**, set **Max products** to 0, and add your postcode for your store's prices. Save it as a task and schedule it every Wednesday.

**Can I get alerts when an item is back in stock?** Yes: add the products, your postcode, turn on **Only report changes**, save it as a task and schedule it hourly or daily. Connect email, Slack or [Google Sheets](https://apify.com/s_actors/google-sheets-import-export) in Integrations.

**Why was a store skipped?** A few Coles stores (some Coles Central stores in city centres) have no online range: coles.com.au cannot show products for them. The Actor checks every store first and takes the next nearest one instead.

**Which states are covered?** Every Coles supermarket in NSW, ACT, VIC, QLD, SA, WA, TAS and NT.

#### Tips

- Each store is one more search per query: 3 stores = 3 times the rows. Use **Coles store numbers** for a fixed set of stores.
- For a restock watchlist use **Products** with links: the same products every run, each found in every store's results for the exact unit count.
- Use a separate **Monitor name** for each scheduled task.

#### Limits

- Coles Australia (coles.com.au) supermarkets only; Liquorland and Coles Express stores are not included.
- Aisle locations are shown only where Coles publishes them (mostly fresh produce).
- Searches by barcode are not supported by Coles: use product links or ids.

#### Other Australian supermarket tools

| Actor | What it does |
| --- | --- |
| [Coles vs Woolworths vs ALDI Price Comparison & API](https://apify.com/s_actors/coles-woolworths-aldi-price-comparison) | One shopping list priced at Coles, Woolworths and ALDI side by side: cheapest store per item, same-product matches, basket totals |
| [Woolworths Scraper & API](https://apify.com/s_actors/woolworths-scraper) | Woolworths Australia prices, specials, half price and multibuy deals, stock, barcodes and nutrition |
| [ALDI Stock Checker & API](https://apify.com/s_actors/aldi-stock-checker) | ALDI Australia Special Buys stock at every store near a postcode, prices and Special Buys dates |

#### For AI agents and API

```json
{
    "searchTerms": ["tim tam"],
    "locations": ["2000", "Bondi Junction"],
    "storesPerLocation": 5,
    "products": ["https://www.coles.com.au/product/arnott-s-tim-tam-original-chocolate-biscuit-large-pack-365g-6634760"],
    "categories": ["half price"],
    "maxItemsPerQuery": 0,
    "inStockOnly": true,
    "onlyChanges": true,
    "monitorName": "coles-restock"
}
```

Each row is one product at one store with `stockQuantity`, `price`, `wasPrice`, `promotion`, `storeName`, `distanceKm` and the product link.

# Actor input Schema

## `searchTerms` (type: `array`):

What to search on coles.com.au, one per line (e.g. "milk", "tim tam", "pokemon cards"). Each term is searched at every chosen store.

## `locations` (type: `array`):

Australian postcodes or suburbs, one per line (2000, 3000, "Bondi Junction"). For each, the stock count, price and specials of every product at the nearest Coles supermarkets. Empty = Coles online prices and stock without a store.

## `storesPerLocation` (type: `integer`):

How many of the nearest Coles supermarkets to check around each postcode or suburb (up to 50).

## `radiusKm` (type: `integer`):

Only stores this close to the postcode or suburb.

## `storeIds` (type: `array`):

Exact Coles stores by number, one per line (853 = Coles Bondi Westfield). The number is the storeId column of an earlier run. Store address columns stay empty for these.

## `categories` (type: `array`):

Whole Coles categories, one per line: a category link (https://www.coles.com.au/browse/dairy-eggs-fridge/milk), its path ("dairy-eggs-fridge/milk") or a top category name ("Pantry"). "specials" = the whole specials catalogue of the week, also "half price", "multibuy" and "online only".

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

Exact products, one per line: a coles.com.au product link (https://www.coles.com.au/product/arnott-s-tim-tam-original-chocolate-biscuit-large-pack-365g-6634760) or its id (6634760). Best for a restock watchlist.

## `maxItemsPerQuery` (type: `integer`):

How many products to take from each search term or category at each store (48 per Coles page). 0 = all of them.

## `sortBy` (type: `string`):

The order of coles.com.au, which decides the products taken when there is a limit.

## `specialsOnly` (type: `boolean`):

Return only products on special this week (price cuts, half price, multibuy).

## `minDiscountPercent` (type: `integer`):

Return only specials at least this much below the regular price (e.g. 50 = half price). Empty = any.

## `inStockOnly` (type: `boolean`):

Skip products with no stock at the store.

## `includeDetails` (type: `boolean`):

Add the barcode (EAN), description, ingredients, allergens, nutrition per 100 g and country of origin. One extra request per product: slower on big runs.

## `onlyChanges` (type: `boolean`):

For scheduled runs. The first run saves stock and prices; later runs return only what changed at each store: back in stock, restocked, out of stock, specials started or ended, price drops and rises, new products. You pay only for the changes returned.

## `monitorName` (type: `string`):

Separate monitors keep separate memory. Use a different name for each scheduled task.

## `maxConcurrency` (type: `integer`):

How many requests run at the same time.

## Actor input object example

```json
{
  "searchTerms": [
    "tim tam"
  ],
  "locations": [
    "2000"
  ],
  "storesPerLocation": 2,
  "radiusKm": 25,
  "maxItemsPerQuery": 20,
  "sortBy": "relevance",
  "specialsOnly": false,
  "inStockOnly": false,
  "includeDetails": false,
  "onlyChanges": false,
  "monitorName": "default",
  "maxConcurrency": 4
}
```

# Actor output Schema

## `overview` (type: `string`):

Each product at each store: stock count, price, special, store and distance.

## `specials` (type: `string`):

Price cuts, half price and multibuy deals with savings and limits.

## `changes` (type: `string`):

Monitoring: back in stock, restocked, out of stock, specials, price drops, new products.

## `stores` (type: `string`):

Store number, address, phone, hours and coordinates of every row.

## `catalog` (type: `string`):

Product id, brand, size, category, price and unit price of every product.

## `details` (type: `string`):

With "Barcode, ingredients and nutrition" on: barcode, ingredients, allergens, nutrition, origin.

## `all` (type: `string`):

Every field of every row.

# 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 = {
    "searchTerms": [
        "tim tam"
    ],
    "locations": [
        "2000"
    ],
    "storesPerLocation": 2,
    "maxItemsPerQuery": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("s_actors/coles-stock-checker").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 = {
    "searchTerms": ["tim tam"],
    "locations": ["2000"],
    "storesPerLocation": 2,
    "maxItemsPerQuery": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("s_actors/coles-stock-checker").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 '{
  "searchTerms": [
    "tim tam"
  ],
  "locations": [
    "2000"
  ],
  "storesPerLocation": 2,
  "maxItemsPerQuery": 20
}' |
apify call s_actors/coles-stock-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,s_actors/coles-stock-checker"
        }
    }
}
```

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/epzXo0JGA8cNpOtlF/builds/ZGmt45CkWefCHmH1m/openapi.json