Coles AU Product Lookup API – AI & MCP

Fast, low-overhead Coles Australia product search and single-product lookup for AI agents, MCP tools, API workflows, and chat assistants. It returns a compact, normalized JSON contract with explicit current price, regular price, unit price, stock/availability, specials, identifiers, links, and item-level enrichment.

Best for 1–7 product results per call. Search is hard-capped at 10 results. For 8+ products, category crawling, catalog extraction, scheduled monitoring, or bulk research, use the full dromb/coles-au-product-search-specials-stores-unofficial Actor instead.

Choose the right Actor

Need	Recommended Actor
1–7 products	This AI Lookup Actor
One exact product	This AI Lookup Actor
MCP / AI agent / chatbot tool call	This AI Lookup Actor
8+ products	dromb/coles-au-product-search-specials-stores-unofficial
Categories / taxonomy / broad monitoring	dromb/coles-au-product-search-specials-stores-unofficial
Bulk catalog or research workflows	dromb/coles-au-product-search-specials-stores-unofficial

Agent quick start

Search

{
  "operation": "search",
  "query": "full cream milk",
  "maxResults": 5
}

The Actor returns at most maxResults product records. The default is 5 and the maximum is 10.

• Optional postcode adds Coles location-aware price/availability context.

Exact item lookup

{
  "operation": "item",
  "productId": "8150288"
}

You can use url instead of productId. For item, provide exactly one of these two fields, not both.

{
  "operation": "item",
  "url": "https://www.coles.com.au/..."
}

A common agent flow is:

search → select the best candidate → item

Use the returned productId from search for the follow-up item call.

Search responses deliberately omit rich enrichment (description, ingredients, allergens, nutrition) to reduce token overhead. Call item for those fields.

Input contract

Field	Type	Purpose
operation	search or item	Select a bounded workflow
query	string	Required for search
maxResults	integer 1–10	Search result cap; default 5
productId	string	Exact item identifier; use exactly one of productId / url for item
url	string	Exact product URL alternative; use exactly one of productId / url for item
postcode	4-digit string	Optional Coles location context

No category crawler, raw payload, reverse-barcode experiment, pagination control, or other bulk-only fields are exposed here. The small schema is intentional so agents can choose and call the tool reliably.

Output contract for AI agents

Every product result uses the same normalized field names:

• currentPrice — current effective AUD price; this is the price to quote as the present price.
• regularPrice — previous/regular AUD price only when an active discount is known; otherwise null.
• unitPrice, unitQuantity, unitUnit — comparable unit-pricing fields when available.
• onSpecial, promotionType, promotionLabel — promotion signals.
• inStock — true/false when known; null means unknown, not false.
• productId, productUrl, barcode — identifiers for follow-up work.
• description, ingredients, allergens, nutrition — intentionally null in search results to keep agent payloads compact; populated by item lookup when available.
• fetchedAt — UTC timestamp for this lookup.
• query — populated for search; always null for direct item lookups.

The Dataset Schema includes title, description, and example metadata for each field so MCP/LLM clients do not have to guess field semantics.

No results and failures

A successful lookup with no product match writes a free control record:

{
  "recordType": "status",
  "status": "no_results",
  "message": "No matching Coles products were found."
}

A real upstream/source failure is not disguised as no_results: the Actor writes a machine-readable source_error status record and fails the run. If a spending limit stops a multi-result response, a partial_results status record explains how many product rows were published.

Pricing design

This Actor is designed for small, agentic calls:

• Actor start: target configuration apify-actor-start at $0.00005 per start unit (up to 1 GB memory = one start event).
• Product result: target BRONZE price $0.0018 per successfully published product.
• Status/error records are not product-result events.
• Synthetic default Dataset item charging must remain disabled / $0 so status rows stay free.
• No separate enrichment fee.
• Platform usage is intended to be included in the event price (PPE + usage disabled) for predictable agent costs.

The Store pricing panel is authoritative for the active tier prices. For larger result sets, the separate bulk Actor is intentionally cheaper per row.

Recommended agent decision flow

1. Inspect the input schema and choose search for discovery or item for an exact lookup.
2. Start with maxResults: 3–5 for search.
3. Read Dataset product rows and select by productId, name, price, and availability.
4. Chain the selected productId into item when richer details are needed.
5. Treat recordType: status as control information, not a product.
6. Treat a failed run with invalid_input or source_error as a real failure; do not invent product data.

MCP / agent usage

This Actor is intended to be discoverable through Apify MCP and Apify AI once publication and agentic-payment eligibility are enabled. The tool has a deliberately small input schema and a stable normalized output schema so agents can inspect it, call it, and chain its productId into an exact item lookup.

Reliability and scope

• Australia only (countryCode=AU, currency AUD).
• Search returns the retailer's current live result set, capped locally to 10.\n- Coles can broaden sparse/unknown queries; this AI SKU removes candidates with no meaningful lexical relevance to the query instead of presenting obviously unrelated products as matches.
• Availability can vary by location and time; null means the source did not provide a reliable signal.
• Product details and promotions can change after fetchedAt.

Bulk alternative

Use dromb/coles-au-product-search-specials-stores-unofficial when you need larger searches, categories, catalog-oriented extraction, monitoring, or retailer-specific advanced workflows. The two Actors share the same proven retailer source logic but are packaged and priced for different workloads.

Unofficial

This is an independent data-access tool and is not affiliated with or endorsed by Coles.