# Changelog of Taobao Tmall Product Scraper (`sian.agency/taobao-tmall-product-scraper`) Actor

- **URL**: https://apify.com/sian.agency/taobao-tmall-product-scraper/changelog.md
- **Full Actor documentation**: https://apify.com/sian.agency/taobao-tmall-product-scraper.md

## Changelog

All notable changes to **Taobao & Tmall Product Scraper** will be documented in this file.

### \[2026-09-11]

#### 🖼️ Images

- 🖼️ **New `thumbnailUrl`.** Each row now carries a preview image, taken from the first photo on the listing, so the Output tab shows a picture per row.

### \[2026-09-05]

#### 🏬 New operation: Product Page — seller reputation, service terms & specs

- **A new `Product Page` operation** returns the product page as a shopper sees it, and it is the
  only operation in this actor that carries **who is selling and what they promise**: shop
  followers, positive-feedback rate, credit level and badge (e.g. `金牌卖家`, Gold Seller), the
  three buyer-rated seller scores, the return window with dispatch and delivery estimates, the
  shipping cost, and the full specification table.
- **A per-variant SKU table with decoded option names** — `skus[]` carries `priceYuan`, `quantity`
  and a readable `propertiesName` (`尺码:S;主要颜色:白色`) instead of raw `pid:vid` join keys.
- **`price` and `totalStock` are computed from that SKU table**, not from display text, so they
  are real numbers you can sort, filter and compare.
- **Billed at the same per-result rate as Product Detail** — no new charge event, no price change.

#### ⚠️ Read this operation's price and sales as text

`priceText` is a **range** across SKUs (`"78-88"`) and `soldCountText` is rounded by the
marketplace (`"300+"`). Both are returned as text fields and are deliberately never mapped onto
the numeric `price` / `soldCount` columns. Use **Product Detail** when you need exact figures — on
the same item it returns `sales: 700` where Product Page shows `"300+"`.

#### 💎 User Benefits

- Vet a seller before sourcing from them, without leaving the dataset.
- Get shipping cost and delivery expectations that Product Detail usually leaves empty.
- `sellerId` comes back ready to paste straight into the Shop Catalog operation.

#### 🎯 Use Cases

- **Supplier due diligence** — rank candidate sellers by feedback rate, credit level and service scores.
- **Landed-cost modelling** — combine `postage` with per-SKU pricing before committing to an order.
- **Catalogue enrichment** — attach the full specification table to products you already track.

### \[2026-08-28]

#### 📊 One dataset view, and two fields that make every row traceable

- **The dataset now opens straight to one complete Overview** — the separate "Key fields" and
  "Alternate Source" tabs are gone. Every field from every operation lives in Overview now, so
  there's one place to look instead of three.
- **Two new fields on every row: `processedAt` and `scrapingDate`** — a timestamp and a plain
  date for when the actor processed that row, independent of `recordTime` (when the source data
  was actually captured). Use them for freshness audits and slowly-changing-dimension joins.
- **Product images and source URLs now render as clickable links** in the dataset view instead
  of raw text — `images`, `picUrl`, `picUrlFull`, `picUrlList`, `detailUrl`, and `imageList` all
  open directly.

#### 💎 User Benefits

- One dataset view to learn, not three.
- A clear answer to "when was this row processed," without cross-referencing the run log.
- Faster QA — click a thumbnail instead of pasting a URL into a browser.

#### 🎯 Use Cases

- Data teams wiring `processedAt` into a nightly freshness check without touching `recordTime`.
- Analysts scanning a shop catalog by clicking straight through to each product image.

### \[2.7.0] — 2026-08-26

#### ⚡ Product Detail is reliable again

- **A new default detail version.** `Product Detail` now leads with a faster, far more consistently
  available profile (`v3` ⭐ Recommended). Over 24 hours of availability sampling it was reachable in
  21 of 24 hours, against 10 of 24 for the previous default — and it responds in roughly a quarter of
  the time. If it cannot serve an item the actor still falls back to Standard and Full, exactly as before.
- **Stock and units sold are finally populated.** `totalStock` and `soldCount` were empty on every
  Product Detail row before this release — the previous default did not report them as numbers. The new
  default fills both, as real integers.
