# Competitor Price & Stock Intelligence (`northpeak_data/ecommerce-change-intelligence-1`) Actor

Track competitor price changes, stockouts and restocks. Detect commercial moves, score their impact, uncover opportunities and get actionable decision briefs. Turn ecommerce monitoring into smarter pricing decisions.

- **URL**: https://apify.com/northpeak_data/ecommerce-change-intelligence-1.md
- **Developed by:** [Northpeak Data](https://apify.com/northpeak_data) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 competitor intelligence results

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

## Competitor Price & Stock Intelligence

**See competitor price and stock changes, understand their commercial impact, and decide what to investigate next.**

Monitor public ecommerce product and category URLs over repeated runs. The first run creates a baseline; later runs compare changes, score impact and urgency, and surface commercial opportunities. When several monitored pages change together, the Actor can group them into a coordinated competitor move.

**Best for:** ecommerce operators, pricing analysts, category managers and competitive-intelligence teams.

**Which Northpeak monitor should you choose?** This Actor checks the exact product/category URLs you provide and tracks price and stock signals over time. The separate Ecommerce Change Intelligence Actor focuses on broader page-change monitoring. Choose based on your monitoring workflow; neither Actor guarantees extraction on websites that block automated access.

**Why it matters:** A generic page monitor says *something changed*. Competitor Price & Stock Intelligence highlights *which commercial move happened*, estimates its impact, and provides a short decision brief so your team can prioritize its response.

### What you get

- Price increases and drops, stockouts and restocks where the source page exposes usable signals
- Commercial impact score and urgency
- Competitor history and unusual-move signals
- Opportunity detection and concise decision briefs
- Aggregation of coordinated changes across multiple monitored pages

### How to start

1. Add the public product or category page URLs you want to track.
2. Set a consistent `monitorId` for the project.
3. Run once to capture the baseline.
4. Run again later with the same URLs and `monitorId` to detect changes.
5. For ongoing monitoring, schedule recurring Actor runs in Apify. A one-time run does not continuously watch a page.

**Data quality:** If a product cannot be identified reliably, the Actor reports `extraction_incomplete` rather than claiming an unchanged price or stock state. Incomplete checks suppress unverified prices, availability claims, and commercial alerts. A page-wide sale banner is not proof of a discount on the monitored product; when product-level discount evidence is unavailable, `discount` is `null` (unknown), not `true`.

**Important limitations:** You supply the URLs; this Actor does not automatically discover competitor pages. First-run baselines are not historical changes. Results depend on publicly accessible page data, and commercial interpretation is an estimate rather than a confirmed competitor intention.

***

### Verified behavior

A two-run isolated validation in Apify successfully created a baseline and then detected a simulated 15% price cut, producing a `price_cut` commercial event and a decision brief. This validates the change-classification path, **not** the reliability of live extraction on every retailer. Live monitoring still depends on each site's publicly available data and access restrictions.

### Technical details

Commerce Radar monitors competitor ecommerce pages and turns raw page changes into commercial decision signals.

Instead of only reporting that a price or stock value changed, the Actor classifies the move, scores impact and urgency, compares the move with the competitor's recorded behavior, and surfaces possible opportunities.

### Core outputs

- `commercialEvent` — classified move such as `price_cut`, `price_increase`, `stockout`, or `restock`
- `impactScore` — 0–100 commercial significance score
- `urgency` — low, medium, or high
- `strategyFingerprint` — historical comparison and unusual-move detection
- `opportunity` — actionable signal such as competitor stock gap or pricing headroom
- `decisionBrief` — concise explanation of what happened and why it may matter

### How it works

1. Run the Actor with competitor product/category URLs. The first run stores a baseline.
2. Run it again later with the same `monitorId` and URLs.
3. Changed pages are compared with the saved baseline.
4. Commerce Radar infers the commercial move and updates the competitor history.

### Example input

```json
{
  "urls": [
    "https://example.com/product/example-product"
  ],
  "monitorId": "competitor-a",
  "compareMode": "commerce",
  "outputMode": "all",
  "changeThreshold": 1,
  "maxPages": 10
}
```

### Example intelligence result

```json
{
  "status": "changed",
  "commercialEvent": {
    "eventType": "price_cut",
    "impactScore": 70,
    "urgency": "medium",
    "priceDeltaPercent": -20
  },
  "strategyFingerprint": {
    "unusualMove": true,
    "confidence": 70
  },
  "decisionBrief": "price cut detected (impact 70/100, urgency medium). This is unusual versus this competitor's recorded behavior."
}
```

### Architecture

The Actor is HTTP-first and does not require a browser for ordinary HTML pages. Snapshots and strategy history are stored separately from the Ecommerce Change Intelligence Actor, so both products can operate independently.

### Current scope

The MVP focuses on public ecommerce pages with extractable structured commerce data (JSON-LD) or visible price/availability signals. Shopify and other storefronts exposing standard product metadata are natural first targets.

# Actor input Schema

## `urls` (type: `array`):

Public ecommerce product or category URLs. Start with one real product page that exposes price or availability; the first run creates a baseline, not a price-change alert.

## `monitorId` (type: `string`):

Use the same Monitor ID and URLs on future runs to compare against your baseline. Changing the ID starts a new monitoring history.

## `compareMode` (type: `string`):

Focus on commercial signals, content changes, or both.

## `outputMode` (type: `string`):

Return all checks or only changed pages, baselines, and errors. Output records may be billable according to Store pricing.

## `changeThreshold` (type: `integer`):

Minimum weighted score before a change is flagged.

## `maxPages` (type: `integer`):

Safety limit for pages processed per run.

## `aggregateMoves` (type: `boolean`):

Group multiple changed pages from the same competitor into one commercial-move intelligence record.

## `validation` (type: `object`):

Optional controlled values used only to validate the intelligence pipeline end-to-end. Leave disabled for normal monitoring.

## Actor input object example

```json
{
  "urls": [],
  "monitorId": "default",
  "compareMode": "commerce",
  "outputMode": "all",
  "changeThreshold": 1,
  "maxPages": 10,
  "aggregateMoves": true
}
```

# Actor output Schema

## `dataset` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("northpeak_data/ecommerce-change-intelligence-1").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("northpeak_data/ecommerce-change-intelligence-1").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 '{}' |
apify call northpeak_data/ecommerce-change-intelligence-1 --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,northpeak_data/ecommerce-change-intelligence-1"
        }
    }
}
```

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/cPWJRz8JMdRd3IJdu/builds/AHIVxZsMNaozjYGTl/openapi.json