# Falabella Scraper - Products, Prices, Sellers & Reviews (`abotapi/falabella-marketplace-scraper`) Actor

Scrape Falabella, Latin America's leading retail marketplace: products with local prices, discounts, ratings and seller info across the Chile, Colombia and Peru storefronts. Search keywords or paste links, and monitor price changes with recurring updates.

- **URL**: https://apify.com/abotapi/falabella-marketplace-scraper.md
- **Developed by:** [Abot API](https://apify.com/abotapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 product results

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

## Falabella Marketplace Scraper

Scrape products, prices and sellers from Falabella (falabella.com), Latin America's leading retail marketplace. One actor covers three country storefronts: Chile (falabella.com), Colombia (falabella.com.co) and Peru (falabella.com.pe). Each market is its own catalogue with its own currency, and the actor pins the connection exit to the market you select.

### Why This Scraper?

- Three storefronts in one actor: Chile, Colombia and Peru, each with its local currency and catalogue.
- Full listing data on every row: price, was-price, discount, rating, review count, seller, installments and shipping flags.
- Optional detail reads add the description, specification table, category path, stock state, loyalty points and the seller's registered business details.
- Recurring updates mode labels every record NEW, UPDATED, REAPPEARED or EXPIRED, so a scheduled run returns only what changed.
- Resume support: continue an interrupted run from its run id without paying for the same rows twice.
- Paste your own links (products, categories, keyword collections, searches) or run keyword searches; forward pagination and de-duplication are automatic.
- A run that is refused everywhere fails loudly with a connection verdict; a genuinely empty search succeeds with zero rows and a visible note.

### Data You Get

| Field | Meaning |
| --- | --- |
| `id` | Marketplace product id |
| `skuId` | Variant (SKU) id |
| `name` | Listing title |
| `brand` | Brand |
| `url` | Product link |
| `imageUrl` | Main image |
| `currency` | Local currency of the market |
| `price` | Current price (number) |
| `priceDisplay` | Price exactly as the storefront shows it |
| `oldPrice` | Was-price when the product is discounted |
| `discountPercent` | Discount percentage from the storefront badge |
| `ratingAverage` | Customer rating |
| `ratingCount` | Number of reviews |
| `sellerId` | Marketplace seller id |
| `sellerName` | Marketplace seller name |
| `market` | Market country code (CL, CO, PE) |
| `marketHost` | Storefront the record came from |
| `description` | Short description (detail reads) |
| `specifications` | Specification table (detail reads) |
| `categories` | Category path (detail reads) |
| `outOfStock` | Stock state (detail reads) |
| `sellerDetails` | Seller business name, registration number, score (detail reads) |
| `changeType` | NEW, UPDATED, REAPPEARED or EXPIRED (recurring updates) |
| `changedFields` | Fields that changed since the last run (recurring updates) |
| `firstSeenAt` / `lastSeenAt` | First and most recent sighting (recurring updates) |

Every row also carries the flags the card itself shows: verified and official seller, sponsored and best-seller placement, installment offers, delivery flags, plus the long description, per-variant stock counts, loyalty points, warranty code and extra images on detail reads.

### How to Use

Pick **Keyword search** or **My own links**, choose the market, and run. The examples below are illustrative values, not from a live listing.

Minimal keyword search:

```json
{
  "mode": "search",
  "market": "cl",
  "queries": ["poleron"],
  "maxItems": 20
}
```

Ordered search with detail reads:

```json
{
  "mode": "search",
  "market": "co",
  "queries": ["zapatilla"],
  "sort": "price-asc",
  "fetchDetails": true,
  "maxItems": 50
}
```

Your own links, one market each:

```json
{
  "mode": "urls",
  "urls": ["https://www.falabella.com/falabella-cl/product/100000001/producto-de-muestra"],
  "maxItems": 10
}
```

Daily price monitoring:

```json
{
  "mode": "search",
  "market": "pe",
  "queries": ["polo"],
  "incrementalMode": true,
  "stateKey": "polo-daily",
  "maxItems": 200
}
```

### Input Parameters

| Parameter | What it does |
| --- | --- |
| `mode` | Keyword search on one storefront, or your own product and listing links. |
| `market` | Which country storefront: Chile, Colombia or Peru. Each is its own catalogue. |
| `queries` | Search terms, one entry per search; all searches share the record cap. |
| `sort` | Ordering per search: relevance (site default), lowest price or highest price. |
| `urls` | Product, category, keyword-collection or search links. Each is read on its own market. |
| `fetchDetails` | Read each product's page for description, specifications, stock and seller details (per-product surcharge). |
| `maxItems` | The single record cap for the whole run; 0 means no limit. |
| `maxPages` | Runaway guard per source; 0 means as deep as the storefront serves. |
| `resumeFromRunId` | Run id (or dataset id) of an interrupted run to continue. |
| `incrementalMode` | Return only what changed since the previous run of the same setup. |
| `stateKey` | Optional name for a monitoring campaign, keeping its memory stable. |
| `emitUnchanged` | Also return rows that did not change, labelled UNCHANGED (bills extra rows). |
| `emitExpired` | Also return rows that are gone, labelled EXPIRED (only after a complete scan). |
| `mcpConnectors` | Connector ids to export results into (optional delivery step). |
| `notionParentPageUrl` | Notion parent page for the Notion connector export. |
| `maxNotifyListings` | Cap on items written per connector; does not affect the dataset. |
| `proxyConfiguration` | Connection used for every request; defaults to the premium consumer tier pinned to the market. |

### Output Example

Illustrative values, not from a live listing:

```json
{
  "recordType": "product",
  "id": "100000001",
  "skuId": "100000002",
  "name": "Producto de muestra 1",
  "brand": "MARCAMUESTRA",
  "url": "https://www.falabella.com/falabella-cl/product/100000001/producto-de-muestra",
  "imageUrl": "https://media.falabella.com/falabellaCL/100000002_01/public",
  "currency": "CLP",
  "price": 22390.0,
  "priceDisplay": "$ 22.390",
  "oldPrice": 27990.0,
  "discountPercent": 20,
  "ratingAverage": 4.5,
  "ratingCount": 10,
  "sellerId": "S0000",
  "sellerName": "Vendedor de muestra",
  "market": "CL",
  "marketHost": "www.falabella.com",
  "description": "Descripcion del producto de muestra.",
  "specifications": [{"name": "Color", "value": "Rojo"}],
  "changeType": "NEW"
}
```

### Plan Requirement

The storefronts refuse ordinary datacenter connections, so the default connection is the premium consumer proxy tier pinned to the selected market's country. Running the actor needs a paid Apify plan that includes that tier, or your own proxy links pasted into the Connection section. If a serving window closes mid-run, the actor falls back to a result-unblocking tier so the run can finish.

#### Notes and limits

- Product ids and category ids are per-country: a Chilean product id does not exist on the Peruvian storefront.
- Max records is the only cap that stops a run; max pages is a runaway guard.
- Continue-a-previous-run and recurring updates are mutually exclusive: use one or the other.
- Keyword searches can be answered by a keyword collection or a category page; the actor follows the storefront's own redirect and walks that route.

### Send results into your apps (MCP connectors)

Optionally pipe results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector under Apify, Settings, API & Integrations, then fill in:

| Input field | What it does |
|---|---|
| `mcpConnectors` | The connectors to export into. Notion gets a rich page-per-item export; other connectors get a best-effort write or a digest. |
| `notionParentPageUrl` | URL or id of the Notion page under which item pages are created. Required for the Notion connector, ignored by others. |
| `maxNotifyListings` | Cap on items written to each connector per run. Does not affect the dataset. |

The export is a delivery step after the scrape. It never changes the dataset.

#### Support

Open an issue in the actor's support tab; include the run id and the input used.

# Actor input Schema

## `mode` (type: `string`):

Where to collect from: a keyword search on one storefront, or your own product and listing links.

## `market` (type: `string`):

Which country storefront to search. Each market is its own catalogue with its own currency and its own product ids.

## `queries` (type: `array`):

Only read when mode = keyword search. One entry per search; each search is walked forward, and all searches share the record cap.

## `sort` (type: `string`):

Order in which products are returned for each search.

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

Only read when mode = my own links. Paste product page links, or listing links (a search, a keyword collection, a category or a brand page). Each link is read on its own market; product links yield one full product each, listing links are walked forward.

## `fetchDetails` (type: `boolean`):

Open each product's own page and add the description, specification table, category path, stock state, seller legal details and extra images to the record. Off by default: a run without it is much cheaper and still carries prices, discounts, ratings and seller names.

## `maxItems` (type: `integer`):

Stop after this many records across the whole run (0 = no limit; the walk then ends when the catalogue runs out).

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

Runaway guard: an upper bound on how much is read for any single search or listing walk. Leave 0 to go as deep as the source serves, with the record cap above as the only real limit.

## `resumeFromRunId` (type: `string`):

Paste the run id (or dataset id) of an earlier run of this Actor to continue it. Records that run already returned are skipped, so an interrupted large collection can finish without paying for the same rows twice. Leave empty for a normal run.

## `incrementalMode` (type: `boolean`):

Turn this on for daily or weekly monitoring. The first run returns everything as NEW. Later runs return only NEW, UPDATED and REAPPEARED records, each labelled in a changeType column. Prices and rating counts move constantly on a marketplace, so a record whose only difference is a price still counts as UPDATED. Leave off for a normal one-off run.

## `stateKey` (type: `string`):

Optional. Name this monitoring campaign to keep its memory stable, or to deliberately share one memory across differently configured runs. Leave empty and the memory is keyed on the run setup automatically.

## `emitUnchanged` (type: `boolean`):

Off by default. Turn on to also return records that have not changed since the last run, labelled UNCHANGED. This returns, and bills, rows you already have.

## `emitExpired` (type: `boolean`):

Off by default. Turn on to also return records that were present before and are no longer found, labelled EXPIRED. Only produced when a run covered its whole setup, so a capped or continued run never reports records as gone. This returns, and bills, extra rows.

## `mcpConnectors` (type: `array`):

Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write or digest. Leave empty to skip; never changes the dataset output.

## `notionParentPageUrl` (type: `string`):

URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors.

## `maxNotifyListings` (type: `integer`):

Cap on items written to each connector per run. Does not affect the dataset.

## `proxyConfiguration` (type: `object`):

Connection used for every request. The storefronts refuse ordinary datacenter connections, so the default requests the premium consumer connection tier pinned to the selected market; it needs a paid plan that includes that tier. You can also paste your own connection links.

## Actor input object example

```json
{
  "mode": "search",
  "market": "cl",
  "queries": [
    "iphone"
  ],
  "sort": "relevance",
  "urls": [
    "https://www.falabella.com/falabella-cl/search?Ntt=iphone"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "maxNotifyListings": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `overview` (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 = {
    "mode": "search",
    "market": "cl",
    "queries": [
        "iphone"
    ],
    "sort": "relevance",
    "urls": [
        "https://www.falabella.com/falabella-cl/search?Ntt=iphone"
    ],
    "fetchDetails": false,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "maxNotifyListings": 50,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/falabella-marketplace-scraper").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 = {
    "mode": "search",
    "market": "cl",
    "queries": ["iphone"],
    "sort": "relevance",
    "urls": ["https://www.falabella.com/falabella-cl/search?Ntt=iphone"],
    "fetchDetails": False,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "maxNotifyListings": 50,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("abotapi/falabella-marketplace-scraper").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 '{
  "mode": "search",
  "market": "cl",
  "queries": [
    "iphone"
  ],
  "sort": "relevance",
  "urls": [
    "https://www.falabella.com/falabella-cl/search?Ntt=iphone"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "maxNotifyListings": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call abotapi/falabella-marketplace-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,abotapi/falabella-marketplace-scraper"
        }
    }
}
```

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/Z5lpvrsQGBbXlt3mv/builds/n2KghPgVhVwgPjmZi/openapi.json