- **The image gallery is populated too.** `pictUrls` was empty on every Product Detail row, on every
  version. It now carries the full gallery on Recommended, Standard **and** Full.
- **Prices are current, not expired.** The previous default reported whatever promotion the listing last
  carried — on a sample of 24 products, 13 had a promotion window that had already ended, some three
  months earlier. The new default reports the live listed price. If you specifically want the
  list-vs-sale spread, pick `v1` Standard and check its `startTime` / `endTime`.
- **Wrong numbers are now left blank instead of guessed.** Some versions report stock and sales as
  rounded text (`"1万+"`). Converted naively that becomes `1` — a product that sold ten thousand units
  reading as one. Those columns are now left empty on the affected versions and the raw text is passed
  through instead.

#### 💬 Clearer failure messages

- **"This item is not supported" is no longer reported as an error on our side** — it means the item ID
  could not be retrieved, and the message now says so and tells you what to check.
- **Plainer language on every failure**, with the retry advice unchanged. Failed items are still never charged.

### \[2.6.1] — 2026-08-26

#### ⭐ Fixed — review star ratings were the same number on every row

- **`reviewRatingStars` now carries the real 1-5 rating.** It was reading an internal validity flag that reports `1` for every review, so the column looked filled in but told you nothing — you could not sort by rating or filter for negative reviews. It now reads the actual per-review score. If you have stored review data from before this release, that column needs re-fetching.

### \[2.6.0] — 2026-08-24

#### 📄 A run report you can actually use

- **See your first result without leaving the report** — the top of every run report now shows one complete row as copyable JSON, so you can check the field names your pipeline needs before you open the dataset.
- **A preview table built for the operation you ran** — reviews show stars, text, the variant bought and the buyer; searches and shop catalogs show product, price, sales and shop; product detail shows the facts that version returned. No more guessing which columns apply.
- **Failed items come with a one-click retry** — every failure now carries a plain-English reason, a concrete fix, and a **Copy retry input** button that hands you the exact JSON to re-run. Failed rows are never charged, and the report says so.
- **An itemized statement of what you paid** — every charge on the run, at the price your plan actually pays, with the total. Shop Catalog duplicates are dropped before charging and appear as a separate number.
- **Run it again on a schedule, or from an AI agent** — the report links straight to a schedule for this exact input, and ships a ready-made MCP config so Claude, ChatGPT or your own agent can run the Actor in plain language.
- **Chinese product names render correctly** — the report is now served as UTF-8, so titles, shop names and review text no longer arrive as mojibake.

#### 🖼️ Product images in the dataset view

- **Thumbnails instead of URLs** — the Overview, Key fields and Alternate Source views now render the main product image as an actual picture, so you can scan a catalog visually instead of pasting URLs into a browser.
- **Readable field names** — 36 raw column names (`Discnt Price Yuan`, `Fahuo Dsr`, `Pic Url Full`, …) now carry proper labels and icons in the dataset schema.

#### 💎 User Benefits

- Less time spent working out what a run produced, and what it cost.
- A failed item is now a two-click fix instead of a support question.
- Visual catalog scanning for sourcing and competitor work, straight in the Apify Console.

#### 🎯 Use Cases

- Dropshippers checking SKU pricing and stock before ordering, straight from the run report.
- Sourcing teams scanning a Tmall shop catalog by product image rather than by ID.
- Data teams wiring the Actor into an AI agent with the MCP config the report hands them.

### \[2.5.0] — 2026-08-15

#### 🔄 New operation: Product Detail — Alternate Source

- **New: `productDetailAlt`** — the same product lookup served from a **different source**, for items the standard detail versions cannot return. In testing it resolved products that returned *"This item is not supported"* on `v1`. Returns a compact flat row: price and CNY price, total stock, per-SKU variants, images, description, brand and tags. Comes with an **Alternate Source** dataset view.
- **Billed at the same per-result rate as Product Detail** — it is a coverage option, not an upsell. No pricing change in this release.
- **It is a separate operation, not a new `detailVersion`.** It comes from a different source whose response shares **no fields** with the Product Detail versions, so folding it in would have changed Product Detail's columns depending on which version answered. Filter on `_operation` to tell them apart. Product Detail is completely unchanged by this release.
- `itemId` is stamped from your input and `detailUrl` is rebuilt, because this source returns neither.
- It also passes through import-oriented fields (`exchangeRate`, `expressFee`, `startQuantity`, `batchPrice`). **These were empty or trivial on every item tested**, so they are documented as best-effort rather than advertised.

