# AliExpress Scraper: Products, Reviews & Stores (`studio_sussex/aliexpress-product-scraper`) Actor

Scrape AliExpress products, prices, variants, stock, reviews, sellers, shipping, supplier stores, and monitor product changes with localized data.

- **URL**: https://apify.com/studio\_sussex/aliexpress-product-scraper.md
- **Developed by:** [Kenneth Lingo](https://apify.com/studio_sussex) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 products

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

### AliExpress product scraper

Turn AliExpress search results, product pages, reviews, and supplier stores into structured data. **AliExpress Scraper: Products, Reviews & Stores** supports keyword product research, exact product details, variants and SKU stock, seller and shipping data, buyer reviews, store catalogs, and recurring price or inventory monitoring.

Run it in the [Apify Store](https://apify.com/studio_sussex/aliexpress-product-scraper), call it as an AliExpress products API, or connect it to an AI agent through Apify MCP. On Apify cloud, proxy routing is managed for you—**no customer-provided proxy or proxy setup is required**.

### Platform architecture

This repository maintains one scraping engine and two thin distribution layers:

```text
API marketplaces / direct clients / MCP
                 |
        Cloudflare Worker gateway
                 |
          Apify Actor REST API
                 |
     AliExpress research workflows
```

- `src/` and `.actor/`: production Actor, schemas, datasets, monitoring state, and run reports.
- `gateway/`: TypeScript/Hono Worker with versioned REST endpoints, authentication, cost/rate/input limits, normalized envelopes/errors/usage, OpenAPI, Scalar docs, marketplace adapters, and Apify-run jobs.
- `mcp/`: stdio MCP server that calls the gateway; it contains no scraper code.
- `marketplaces/product.json`: shared listing source of truth.
- `artifacts/`: generated marketplace and Postman files.
- `docs/marketplaces/`: provider-specific human launch instructions.

Search is the only synchronous data workflow. Product detail, reviews, store catalogs, monitoring, and larger research requests return Apify run IDs as background jobs because those paths can be browser-heavy or unpredictable.

#### Developer setup

```bash
npm ci
npm test
npm --prefix gateway ci
npm run gateway:test
npm run gateway:check
npm --prefix mcp ci
npm run mcp:test
npm run marketplace:all
```

Copy `.env.example` to an ignored local environment file and replace placeholders. Never commit Apify, Cloudflare, marketplace, API, facilitator, or wallet credentials. For Worker development, use an ignored `gateway/.dev.vars`; set deployed secrets with interactive `wrangler secret put` commands. Required production secrets are `APIFY_TOKEN` and `DIRECT_API_KEYS`; marketplace secrets are added only when that channel is enabled.

Run the gateway locally with `npm --prefix gateway run dev`. The OpenAPI source is `gateway/openapi.json`, docs are served at `/docs`, and the specification at `/openapi.json`. Deployment uses `gateway/wrangler.jsonc` with separate staging and production environments. Use `npm --prefix gateway run deploy:staging` first and production only after smoke tests.

Marketplace adapters authenticate trusted proxies and translate the neutral usage object; they never duplicate scraping logic. Regenerate all artifacts with `npm run marketplace:all` or one channel with `npm run marketplace:rapidapi`, `marketplace:api-market`, `marketplace:zyla`, `marketplace:apilayer`, `marketplace:x402`, `marketplace:smithery`, `marketplace:glama`, or `marketplace:postman`.

See `docs/MARKETPLACE_READINESS.md`, `docs/TOMORROW_LAUNCH_CHECKLIST.md`, `docs/API_UNIT_ECONOMICS.md`, and `docs/MARKETPLACE_PRICING_RESEARCH.md` before launch.

| Need | Supported |
| --- | --- |
| Product search | Yes |
| Full product details | Yes |
| Variants & SKU stock | Yes |
| Reviews | Yes |
| Supplier/store discovery | Yes |
| Price & stock monitoring | Yes |
| Localization | Yes |
| Resume previous datasets | Yes |
| Customer-provided proxy required | No |

Use one Actor instead of assembling separate AliExpress product scraper, reviews scraper, store scraper, variants scraper, and price monitor workflows. Results are available as JSON, CSV, Excel, XML, RSS, and through the Apify API.

### Quick start — Run the scraper and download results

No coding required! Run directly on Apify using your available credits.

1. Open the Input tab.
2. Select a ready-made example or choose your scraping mode.
3. Enter your search keywords, product URLs, or store URL.
4. Set a small result limit (10–20 recommended for testing).
5. Click Start and wait for the run to finish.
6. Open the Output tab to view your scraped data.
7. Export your results as JSON, CSV, or Excel.

#### Where do my results go?

Your results are stored directly in Apify. You do not need to visit another website.

Open your completed run and navigate to its dataset to download the complete results.

#### What can I try?

All five workflows are available:

- Product search and discovery
- Full product details, variants, and SKU inventory
- Buyer reviews and photos
- Supplier and store catalogs
- Price and inventory monitoring

For monitoring, run the same configuration again later to detect changes.

#### Using the API?

Start the Actor, wait for completion, and retrieve its output dataset using the Apify API.

You can also create scheduled tasks for recurring monitoring.

### What data can you scrape?

| Data or workflow | Available output |
| --- | --- |
| Search products | Product ID and URL, title, images, price, original price, discount, rating, sold counts, category, badges, Choice/sponsored flags, and search provenance |
| Prices | Current price, ranges, original price, currency, and discount where AliExpress exposes them |
| Variants | Product option groups and values |
| SKU-level price | Per-SKU sale/original price, currency, and purchase limits where exposed |
| Inventory | Product stock plus available inventory and saleability for individual SKUs where exposed |
| Seller/store | Store and seller IDs, names, company/profile fields, followers, positive rate, and establishment date when available |
| Shipping | Ship-from country, destination, methods, costs, and estimated delivery fields when exposed |
| Specifications | Product attributes, brand, category path, promotions, wishlist count, video, and availability |
| Description | Optional bounded product description HTML and plain text |
| Gallery | Main image, additional search images, and full detail gallery |
| Reviews | Rating, text and translation, country, date, SKU, images/video, helpful votes, seller reply, and follow-up feedback |
| Monitoring | `NEW`, `UPDATED`, and optionally `UNCHANGED` product state with before/after changes |
| Supplier/store catalog | Products accessible from an AliExpress store plus supplier metadata and catalog position |
| Localization | Requested ship-to country, currency, and locale; every row reports what AliExpress actually served |

### AliExpress product search

Use `mode: "search"` with one or more `searchQueries`, or provide AliExpress keyword/category URLs in `startUrls`. Sort by relevance, orders, ascending price, or descending price. Filter by price, rating, sold count, discount, Choice, sponsored status, free-shipping cards, and ship-from country.

This workflow is useful for AliExpress product research, competitor assortment analysis, and dropshipping product research. `maxResults` is a hard product-output cap, so run size and spend remain predictable.

```json
{
  "mode": "search",
  "searchQueries": ["wireless earbuds"],
  "sortBy": "orders",
  "maxResults": 20
}
```

### AliExpress product details, variants & stock

Use `mode: "details"` and provide product URLs, numeric product IDs, regional URLs, or official `a.aliexpress.com` and `s.click.aliexpress.com` share links in `productUrls`. Direct product inputs automatically request full details.

A successful rich product record can include variant axes, AliExpress SKU IDs, SKU-level prices, available inventory, total stock, seller details, specifications, gallery images, shipping options, ETA, category path, promotions, video, and an optional description. This makes the Actor usable as an AliExpress variants scraper, SKU scraper, inventory scraper, stock scraper, and price scraper.

```json
{
  "mode": "details",
  "productUrls": ["https://www.aliexpress.com/item/3256811621288203.html"],
  "includeDescription": true
}
```

Rich detail is best-effort. AliExpress applies product-specific challenges, so full detail coverage is not guaranteed. Failed direct detail lookups are emitted as explicit diagnostic rows and are not billed as successful `product-detail` results; successful search or store data remains available when enrichment fails.

### AliExpress reviews scraper

Use `mode: "reviews"` for an AliExpress review API workflow. Review records are separate dataset rows with `recordType: "review"` and can contain the original and translated review, stars, reviewer country, review date, variant/SKU, buyer photos or video, helpful votes, seller replies, and follow-up feedback.

Filter by minimum/maximum rating, reviewer country, keyword, date, or media presence. Set `onlyNewReviews: true` to persist accepted review identities and emit only reviews not seen in earlier runs within the fetched review window. Use `hideReviewerName: true` when buyer display names are unnecessary.

```json
{
  "mode": "reviews",
  "productUrls": ["3256807852898873"],
  "maxReviewRating": 2,
  "reviewsWithMediaOnly": true,
  "maxReviewsPerProduct": 50,
  "maxTotalReviews": 50
}
```

### AliExpress store and supplier scraper

Use `mode: "store"` with an AliExpress store URL or numeric store ID. The Actor collects unique accessible catalog products, their store position, and available supplier metadata. It can optionally enrich those products with details, reviews, or monitoring data.

```json
{
  "mode": "store",
  "storeUrls": ["https://www.aliexpress.com/store/1101705614"],
  "storeSort": "orders",
  "maxResults": 100
}
```

Store paging is bounded by `maxResults` and `maxStoreScrolls`. Dynamic stores do not always expose their complete catalog, so the Actor reports what it captured rather than claiming catalog completeness. This workflow covers common AliExpress store scraper, supplier scraper, and seller scraper use cases.

### AliExpress price & stock monitoring

Use `mode: "monitor"` for an AliExpress price monitor or stock monitor. The Actor stores a compact snapshot in your Apify account and compares the next run with it. It tracks prices, currency, sold count, ratings, review count, total stock, SKU prices and inventory, shipping, and seller metadata where available.

- `NEW` — no previous snapshot existed.
- `UPDATED` — one or more tracked values changed.
- `UNCHANGED` — stable; suppressed by default unless `emitUnchanged: true`.

```json
{
  "mode": "monitor",
  "productUrls": ["3256811621288203", "1005012536331708"],
  "emitUnchanged": false
}
```

For the most value, save this input as an Apify Task and attach a Schedule. Monitoring state and datasets remain in the running customer's Apify account.

### AliExpress scraper API

Public Actor identity: `studio_sussex/aliexpress-product-scraper`

Stable Actor ID: `i6VUtUn1ch1gwjEzX`

Use the Actor through the official Python or JavaScript client, raw REST API, Apify CLI, webhooks, schedules, or automation platforms. API examples for Python, JavaScript, cURL, and AI/MCP clients are available in the public [AliExpress Product Scraper API Examples](https://github.com/kinglingo3281/aliexpress-product-scraper-examples) repository.

Store your Apify token in the `APIFY_TOKEN` environment variable. Never hard-code it or commit it.

### Use the AliExpress scraper with Python

Install the current official client:

```bash
pip install apify-client
export APIFY_TOKEN="your_apify_token"
```

```python
import os

from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("studio_sussex/aliexpress-product-scraper").call(
    run_input={
        "mode": "search",
        "searchQueries": ["wireless earbuds"],
        "sortBy": "orders",
        "maxResults": 20,
    }
)

for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)
```

### Use the AliExpress scraper with JavaScript / Node.js

Install the current official client:

```bash
npm install apify-client
export APIFY_TOKEN="your_apify_token"
```

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('studio_sussex/aliexpress-product-scraper').call({
  mode: 'search',
  searchQueries: ['wireless earbuds'],
  sortBy: 'orders',
  maxResults: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with cURL

Start a run without putting the token in the URL:

```bash
export APIFY_TOKEN="your_apify_token"

curl -sS -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"search","searchQueries":["wireless earbuds"],"sortBy":"orders","maxResults":20}' \
  "https://api.apify.com/v2/acts/studio_sussex~aliexpress-product-scraper/runs"
```

The response contains the run ID and `defaultDatasetId`. Wait for the run, then retrieve items:

```bash
curl -sS -H "Authorization: Bearer $APIFY_TOKEN" \
  "https://api.apify.com/v2/actor-runs/RUN_ID?waitForFinish=120"

curl -sS -H "Authorization: Bearer $APIFY_TOKEN" \
  "https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true&format=json"
```

### Use with n8n, Make, Zapier and other automation platforms

Any platform that can send authenticated HTTP requests can start the Actor through the Apify REST API and read its dataset. Use an HTTP request step with the same run endpoint and JSON input shown above, wait for completion, then fetch `defaultDatasetId` items. Apify schedules and webhooks can trigger recurring monitoring or notify a downstream workflow when a run finishes.

This describes standard REST integration; it does not imply a dedicated native connector for every platform.

### Use with AI agents and MCP

Copy this capability instruction into an AI agent:

```text
Use `studio_sussex/aliexpress-product-scraper` (Actor ID `i6VUtUn1ch1gwjEzX`) when you need AliExpress product search, exact product details, variants/SKU stock, reviews, seller/store research, or price/stock monitoring. Inspect its input schema before running it, keep `maxResults`, `maxReviewsPerProduct`, and `maxTotalReviews` bounded, and read results from the run's default dataset.
```

Natural-language requests an agent can fulfill include:

- “Find 100 best-selling wireless chargers on AliExpress.”
- “Get full variants, stock, seller, and shipping information for this AliExpress URL.”
- “Collect the newest 50 low-star reviews for this product.”
- “Find all accessible products from this supplier store.”
- “Monitor these 20 AliExpress products for price and stock changes.”

Input guidance for agents:

| Intent | Input |
| --- | --- |
| Search | `mode: "search"`, `searchQueries`, `sortBy`, `maxResults` |
| Product details | `mode: "details"`, `productUrls`; optionally `includeDescription` |
| Reviews | `mode: "reviews"`, `productUrls`, review filters, `maxReviewsPerProduct`, `maxTotalReviews` |
| Store research | `mode: "store"`, `storeUrls`, `storeSort`, `maxResults` |
| Monitoring | `mode: "monitor"`, `productUrls`, normally `emitUnchanged: false` |
| Localization | Add `targetCountry`, `targetCurrency`, and `locale` to any relevant workflow |

#### Apify MCP

The current official method is the hosted Apify MCP server at `https://mcp.apify.com` over Streamable HTTP. Add that URL to an MCP-capable client and authorize with Apify OAuth; do not place an API token in public configuration. An agent can then:

1. Call `search-actors` with AliExpress-related keywords.
2. Call `fetch-actor-details` for `studio_sussex/aliexpress-product-scraper` and inspect pricing plus the input schema.
3. Call `call-actor` with the Actor identity and valid bounded input.
4. If needed, poll `get-actor-run` until terminal status.
5. Call `get-dataset-items` using the returned dataset ID.

Example request:

```text
Using Apify MCP, inspect `studio_sussex/aliexpress-product-scraper`, estimate the paid run from its current pricing, then ask for approval before running it. After approval, find 20 wireless earbuds sorted by orders and return the dataset items.
```

For a minimal client that loads this Actor directly, Apify supports tool selection in the MCP URL:

```text
https://mcp.apify.com?tools=studio_sussex/aliexpress-product-scraper
```

Running Actors requires authentication. Actor discovery and schema inspection can be performed with Apify's anonymous discovery tools, but execution and dataset access require an authorized Apify account.

### Key inputs

| Input | Purpose |
| --- | --- |
| `mode` | Auto, search, details, reviews, monitor, or store workflow |
| `searchQueries` | Keyword searches |
| `startUrls` | AliExpress keyword-search or category-result URLs |
| `productUrls` | Exact product URLs/IDs or official AliExpress short/share links |
| `storeUrls` | Store URLs or numeric store IDs |
| `maxResults` | Hard cap on emitted product rows |
| `sortBy` | Relevance, orders, price ascending, or price descending |
| `minPrice`, `maxPrice`, `minRating`, `minSold` | Product filters |
| `minDiscountPercent`, `choiceOnly`, `freeShippingOnly` | Additional discovery filters |
| `includeSponsored` | Include or exclude sponsored listings |
| `targetCountry`, `targetCurrency`, `locale` | Requested market and localization |
| `includeDetails`, `includeDescription` | Rich product and description enrichment |
| `includeReviews` | Combine reviews with another workflow |
| `minReviewRating`, `maxReviewRating`, `reviewCountry` | Review filters |
| `reviewsWithMediaOnly`, `reviewKeyword`, `reviewsSinceDate` | Focus review collection |
| `onlyNewReviews` | Emit only previously unseen reviews within the fetched window |
| `monitorChanges`, `emitUnchanged` | Change monitoring behavior |
| `resumeDataset` | Skip products already completed in a previous dataset |
| `maxReviewsPerProduct`, `maxTotalReviews` | Review output and spending guards |
| `detailConcurrency`, `maxStoreScrolls` | Bounded detail/store work |

The [Input tab](https://apify.com/studio_sussex/aliexpress-product-scraper/input-schema) is the source of truth for all fields, defaults, limits, and descriptions.

### Output datasets and views

The default dataset can contain product and review records. Purpose-built views make exports easier:

| View/output | Purpose |
| --- | --- |
| `overview` | Discovered and enriched products |
| `pricing` | Prices, discounts, ratings, sales, and URLs |
| `export` | Compact flat product export |
| `details` | Full product details, seller, shipping, specifications, gallery, and description |
| `reviews` | Buyer review records |
| `changes` | Monitoring lifecycle and before/after state |
| `stores` | Supplier/store products and store metadata |
| `variants` | One row per product SKU/variant |
| Run report | HTML dashboard with counts, detail success, billing events, and diagnostics |
| Market summary | Price/sales/rating distributions, coverage, top stores/categories, and top products |

Missing upstream data remains null or absent rather than being invented. Without extra scrape requests, product runs also generate a market summary. Products with collected reviews can include derived positive/negative/media rates, top countries and variants, low-rating problem variants, and best-effort complaint themes.

### Resume and incremental collection

- Select `resumeDataset` to continue product collection without re-emitting products already completed there.
- Use `onlyNewReviews: true` to emit and bill only unseen accepted review identities in the fetched review window.
- Product monitoring persists compact snapshots and normally suppresses unchanged products.
- Monitoring and incremental state are stored in named key-value stores in the customer's Apify account.

### Pricing

This Actor uses pay per event. Always check the live Store pricing panel before a run because Store prices can change.

| Event | Current listed price |
| --- | ---: |
| Actor start | $0.005 per start event (memory-adjusted by Apify) |
| Search/store product | $0.00199 per successful product |
| Full product detail | $0.008 per successful rich detail |
| Buyer review | $0.001 per emitted review |
| Product change | $0.005 per first-seen or changed monitoring result |

Product result events are mutually exclusive: an ordinary search/store row uses `product`, a successful rich detail uses `product-detail`, and a first-seen or changed monitor row uses `product-change`. Reviews are billed independently. Filtered rows, duplicates, failed requests, failed direct details, suppressed unchanged rows, and rows beyond a charge limit are not successful custom result events.

Use `maxResults`, `maxReviewsPerProduct`, `maxTotalReviews`, and Apify's run charge limit to control spend.

### Reliability and limitations

- Search uses lightweight HTTP; detail and store workflows use Chromium only when required.
- Product-detail contexts are isolated and concurrency is bounded.
- On Apify cloud, proxy routing is managed automatically; customers do not provide proxy credentials.
- Blocks are reported as blocks, not disguised as zero-result success.
- The Actor does not solve CAPTCHAs.
- Rich detail is product and route dependent; it is not guaranteed for every product.
- Store catalogs are dynamic and bounded, so captured results may not represent every store item.
- AliExpress can override requested localization. Trust each row's returned currency and market fields.
- Review depth depends on what AliExpress exposes in the fetched window.
- Retries, pages, request counts, and browser operations are bounded.

In private/cloud acceptance tests, 1K, 5K, and 10K unique-product US search runs completed with zero retries, blocks, or errors for the measured input shape. The measured 10K run completed in about nine minutes. These are test results, not a promise that every 10K run will have the same speed or outcome.

### FAQ

#### Is this an AliExpress API alternative?

Yes for data-collection workflows: it provides structured product search, details, variants, reviews, seller/store data, and monitoring through Apify clients and REST APIs. It is an independent scraper, not an official AliExpress API and not affiliated with or endorsed by AliExpress.

#### Do I need my own proxy?

No. Proxy routing is managed on Apify cloud. Do not put proxy URLs or credentials in ordinary Actor input.

#### Can it scrape AliExpress variants and SKU inventory?

Yes, when full detail succeeds and AliExpress exposes the fields. The `variants` dataset view produces one row per SKU with price and available inventory where available.

#### Can it scrape AliExpress buyer photos and low-star reviews?

Yes. Use `reviewsWithMediaOnly: true`, set `maxReviewRating`, and bound `maxReviewsPerProduct` and `maxTotalReviews`.

#### Can it scrape every product from an AliExpress supplier store?

It collects accessible products with bounded paging. AliExpress stores are dynamic and may not expose a complete catalog, so completeness is not guaranteed.

#### Can I use it as an AliExpress price tracker?

Yes. Save monitor input as an Apify Task, schedule repeated runs, and consume `NEW`/`UPDATED` records from the `changes` view. Set `emitUnchanged: true` only if stable rows are also needed.

#### Can I use this AliExpress scraper from Python or JavaScript?

Yes. Use the official `apify-client` package for Python or JavaScript, or call the REST API from any language. Copyable examples are linked above.

#### Does it work with AI agents and MCP?

Yes. Apify's hosted MCP server can discover, inspect, run, and retrieve results from the Actor after authorization. The Actor's schemas provide structured input and output guidance for agents.

#### Where is data stored?

Results and state are written to storage in the running customer's Apify account. Dataset and key-value retention follow that customer's Apify plan and storage settings. No output is copied to an external service by this Actor.

### Data handling

The Actor processes public AliExpress marketplace pages. Buyer display names can be omitted with `hideReviewerName`. Use collected data in accordance with applicable law, AliExpress terms, and your own privacy obligations.

This independent community Actor is maintained by [Studio Sussex](https://studiosussex.com) and is not affiliated with or endorsed by AliExpress.

### Support

For reproducible issues, open the Actor's **Issues** tab with the run ID, workflow, sanitized input, and first relevant error message. Never include API tokens, proxy credentials, cookies, or private customer data.

# Changelog

This Actor's version history is a separate document: https://apify.com/studio\_sussex/aliexpress-product-scraper/changelog.md

# Actor input Schema

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

<strong>Recommended: Auto-detect.</strong> Keywords run search, exact product links default to full details, and store links run supplier discovery. Choose a specific workflow when you want reviews or monitoring.

## `searchQueries` (type: `array`):

Keywords to search on AliExpress. Leave empty when using URLs, product IDs, or store IDs.

## `startUrls` (type: `array`):

AliExpress keyword-search or category result URLs. Product detail URLs belong in Product URLs/IDs; store URLs belong in Store URLs/IDs.

## `productUrls` (type: `array`):

Exact AliExpress product URLs, numeric IDs, regional URLs, or official AliExpress short/share links. Up to 1,000 direct products per run; short links are resolved automatically.

## `storeUrls` (type: `array`):

AliExpress store URLs or numeric store IDs. Store mode renders the all-items page, calls its signed catalog API with bounded paging, and collects unique products plus supplier metadata.

## `maxResults` (type: `integer`):

<strong>Hard product-output cap.</strong> Keeps run size and spend predictable. Reviews have separate caps below.

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

Only sort modes verified against live AliExpress listings are offered. 'relevance' is the site default.

## `minPrice` (type: `number`):

Minimum product price in the currency AliExpress actually serves for the selected market.

## `maxPrice` (type: `number`):

Maximum product price in the currency AliExpress actually serves for the selected market.

## `minRating` (type: `number`):

Keep products rated at least this high (0-5). Products without a rating are dropped when set.

## `minSold` (type: `integer`):

Keep products with at least this many reported orders. Uses the exact order count when AliExpress exposes it.

## `minDiscountPercent` (type: `number`):

Keep only products with at least this displayed/derived discount percentage.

## `choiceOnly` (type: `boolean`):

Keep only products AliExpress marks as Choice.

## `freeShippingOnly` (type: `boolean`):

Keep only products whose search card explicitly carries the Free Shipping badge.

## `shipFromCountry` (type: `string`):

Two-letter country code reported per product, e.g. US or CN.

## `includeSponsored` (type: `boolean`):

AliExpress marks ads in the search results (isSponsored = true). Turn off for organic listings only.

## `deduplicateAcrossQueries` (type: `boolean`):

By default each query keeps its own rows (a product matching two queries is emitted twice with different searchQuery values). Turn on to emit each product once per run.

## `rotateSorts` (type: `boolean`):

AliExpress repeats listings across pages. When a sort stops producing new products, continue with the other verified sort modes to reach maxResults. Each row records the sort it came from.

## `targetCountry` (type: `string`):

Two-letter ship-to/proxy country such as US, GB, DE, FR, AU. The Actor automatically uses a residential IP in this country on Apify cloud.

## `targetCurrency` (type: `string`):

Requested three-letter display currency such as USD, EUR, GBP, AUD. Returned rows always report the currency AliExpress actually served.

## `locale` (type: `string`):

Requested AliExpress locale such as en\_US, de\_DE, fr\_FR, es\_ES.

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

Open each product through a real browser and collect variants, SKU pricing, stock, seller, specifications, shipping and full gallery data. Automatically enabled for direct product URLs/IDs.

## `includeDescription` (type: `boolean`):

Fetch description HTML/text after successful full-detail capture.

## `includeReviews` (type: `boolean`):

Collect separate buyer-review rows and attach review statistics + derived review intelligence to the product.

## `detailConcurrency` (type: `integer`):

Maximum simultaneous browser product-detail contexts. Default 2 is reliability-first; raise only after your cloud workload is stable.

## `minReviewRating` (type: `number`):

Optional review filter: keep reviews rated at least this many stars.

## `maxReviewRating` (type: `number`):

Optional review filter: useful for finding negative/low-star reviews.

## `reviewsWithMediaOnly` (type: `boolean`):

Return only reviews containing at least one image or video.

## `reviewCountry` (type: `string`):

Optional two-letter reviewer-country filter, e.g. US, DE, GB.

## `reviewKeyword` (type: `string`):

Optional case-insensitive keyword filter across original, translated, and follow-up review text.

## `reviewsSinceDate` (type: `string`):

Optional YYYY-MM-DD cutoff. Reviews with missing/unparseable dates are excluded when this is set.

## `hideReviewerName` (type: `boolean`):

Remove reviewerName from emitted review rows while keeping country and non-identifying research fields.

## `onlyNewReviews` (type: `boolean`):

Persist review identities per product/market/locale and emit/bill only reviews not seen in earlier runs. Applies within the review window actually fetched; it does not claim complete review-history coverage.

## `maxReviewsPerProduct` (type: `integer`):

Maximum matching review rows per product (up to 5,000). Availability at deep pages depends on what AliExpress exposes.

## `maxTotalReviews` (type: `integer`):

Whole-run review-row cap. This is the main review spending guard.

## `maxReviewScanPages` (type: `integer`):

Safety cap for pages scanned while finding matching reviews. Raise only when using restrictive review filters.

## `monitorChanges` (type: `boolean`):

Persist product state in your own Apify account and emit only first-seen or changed products by default. Useful for scheduled price, sales, rating and stock monitoring.

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

When monitoring, also return unchanged products. Leave off for change-only output and lower billing.

## `resumeDataset` (type: `string`):

Select a previous Apify dataset to continue without re-emitting products already completed there. Search/store skips prior products; details skips products with completed full detail. API callers can also pass the dataset ID/name directly.

## `storeSort` (type: `string`):

Requested ordering for products on the AliExpress store all-items page.

## `maxStoreScrolls` (type: `integer`):

Safety cap for signed store-catalog page rounds and rendered-page fallback scrolling. Stops early when no new product IDs are exposed.

## `maxPagesPerQuery` (type: `integer`):

Safety ceiling on listing pages fetched per query (and per sort mode).

## `maxRequests` (type: `integer`):

Hard request budget for the whole run, retries included.

## `minDelayMs` (type: `integer`):

Global pacing floor between page fetches. Cloud runs rotate residential IPs automatically; increase this only if AliExpress still reports blocks.

## `requestTimeoutMs` (type: `integer`):

Timeout for a single HTTP request.

## `maxRetries` (type: `integer`):

Retry ceiling for retryable transport/server errors.

## `keepRawCard` (type: `boolean`):

Attach the unmodified AliExpress card JSON to each row under rawCard. Makes rows much larger; use for debugging only.

## Actor input object example

```json
{
  "mode": "auto",
  "searchQueries": [
    "wireless earbuds"
  ],
  "productUrls": [],
  "storeUrls": [],
  "maxResults": 20,
  "sortBy": "relevance",
  "choiceOnly": false,
  "freeShippingOnly": false,
  "includeSponsored": true,
  "deduplicateAcrossQueries": false,
  "rotateSorts": true,
  "targetCountry": "DE",
  "targetCurrency": "EUR",
  "locale": "de_DE",
  "includeDetails": false,
  "includeDescription": false,
  "includeReviews": false,
  "detailConcurrency": 2,
  "reviewsWithMediaOnly": false,
  "reviewsSinceDate": "2026-09-01",
  "hideReviewerName": false,
  "onlyNewReviews": false,
  "maxReviewsPerProduct": 20,
  "maxTotalReviews": 1000,
  "maxReviewScanPages": 20,
  "monitorChanges": false,
  "emitUnchanged": false,
  "storeSort": "default",
  "maxStoreScrolls": 20,
  "maxPagesPerQuery": 20,
  "maxRequests": 100,
  "minDelayMs": 750,
  "requestTimeoutMs": 30000,
  "maxRetries": 3,
  "keepRawCard": false
}
```

# Actor output Schema

## `report` (type: `string`):

Responsive visual summary of this run, including product/review counts, detail success, resume savings, billing events and diagnostics.

## `products` (type: `string`):

Product discovery and enriched product rows.

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

Focused full-detail product view.

## `reviews` (type: `string`):

Review rows with text, media, variant and reviewer metadata.

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

Monitoring lifecycle and before/after product state.

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

Products discovered from supplier/store workflows.

## `datasetUrl` (type: `string`):

Full dataset for JSON/CSV/XLSX/API access.

## `variants` (type: `string`):

One row per product SKU/variant, ready for CSV/Excel/API use.

## `marketSummary` (type: `string`):

Derived price/sales/rating distributions, field coverage, top stores/categories, and top products from accepted product rows. No extra scrape requests.

# 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 = {
    "searchQueries": [
        "wireless earbuds"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("studio_sussex/aliexpress-product-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 = { "searchQueries": ["wireless earbuds"] }

# Run the Actor and wait for it to finish
run = client.actor("studio_sussex/aliexpress-product-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 '{
  "searchQueries": [
    "wireless earbuds"
  ]
}' |
apify call studio_sussex/aliexpress-product-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,studio_sussex/aliexpress-product-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/i6VUtUn1ch1gwjEzX/builds/qPci2R87Y0MnIp4Um/openapi.json