# Promo Pulse — Belgian Supermarket Promo Tracker (`studio-amba/promo-pulse`) Actor Scheduled meta-scraper that tracks a fixed shelf of products at Lidl, Action and Colruyt Belgium, diffs prices against the previous run, and emits only promo START/STOP and price-change events — not a full re-export. - **URL**: https://apify.com/studio-amba/promo-pulse.md - **Developed by:** [Studio Amba](https://apify.com/studio-amba) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 promo/price events 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Promo Pulse Tracks a fixed shelf of products at Lidl, Action and Colruyt Belgium on a schedule, and tells you only what changed since the last run — promo started, promo ended, price dropped, price restored. Not a full price re-export. ### Why use this actor? Most retail scrapers give you a full snapshot every time you run them — hundreds of products, most of which haven't changed since yesterday. If you actually want to know when a promotion starts or ends, you end up doing the diffing yourself: storing yesterday's prices somewhere, comparing them to today's, and figuring out which rows actually matter. This actor does that diffing for you. It's a meta-actor: under the hood it calls our own Lidl, Action and Colruyt scrapers, tracks the same set of products every run (the "shelf"), and remembers each product's price and promo status in a persistent, named key-value store — separate from the run's own storage, so it survives across scheduled runs, not just within one. Every run compares the current state to the stored state and only pushes rows for products that actually changed. Useful for price-monitoring tools, deal-alert bots, competitor pricing research, or just watching whether a specific product's promo depth is worth waiting for. ### How to scrape supermarket promotion data (track promotions run-over-run) 1. Pick your stores (or leave the field empty for all 3: Lidl, Action, Colruyt). 2. Run it once. The first run has nothing to compare against, so it seeds its memory with the current price and promo status of every tracked product and pushes one status row per store ("baseline seeded") — no change events yet, because there's no prior run to diff against. 3. Schedule it (see below). Every run after the first compares the current shelf state to what was stored last time and pushes one row per product that changed: a promo starting, a promo ending, a price dropping, or a price going back up. 4. A run where nothing changed still isn't an empty dataset — it pushes a single "zero-delta" status row per healthy store, so you can tell the difference between "nothing changed" and "the run silently failed." ### Scheduling This actor's whole value is in running on a schedule, not as a one-off. In the Apify Console: 1. Open the actor, go to **Schedules → Create new schedule**. 2. Every 6-12 hours is a reasonable cadence — grocery/retail promos don't change more often than that, and running more frequently just burns compute without finding more events. Twice a day (e.g. `0 8,20 * * *`) catches most weekly-cycle promo changes without over-polling. 3. Leave `resetState` off (it's off by default). That flag wipes the actor's memory and would make every scheduled run look like a first run, which defeats the entire point of a diff feed. Only use it manually for testing. 4. Point the schedule's output at an integration (Zapier, Make, a webhook, a Slack channel) that fires per new dataset item, so promo events land wherever you actually watch them, the same run they're detected. ### Input | Field | Type | Required | Description | |-------|------|----------|--------------| | `stores` | Array | No | Which stores to track: `lidl`, `action`, `colruyt`. Empty = all 3. | | `maxResultsPerQuery` | Integer | No | Max products fetched per tracked search query per store (default 15). Action and Colruyt track 4 queries each, so their shelf is roughly 4x this value; Lidl tracks 1 (see Limitations). | | `timeoutPerSourceSecs` | Integer | No | Max wait per underlying store scraper call before it's marked failed and skipped (default 150). | | `proxyConfiguration` | Object | No | Residential proxy passed through to the child scrapers, scoped to Belgium. | | `resetState` | Boolean | No | Testing only — wipes the stored shelf state for every store before this run, so every store re-seeds instead of diffing. Never use this on a real schedule. | ### Output Each row is either a genuine change event or a run-status placeholder. | Field | Type | Example | Description | |-------|------|---------|--------------| | `eventType` | String | `promo_started` | One of `promo_started`, `promo_ended`, `price_dropped`, `price_restored`, or `run_status`. | | `productName` | String | `EVERYDAY Volle melk brik 1L` | Product name, or a status message on a `run_status` row. | | `ean` | String | `""` | Product barcode. Currently always empty — see Limitations. | | `store` | String | `Colruyt` | `Lidl`, `Action`, or `Colruyt`. | | `oldPrice` | Number \| null | `1.11` | Price observed the previous run. | | `newPrice` | Number \| null | `0.89` | Price observed this run. | | `depthPct` | Number \| null | `-20` | Run-over-run price change, negative for a drop, positive for an increase. | | `promoText` | String | `Price dropped 20%` | Human-readable summary of the event. | | `url` | String | `https://www.colruyt.be/nl/producten/17691` | Product page — the stable identity key used to match a product across runs. | | `detectedAt` | String (ISO) | `2026-07-21T13:15:21.552Z` | Timestamp of this run. | #### Example output ```json [ { "eventType": "price_dropped", "productName": "EVERYDAY Volle melk brik 1L", "ean": "", "store": "Colruyt", "oldPrice": 1.11, "newPrice": 0.89, "depthPct": -20, "promoText": "Price dropped 20%", "url": "https://www.colruyt.be/nl/producten/17691", "detectedAt": "2026-07-21T13:15:21.552Z" }, { "eventType": "promo_ended", "productName": "BONI halfvolle melk PET 50cl", "ean": "", "store": "Colruyt", "oldPrice": 0.45, "newPrice": 0.65, "depthPct": 42.9, "promoText": "Promo ended — price restored", "url": "https://www.colruyt.be/nl/producten/1599", "detectedAt": "2026-07-21T13:15:21.552Z" } ] ```` ### Store coverage and how the shelf is defined Each store tracks a fixed set of search queries every run — the same queries, run after run — so the same products keep recurring and can actually be diffed. Rotating the queries would make most products look "new" every time, which defeats the diff. - **Lidl** (`lidl-scraper`): 1 query. Verified live that Lidl's own search API doesn't filter by the `query` text — "chocolade", "koffie" and "wijn" all returned the identical top listing (confirmed: "9288 total found" for every query, the full catalog size, not a filtered count). In practice this returns Lidl's own rotating top listing, dominated by their non-food "weekly offer" items — actually a decent fit for a promo tracker, since that catalog rotates on a fixed weekly cycle. Flagged as a site/actor-level quirk worth healing separately; not something this actor can fix by choosing better keywords. - **Action** (`action-scraper`): 4 queries (`kaars`, `opberger`, `speelgoed`, `decoratie`). Confirmed the search actually filters — each query returns visibly different, relevant products. - **Colruyt** (`colruyt-scraper`): 4 queries (`melk`, `brood`, `kaas`, `pasta`). Confirmed filtering works correctly. Only these 3 were wired. Other grocery children in the fleet (Tesco/Sainsbury's/Asda/Morrisons, Rewe) were left out for this build — Tesco and Sainsbury's are UK/private and would mean mixing currencies and a separate schedule cadence for no real benefit over the Belgian set; Rewe is German and adds a second country's worth of complexity without a second country's worth of value yet. Belgium was chosen because it gave 3 solid, cloud-verified sources with real, distinct promo signals rather than stretching to more, flakier ones. ### Limitations - **No EAN/barcode.** None of the three wired source scrapers (Lidl, Action, Colruyt) currently return a barcode field. The product URL is used as the stable identity key across runs instead — it's reliable, just not a universal barcode. - **Colruyt has no "regular price" baseline.** Colruyt's API returns the current selling price and a flag for whether it's currently a promo price, but never the pre-discount regular price. `depthPct` for Colruyt promo events is computed from the run-over-run price delta, not from a true "% off list price" figure. Lidl and Action do expose a real pre-discount price, so their `promoText` includes the actual discount percentage when available. - **Lidl's search doesn't filter by keyword** (see above) — the tracked shelf is whatever Lidl's own top listing returns, not specifically the query text. - **A new product appearing on the shelf is not itself an event.** If a product wasn't in the previous run's snapshot (e.g. it just entered stock, or a query started surfacing it), this run only adds it to the baseline — it won't emit an event until a *second* run sees a change from that baseline. - **First run per store never emits change events**, only a baseline-seeded status row — there's nothing to diff against yet. ### Cost estimate Priced per detected event, not per product scanned — a quiet run costs almost nothing. At $0.01/event plus a $0.01 run-start fee, a run that finds 10 promo changes across all 3 stores costs about $0.11. ### Related Scrapers - [Lidl Scraper](https://apify.com/studio-amba/lidl-scraper) — full product/price scraper this actor calls under the hood - [Action Scraper](https://apify.com/studio-amba/action-scraper) — full product/price scraper this actor calls under the hood - [Colruyt Scraper](https://apify.com/studio-amba/colruyt-scraper) — full product/price scraper this actor calls under the hood - [UK Grocery Price Matrix](https://apify.com/studio-amba/uk-grocery-price-matrix) — cross-retailer price comparison, same meta-scraper family - [EU Fresh Company Radar](https://apify.com/studio-amba/eu-fresh-company-radar) — same delta-feed design pattern, applied to company registrations instead of prices # Actor input Schema ## `stores` (type: `array`): Which Belgian stores to track. Leave empty for all 3: Lidl, Action, Colruyt. ## `maxResultsPerQuery` (type: `integer`): Maximum products to fetch per tracked search query per store. Each store tracks 4 fixed queries, so total tracked products per store is roughly 4x this value. ## `timeoutPerSourceSecs` (type: `integer`): Maximum time to wait for each underlying store scraper call. A slow or failing source is skipped after this rather than blocking the whole run. ## `proxyConfiguration` (type: `object`): Residential proxy passed through to the child scrapers, scoped to Belgium. ## `resetState` (type: `boolean`): Clears the persistent shelf state for every store before this run, so every store re-seeds its baseline instead of diffing. Use for QA/testing. Never enable this on a real scheduled run — it defeats the delta/diff purpose of the actor. ## Actor input object example ```json { "stores": [ "lidl", "action", "colruyt" ], "maxResultsPerQuery": 15, "timeoutPerSourceSecs": 120, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "BE" }, "resetState": false } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "stores": [ "lidl", "action", "colruyt" ], "maxResultsPerQuery": 15, "timeoutPerSourceSecs": 120, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "BE" }, "resetState": false }; // Run the Actor and wait for it to finish const run = await client.actor("studio-amba/promo-pulse").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "stores": [ "lidl", "action", "colruyt", ], "maxResultsPerQuery": 15, "timeoutPerSourceSecs": 120, "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "BE", }, "resetState": False, } # Run the Actor and wait for it to finish run = client.actor("studio-amba/promo-pulse").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "stores": [ "lidl", "action", "colruyt" ], "maxResultsPerQuery": 15, "timeoutPerSourceSecs": 120, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "BE" }, "resetState": false }' | apify call studio-amba/promo-pulse --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=studio-amba/promo-pulse", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Promo Pulse — Belgian Supermarket Promo Tracker", "description": "Scheduled meta-scraper that tracks a fixed shelf of products at Lidl, Action and Colruyt Belgium, diffs prices against the previous run, and emits only promo START/STOP and price-change events — not a full re-export.", "version": "0.1", "x-build-id": "J2haRs8i3BOhBcItn" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/studio-amba~promo-pulse/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-studio-amba-promo-pulse", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/studio-amba~promo-pulse/runs": { "post": { "operationId": "runs-sync-studio-amba-promo-pulse", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/studio-amba~promo-pulse/run-sync": { "post": { "operationId": "run-sync-studio-amba-promo-pulse", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "stores": { "title": "Stores", "type": "array", "description": "Which Belgian stores to track. Leave empty for all 3: Lidl, Action, Colruyt.", "items": { "type": "string", "enum": [ "lidl", "action", "colruyt" ], "enumTitles": [ "Lidl", "Action", "Colruyt" ] } }, "maxResultsPerQuery": { "title": "Max Results Per Query", "minimum": 5, "maximum": 50, "type": "integer", "description": "Maximum products to fetch per tracked search query per store. Each store tracks 4 fixed queries, so total tracked products per store is roughly 4x this value.", "default": 15 }, "timeoutPerSourceSecs": { "title": "Timeout Per Source (seconds)", "minimum": 30, "maximum": 600, "type": "integer", "description": "Maximum time to wait for each underlying store scraper call. A slow or failing source is skipped after this rather than blocking the whole run.", "default": 150 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Residential proxy passed through to the child scrapers, scoped to Belgium." }, "resetState": { "title": "Reset Shelf State (testing only)", "type": "boolean", "description": "Clears the persistent shelf state for every store before this run, so every store re-seeds its baseline instead of diffing. Use for QA/testing. Never enable this on a real scheduled run — it defeats the delta/diff purpose of the actor.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```