#### 🐛 Fixed

- **Telemetry recorded the wrong detail version.** Runs that did not set `detailVersion` were fingerprinted as `v9` while the actor actually requested `v1` — skewing the per-version data used to decide which version to lead with.

### \[2.4.1] — 2026-08-14

#### ⚡ `detailVersion: v5` (Cached — Lite) is retired

- **The Lite version is no longer available.** Every request to it came back rejected, so a run that asked for Lite could only ever produce an error row.
- **If you have a saved task set to Lite, it keeps working** — it is now served by **Fresh — Standard (`v1`)** instead, and the option stays in the list purely so those tasks do not break. ⚠️ **Standard returns different field names from Lite**, so check the field matrix in the README if your pipeline pinned a Lite-only field (`shop_id`, `sku_props`, `desc_url`, …). Do not pick Lite for new work.
- **Product Detail stopped dead-ending on unavailable items.** Lite sat at the end of the automatic fallback chain, so any item the other versions could not serve finished on a cryptic rejection message for what is really "no version covers this item". The chain is now Standard → Full, and an exhausted item returns the honest *"This item is not supported."*
- A version that reports the item is unavailable to it now falls through to the next version instead of ending the attempt.

#### 🐛 Fixed

- **The run log named the wrong detail version.** Runs that did not set `detailVersion` were logged as *"Full (fresh)"* while the actor actually requested Standard.

### \[2.4.0] — 2026-07-25

#### 🎯 Product Detail reliability — and honest per-version documentation

- **⚠️ Behaviour change — the default `detailVersion` is now `v1` (Standard), was `v9` (Full).** `v9` has been returning effectively no data for weeks, so leading with it meant most Product Detail runs spent their whole retry budget on a version that could not answer. **If your pipeline depends on `v9`'s flat field shape, set `detailVersion: "v9"` explicitly** — but note it is currently unreliable. Runs that never set `detailVersion` will now receive `v1`-shaped rows (different field names — see the field matrix in the README).
- **Product Detail now recovers instead of giving up.** When a detail version cannot serve an item, the actor falls through to the other standard versions rather than failing the row. Previously only "item not supported" triggered the fallback; a timeout ended the run empty. Recovered rows are complete rows, and failed attempts are never billed.
- **Fixed: Standard (`v1`) rows were missing most of their content.** Specifications, description HTML and the whole seller/shop block were silently dropped, and the price aliases were empty. All are now populated — a `v1` row went from ~20 usable fields to ~50.
- **📚 New: a field × version matrix in the README.** Each detail version returns a genuinely different field set — only `itemId`, `title` and `images` are common to all of them, and `v5` uses `snake_case` where `v1` uses `camelCase`. The matrix is generated from live live payloads, and the previous output field list (which advertised fields the actor never emitted) has been replaced.
- **📚 Documented the automatic fallback**, so it is clear that `detailVersion` is a preference and the version that answers determines the field names. The 💎 Premium version is never substituted in either direction — a standard request can never be upgraded into premium billing.
- **📚 Removed the `v2` "async premium" option from the docs.** It was never selectable: it is offered only through its own dashboard task page, and calling it over the API returns no data. Use `v4` for premium final pricing.

### \[2.3.0] — 2026-06-19

#### 🚀 Five operations — premium final pricing and buyer Q\&A

- **💎 Premium Detail — Final Payable Price** — a new premium product-detail version returns the exact **after-coupon final price** per product and per SKU, so you can calculate true margins and re-price with confidence. Priced at $0.20/result, effective 2026-07-02.
- **❓ Product Q\&A** — pull real pre-purchase buyer questions and answers for any product, plus the top buyer-concern tags — ideal for listing optimization and customer-intent research. Priced at $0.008/result, effective 2026-07-02.
- **🏪 Bigger Shop Catalogs** — an additional catalog mode for the latest, largest seller listings.
- **🔍 Keyword Search up front** — keyword search is now the default operation: the fastest way to discover products by query, price, and rating.

#### 💎 User Benefits

- **Know your real cost** — final after-coupon pricing replaces guesswork for sourcing and re-pricing decisions.
- **Understand demand before you buy** — buyer questions reveal what shoppers actually care about before they purchase.
- **More coverage, one actor** — products, prices, shops, search, reviews, and Q\&A in a single tool.

#### 🎯 Use Cases

- Dropshippers validating true landed cost with after-coupon final pricing before listing a product.
- Sourcing teams mining buyer Q\&A to pre-empt customer questions and sharpen product descriptions.
- Listing optimizers using top buyer-concern tags to rewrite titles and descriptions that convert.

### \[2.2.0] — 2026-06-17

#### 🕒 Data Freshness — capture timestamps + clearer detail versions

- **🆕 New `recordTime` field on every row** — the exact capture timestamp (when the data was actually scraped), separate from `_fetchedAt` (when your run executed). Use `recordTime` to verify how fresh each row is. Surfaced on Product Detail (all versions), Keyword Search, Shop Catalog, and Reviews.
- **🔁 Product Detail versions relabelled by freshness** — the `detailVersion` option now states clearly which versions are fresh vs cached:
  - **`v9` Full** — live, non-cached. **New default.**
  - **`v1` Standard** — live, non-cached. Slightly different coverage; combine with `v9` to maximise coverage.
  - **`v5` Lite** — ⚠️ **cached** (data can be days to months old, no reliable capture time). No longer recommended when freshness matters; use only when stale data is acceptable.
- **📖 Docs** — README adds a "Data freshness & detail versions" section, corrects the freshness FAQ, and documents the optional async detail versions (fuller campaign pricing, available on request).
- **📊 Dataset views** — added an Overview view (all fields) plus a curated "Key fields" view that includes `recordTime`.

#### 💎 User Benefits

- **Provable freshness** — every row tells you exactly when it was captured.
- **No more surprise stale data** — the cached version is clearly marked; the default is now a fresh version.

### \[2.1.0] — 2026-05-07

#### 🔧 Bug Fixes + Enhanced Pagination Metadata

- **🗑️ Removed Shop Catalog v3** — the v3 option is not available. The `catalogVersion` option now only supports `v1` (Standard) and `v2` (Extended).
- **📊 New Pagination Metadata** — all paginated operations now include total count and page metadata in every row:
  - `keywordSearch`: `_totalItems`, `_totalPages` (from `data.model.page`)
  - `shopCatalog` (v2): `_totalItems`, `_totalPages` (from `data.httpData.itemListModuleResponse.page`)
  - `productReviews`: `_maxPage` (complements existing `_totalReviews`)
- **📖 New REFERENCES.md** — added example inputs and outputs for every operation, including sample fields and pagination metadata

#### 💎 User Benefits

- **More predictable pagination** — see total results upfront without extra API calls
- **Cleaner input options** — v3 option removed to prevent confusion and errors
- **Better documentation** — concrete examples for every operation help users understand data structure before running

### \[2.0.0] — 2026-05-06

#### 🚀 Major Upgrade — Direct API + v9 Detail + v2 Shop Catalog

- **🆕 Product Detail v9** — flat response with coupon-adjusted pricing (`afterCouponAmountPrice`), full product attributes, specs map, SKU images, seller type, and promotion model data. The most complete product detail available.
- **🆕 Shop Catalog v2** — 60 items per page (2x v1's 30), five sort options (comprehensive, hot selling, new arrivals, price ascending, price descending), and sell-point highlights per item. Requires `shopId` in addition to `userId`.
- **🔀 Sort Order Support** — keyword search and shop catalog results can now be sorted by sales, price, comprehensive ranking, hot selling, or new arrivals via the new `sort` input field.
- **💬 Review Sort** — product reviews can be sorted by date (`feedbackdate`) or relevance (`general`) via the new `orderType` input field.
- **⚡ Faster responses** — roughly 2s per page, down from ~5s. Simpler and more reliable.
- **🛡️ Clearer Error Messages** — when a row can't be retrieved, it now says what happened and what to try next instead of showing a raw error code.

#### 💎 User Benefits

- **60 items/page with v2** — scrape full shop catalogs in half the time and cost. A 1,000-item shop now needs ~17 pages instead of ~34.
- **Coupon pricing in v9** — see the actual price after coupons and promotions, rather than the list price. Critical for accurate margin calculations.
- **5 sort options for shops** — find bestsellers, newest arrivals, or cheapest products directly. No need to sort 3,000 rows client-side.
- **Faster responses** — direct API calls cut ~3 seconds of latency per page compared to the previous architecture.

#### 🎯 Use Cases

- Dropshipping operators using v9 detail for coupon-adjusted margin calculations and full SKU attribute analysis
- E-commerce teams switching to v2 shop catalog for 2x faster competitor catalog sweeps with price sorting
- Market researchers using sort options to find hot-selling and new-arrival products without post-processing
- Data teams leveraging v9's structured attributes and specs for automated product categorization pipelines

### \[1.0.0] — 2026-04-27

#### 🎉 Taobao & Tmall Product Scraper — Launch!

- **🛍️ Four-in-One Scraper** — Product detail lookup, keyword search, shop catalog sweep, and customer review extraction — all in one actor, one operation per run
- **🎨 SKU Variant Intelligence** — Per-SKU prices, stock, property paths, and swatch images for every color/size combo — perfect for dropshipping decisions
- **🔍 Multi-Language Keyword Search** — Search Taobao and Tmall with Chinese, English, or mixed queries, plus price range and Tmall-only filtering
- **🏪 Full Shop Catalog Sweep** — Pull a seller's entire product list by shop ID — ideal for brand mapping and competitor intelligence
- **💬 Rich Review Scraping** — Customer reviews with text, photos, videos, purchased variant, reviewer info, helpfulness votes, and follow-up appended comments
- **📊 79 Structured Fields** — Every response pre-flattened into a flat row — no parsing nested Chinese JSON
- **🎬 Full Media URLs** — Product videos, description galleries, review photos and videos — all as direct downloadable links
- **🔋 Two Detail Depths** — Rich (full payload) for research; Lite (compact) for high-volume runs
- **📄 Smart Pagination** — Auto-paginate keyword search, shop catalog, and reviews with a single `maxPages` setting (up to 50)
- **👁️ Three Dataset Views** — Overview, Products, and Reviews views predefined — switch perspectives without re-running
- **🌏 English Title Translation** — Search results include machine-translated English titles where available
- **💎 No Account Required** — No Taobao account, no API key, no setup — paste an item ID or keyword and run
- **💰 Flat Pay-Per-Result Pricing** — No monthly minimums, and you're only charged for rows you receive

#### 💎 User Benefits

- **Save 20+ hours of setup** per Taobao scraping project — skip HTML parsing, anti-bot workarounds, and variant flattening
- **Ship BI dashboards in an afternoon** — three ready-to-filter views export directly to Google Sheets, Airtable, Snowflake, BigQuery, and Postgres
- **Dropship smarter** — SKU-level pricing, stock, and seller reliability indicators in every row
- **Catch price drops automatically** — schedule daily Shop Catalog runs with `_fetchedAt` for slowly-changing-dimension logic
- **Zero learning curve** — pick one of four operations, provide one input, get one clean dataset

#### 🎯 Use Cases

- Dropshipping operators finding validated best-sellers via keyword search + SKU-level variant data
- E-commerce teams running daily competitor price monitoring on Tmall brand-store catalogs
- Brand founders sourcing private-label OEM partners and filtering by seller level / location
- Marketing agencies mining customer review photos, videos, and authentic Chinese copy for UGC ad creative
- Market researchers mapping entire product categories with 500+ rows per run
- Amazon FBA sellers researching Chinese brands expanding overseas
- Data teams enriching internal product catalogs with Taobao market data