1688 Scraper — Product & Supplier Search, MOQ & Landed Cost

Research ANY product category on 1688.com — Alibaba's domestic wholesale marketplace — and get sourcing-grade rows, not raw Chinese HTML.

Type one English keyword ("led strip lights", "yoga mat", "phone case"), and get back research-ready products: machine-translated English titles, MOQ price ladders, supplier trust signals, a 0–100 dropship score, an estimated landed cost in USD, and compliance hints for your target market. Every row carries a scrapedAt timestamp so freshness is verifiable.

No Chinese needed. No 1688 account. Failed or zero-result runs cost $0; a successful run bills a $0.01 base fee plus per-event fees. Fail-not-billed.

After your first search — Price Monitoring Mode: reuse the offer IDs from your search results (watchlistOfferIds), attach a Schedule (e.g. daily), and get a per-offer history curve, day-over-day / 7-day-low change metrics and price-drop / stock-tight alerts — without ever re-searching. See Price Monitoring Mode below.

Keywords: 1688, 1688 scraper, wholesale, dropshipping, product research, supplier search, landed cost, MOQ, China sourcing

---

🎯 What you can do with it

• Product selection — scan a category at factory prices before you commit to a supplier
• Price comparison — sort by price or sales and read the full quantity-break ladder per product
• Dropshipping evaluation — every product scored 0–100 from four observable signals (one-piece dropship support, MOQ, supplier composite score and repeat-purchase rate); dataQuality / scoreConfidence show how much evidence backs each score
• Margin math — estimated landed cost (product + shipping + duty + fees) and suggested retail with margin % for US / EU / UK
• Compliance screening — required certs and risk level per target market (FDA / CE / Prop 65 / FCC hints)

---

⚡ Quick start: 20 fully enriched products for $0.17

Start with one keyword search and the complete detail layer. The Console Try form and the Actor-level API example use this same starter input:

{
  "keyword": "phone case",
  "maxItems": 20,
  "includeDetails": true,
  "targetMarket": "US",
  "sort": "relevant",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "CN"
  }
}

On the FREE tier complete delivery costs 20 × $0.005 search-item + 20 × $0.003 detail-item + $0.01 run-base-fee = $0.17, with 20 detail-item events. The Console starter prefill is maxItems: 20 and includeDetails: true; API callers that omit those fields keep the existing defaults of maxItems: 40 and includeDetails: true.

The 20-item batch is intentional: card-only rows can lack MOQ, quantity-break ladders and weight, while detail requests below 20 automatically downgrade to card-only. This starter is designed to show the advertised MOQ, price-ladder, weight, landed-cost and evidence-backed scoring fields in the first run.

After a successful search, open SUMMARY or OUTPUT and choose a ready-made next step instead of reconstructing JSON by hand:

1. Deepen a card-only search: after an explicit includeDetails:false run or an automatic small-batch downgrade, copy nextSteps.detailSearch.input for a 20-item full-detail run. Complete delivery on the FREE tier is 20 × $0.005 search-item + 20 × $0.003 detail-item + $0.01 run-base-fee = $0.17. A run that already delivered full detail does not offer this redundant next step.
2. Watch the delivered offers: copy nextSteps.priceMonitor.input. It contains up to 10 valid, deduplicated offerId values from the rows actually delivered, in dataset order. With 10 IDs, one run is 10 × $0.015 snapshot-item + $0.01 run-base-fee = $0.16; daily for 30 days is 30 × $0.16 = $4.80. Bind your own Schedule—the Actor never creates one automatically. The first run seeds history; curves and change metrics start with the second run.

Both estimates use FREE-tier list prices and assume complete delivery; they are not a promise that a budget cap will fund every row. If the original input carried an explicit positive maxTotalChargeUsd, the suggested inputs preserve it and estimateExceedsCap tells you whether the estimate fits. Zero-delivery, monitoring and unsettled runs do not emit nextSteps.

---

📈 Price Monitoring Mode

Already know which 1688 offers you care about? Stop re-searching — watch their prices over time. Fill watchlistOfferIds (up to 200 offer IDs) and the Actor switches from search mode to monitoring mode: each run snapshots every watched offer at card level, appends it to your private history, and returns one snapshotItem row per delivered offer with its curve, change metrics and alert status.

Use the Dataset's Price snapshots view for per-offer prices, MOQ, available stock, history and changes; Monitoring reports shows run-level alerts and status, while Trend reports shows the weekly aggregate and rankings. The original Overview remains dedicated to product-search rows.

Three steps:

1. Fill the watchlist — paste the numeric offer IDs (from a product URL, e.g. 781924595627) into watchlistOfferIds. Optionally set alert thresholds (alertOnPriceDropPct, alertOnStockTightPct) and a webhookUrl.
2. Attach a Schedule — the Actor never self-schedules; bind a Schedule (e.g. 0 8 * * * for 08:00 daily) so history accumulates. One run per day = one point on the curve.
3. Read the results — each successfully persisted offer produces one atomically billed snapshotItem row with snapshotAt, current{price, priceTierMinQuantity, consignPrice, moq, bookedCount, supplier}, history{days, min, max, last7dLow}, changes{vsPrevDayPct, vs7dLowPct, stockTightPct}, and alertHit. price keeps the lowest observed bulk-tier price across runs so historical comparisons stay consistent; priceTierMinQuantity identifies that tier, while consignPrice is the MOQ-tier price when the ladder exposes one (otherwise the headline upper price is the small-order proxy). bookedCount is the reported available stock, not total sales; implausible values above 10,000,000 are omitted rather than used for stock alerts. Set includeTrendReport=true for a trendReport roll-up once comparable history exists. A first run without a previous comparable price sets trendReportSkipped: "insufficient_history" and neither delivers nor charges a report; avgPriceChangePct averages only offers with a real previous-price comparison, never treating missing history as 0%.

Where the offer IDs come from. Any 1688 product URL carries one (detail.1688.com/offer/781924595627.html). If you are still discovering products rather than watching known ones, run a search first and reuse its output: this Actor's own search rows carry offerId, and so does every match in 1688 Image Search Scraper — there it sits at results[].offerId on each imageResult row (one row per query image, matches nested inside), so a reverse-image search of a product photo turns directly into a price watch on everything it matched. IDs that cannot be read as numeric are named in SUMMARY.invalidOfferIds and never billed, so a stale or mistyped ID costs nothing.

What it costs (monitoring mode):

Event	Price	When it's charged
snapshot-item	$0.015	Per offer successfully snapshotted and written to history
trend-report	$0.25	Once per run when includeTrendReport=true delivers a report
alert	$0.00	Never billed (price-drop / stock-tight alerts are a free retention hook)
run-base-fee	$0.01	Once per run that bills at least one event

A daily run watching 10 offers costs 10 × $0.015 + $0.01 = $0.16 (no trend report). If the history store is unreachable, the run marks errorCode: KV_UNAVAILABLE, withholds successful snapshot payloads, and charges $0.00—no result is pushed for free. Truncated IDs (over 200) and invalid IDs are reported per-item and never billed.

What a standing watchlist costs per month (FREE-tier prices; the per-event prices drop 10 / 20 / 30% at Bronze / Silver / Gold, the $0.01 base fee is flat):

Watchlist	One run	Daily (30 runs)	Weekly (4.33 runs)	Weekly + trend report
3 offers	$0.055	$1.65	$0.24	$1.32
5 offers	$0.085	$2.55	$0.37	$1.45
10 offers	$0.16	$4.80	$0.69	$1.78
20 offers	$0.31	$9.30	$1.34	$2.43
50 offers	$0.76	$22.80	$3.29	$4.38
200 offers (cap)	$3.01	$90.30	$13.04	$14.13

Every cell is (offers × $0.015 + $0.01) × runs per month, plus $0.25 per run in the last column. Two things worth internalising before you pick a frequency:

• The $0.01 base fee is per run, not per offer, so it dominates a small watchlist run often: 3 offers daily is $1.65/month, and $0.30 of that is base fee. Watching 3 offers weekly costs $0.24 — if you do not need daily resolution, weekly is nearly 7× cheaper.
• The $0.25 trend report costs more than snapshotting 16 offers. On a 3-offer watchlist it is 82% of the run's bill, which is why the quick-start below leaves includeTrendReport off and the ready-made weekly radar template turns it on: a weekly roll-up over a wide watchlist is where a $0.25 aggregate earns its price. Turning it on daily instead would cost $10.05/month on 5 offers versus $2.55 without.

Your history is private. Snapshots live in an owner-side named Key-Value store (price-snapshots) keyed by your Apify user id, so two users watching the same offer never see each other's curves. The Actor reaches it with a scoped, secret-injected API token — never a hard-coded credential.

Ready-made monitoring templates (one click):

• Track my 1688 shortlist prices daily — a 3-offer watchlist wired for a daily Schedule
• Weekly price-drop radar — a weekly drop / stock-tightening sweep with the trend report on

Monitor quick-start input — byte-for-byte the input of the daily template above, and verified delivering on build 0.1.36 (run TTAUZX3djQ38T2cKa: 3 of 3 offers snapshotted, snapshot-item 3 + run-base-fee 1, historyReadOk: true, SUCCEEDED). All three IDs are live products, so copying this produces a real curve rather than three snapshot_failed rows:

{
  "watchlistOfferIds": ["781924595627", "659979401746", "993816303199"],
  "historyDays": 30,
  "alertOnPriceDropPct": 5,
  "alertOnStockTightPct": 30,
  "includeTrendReport": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "CN"
  }
}

includeTrendReport is off here on purpose — at 3 offers the $0.25 report would be 82% of the bill (see the table above). Turn it on when the watchlist is wide and the frequency is weekly, which is exactly what the weekly price-drop radar template does (4 offers, verified on run MtqCm2nffCkc2ndC0: 4 of 4 snapshotted, trend-report 1, report carried offersTracked: 4 with 2 ranked price drops).

---

⚡ Three points that matter

1. Decision-grade enrichment, not raw dumps — landed cost, dropship score and compliance hints come attached to each product row. You stop paying for data you still have to research by hand.
2. Honest billing — search-item (and monitoring snapshot-item / trend-report) uses the SDK's atomic Actor.pushData(rows, eventName) path: budget-limit first, push the accepted prefix, then charge it. detail-item and run-base-fee settle only after the product rows are pushed; the pre-work billing plan reserves those events so they should settle in full, while any partial/zero/error is exposed as billingInvariantViolation plus errorBuckets in SUMMARY.
3. A budget cap you control — the effective ceiling is min(input maxTotalChargeUsd, Apify platform cap). Current subscription-tier prices are read at runtime, detail/base costs are reserved before work, and the ledger uses the SDK's actual ChargeResult counts.

This is not presented as a distributed transaction across all events: the SDK atomically couples each result-row event to its dataset push, while detail-item and run-base-fee are separate post-push settlements protected by the pre-reserved budget and explicit invariant reporting.

---

⚡ One-click examples

Skip the input form — these public tasks run proven configurations in one click:

• 1688 Wholesale Search by Keyword — a deeper search: one English keyword → detail-enriched factory offers in English
• 1688 Supplier Lookup — Factory & Trust Signals — best-selling offers first, with supplier trust signals on every row
• 1688 MOQ & Price Range Scan — filter a category to your CNY budget band and read the MOQ ladders
• 1688 Landed Cost Sourcing — US — duty, shipping and margin estimates for the US market
• 1688 Dropship-Ready Product Research — readiness scores for one-piece-shipping candidates
• 1688 Price Monitor for My Shortlist — daily price curves and drop/stock alerts for offers you already track
• Price Comparison — sorted by price — cheapest first for instant comparison
• Price Ladder Deep Scan — MOQ price-break ladders across a whole niche
• Supplier Vetting Report — detail-enriched rows for supplier shortlisting
• MOQ Ladder Comparison — side-by-side MOQ and unit-price comparison

---

🔑 What keywords can you use? Any category.

This is not a vertical scraper — one input accepts any English product keyword. English keywords are sent to 1688.com as typed and 1688's own search matches them: common product terms like the ones below return relevant results, very niche English terms can return fewer. Pet-supply keywords are additionally mapped to Chinese search terms (500+ built-in mappings). Examples:

Keyword	Typical use
led strip lights	Consumer electronics price scan
phone case	High-volume accessory sourcing
yoga mat	Sports & fitness selection
stainless steel water bottle	Home & outdoor comparison
car phone holder	Auto accessories research
plush toy	Gifts & toys compliance screening

Anything sold on 1688.com is in scope — the plainer and more common the English product name, the better the match.

---

📄 Sample output

Actual row from owner verification run VsBB4dpPw797yXslj (build 0.1.37):

{
  "offerId": "659979401746",
  "titleCn": "狗碗批发食盆宠物碗狗盆单碗猫碗猫食盆大号跨境Dog supplies PET",
  "titleEn": "Dog Bowl Wholesale Pots Pet Bowl Dog Pots Single Bowl Cat Bowl Cat Pots Large Cross-Border Dog supplies pet",
  "price": { "min": 3.1, "max": 3.1, "currency": "CNY", "unit": "piece" },
  "quantityPrices": [
    { "price": 3.1, "minQuantity": 1 },
    { "price": 3, "minQuantity": 100 },
    { "price": 2.9, "minQuantity": 1000 }
  ],
  "moq": 1,
  "salesTotal": 209,
  "supplierName": "义乌优宝宠物用品有限公司",
  "isSuperFactory": true,
  "detailUrl": "https://detail.1688.com/offer/659979401746.html",
  "estLandedCostUsd": {
    "totalLandedCostUSD": 1.5,
    "suggestedRetailPriceUSD": 4.5,
    "estimatedMarginPercent": 66.7
  },
  "dropshipReadyScore": 80,
  "dropshipGrade": "A",
  "scoreConfidence": "ok",
  "compliance": {
    "targetMarket": "US",
    "suggestedCertifications": ["CPSC compliance"],
    "riskFlags": []
  },
  "scrapedAt": "2026-11-08T09:02:15.521Z"
}

Additional fields cover attributes, shipping & stock, supplier repeat rate, factory-inspection flags, and product/description images. The standard quantity-break ladder is quantityPrices; skuDetails is optional and normally empty with standard public inputs. dataQuality describes the completeness of the four score inputs, not detail-fetch status; detail delivery is reported separately in SUMMARY.detailLevelCount/detailStatus. Read it together with scoreConfidence before treating a score as a strong supplier verdict.

Translation honesty rule: titleEn only ever carries an English title. Titles are translated via a free translation API chain (translationMethod="api") with an offline dictionary fallback (translationMethod="dictionary"). When neither can produce clean English for a title, titleEn is left empty rather than shipping a Chinese/English mix — the original Chinese is always preserved in titleCn.

---

🆚 How it compares

	This Actor	Other 1688 wholesale scrapers	Typical 1688 scrapers
Startup / run fee	None — a $0.01 base fee applies only to successful runs	Often a per-run fee — billed even when nothing is delivered	Often yes
Failed / zero-result runs	$0.00 — never billed	Usually billed at least the startup fee	Usually billed
Enrichment trio (landed cost + dropship score + compliance)	Included	Not offered	Not offered
Budget cap (maxTotalChargeUsd)	Pre-work cap + SDK atomic push/charge + factual ledger	Not offered	Not offered
English titles	Machine-translated	Chinese only	Chinese only
Freshness proof	scrapedAt on every row	—	—
Pricing	$0.005/search-item + $0.003/detail-item + $0.01 base (successful runs only)	Per-item + startup + extras	Per-row tables

---

🛡️ Trust at a glance

What we commit to	How it works here
Pay only for delivered results	Zero-result runs cost $0.00 — billed per row actually delivered; successful runs add a single $0.01 base fee, nothing else
No hidden usage fees	Pure pay-per-event pricing; proxy and platform compute costs are included, never passed through
Honest degradation	Every run's SUMMARY discloses exactly what happened — partial deliveries always come with a named reason
Audit-ready billing ledger	SUMMARY reports current-tier prices, effective cap, affordable rows, raw ChargeResult outcomes, factual charged counts, withheld rows and platform-count reconciliation
MCP / agentic-payment ready	Input, dataset, key-value-store and output schemas are all declared — machines can validate the contract before calling
Issues answered fast	Open an Issue instead of guessing — our response time is public on the developer profile
Loved it? Leave a review	If this saved you sourcing hours, a quick review helps other buyers find it — and we read every one

---

💰 Pricing (pay-per-event, no subscription)

Event	Price	When it's charged
search-item	$0.005	Per delivered product card
detail-item	$0.003	Per delivered card with full detail enrichment
snapshot-item	$0.015	Per offer successfully snapshotted in Price Monitoring Mode
trend-report	$0.25	Once per monitoring run when includeTrendReport=true
run-base-fee	$0.01	Once per successful run (charged once per successful run, only when at least one row was delivered)
Startup fee	$0.00	Never

There is no minimum charge. Small orders bill strictly per event (a 1-card run costs $0.015). The platform price list's minimalMaxTotalChargeUsd ($0.04) is a budget-PROTECTION parameter for the platform, not a minimum spend.

The "from $3.50 / 1,000" price shown on the Store page is the GOLD subscription-tier rate; on the FREE tier you pay $5 per 1,000 items (the list prices above).

Volume subscribers get the standard Apify platform tier discounts. At runtime the Actor reads those current tier prices plus Apify's platform cap, applies min(input cap, platform cap), reserves run-base-fee, and limits work and delivery to affordable rows. maxTotalChargeUsd: 0 means zero paid rows; the Console schema accepts 0 explicitly.

Failed or zero-result runs cost $0. A successful run bills a $0.01 base fee plus per-event fees ($0.005/search-item, $0.003/detail-item, $0.015/snapshot-item, $0.25/trend-report).

Worked examples (FREE tier):

Run shape	Math	Total
1-item trial (card only)	1 × $0.005 + $0.01 base	$0.015
10 cards (card only)	10 × $0.005 + $0.01 base	$0.06
40 fully enriched products	40 × $0.005 + 40 × $0.003 + $0.01 base	$0.33

Best value at 20+ items — per-item fees amortize the $0.01 run fee. If includeDetails=true is requested with maxItems < 20, the Actor automatically switches to card-only before any proxy/browser starts; SUMMARY.deliveryShape.reason is DETAILS_MIN_20_AUTO_CARD_ONLY.

---

❓ FAQ

Do I need a 1688 account or any Chinese? No account, no Chinese. Type an English keyword and it is searched on 1688.com as typed (pet-supply terms are also mapped to Chinese); titles come back machine-translated to English (titleCn keeps the original).

How do I search 1688 by keyword in English? Put your term in keyword (e.g. phone case, yoga mat) and run — you get research-ready product rows with prices and supplier signals; includeDetails:true with at least 20 items adds the full detail layer, including MOQ ladders and weight. No URL hunting.

Can I find suppliers / factories, not just products? Yes — every row carries supplier trust signals (name, super-factory flag, repeat-purchase rate, inspection flags) so you can shortlist suppliers, and sort=sales surfaces the highest-volume offers first.

How is this different from an Alibaba.com scraper? 1688.com is Alibaba's domestic wholesale marketplace — factory-direct prices well below Alibaba.com's export listings. This Actor turns that Chinese-only data into English, decision-ready rows (landed cost + dropship score + compliance).

What batch size is best value? 20+ items — per-item fees amortize the flat $0.01 run fee. Below 20, an includeDetails=true request is automatically delivered card-only; request includeDetails=false directly if that is already your intent.

What does the dropship score mean? A 0–100 heuristic built from four observable inputs: one-piece dropship support, MOQ, supplier composite score and repeat-purchase rate. Their original 30:20:10:5 weights are normalized across those four inputs, and a missing input receives a neutral subscore rather than fabricated evidence. Use dataQuality and scoreConfidence to see how much evidence backs the grade; it is a screening aid, not supplier verification.

How is landed cost calculated? Product price + estimated shipping + duty + fees for your targetMarket (US/EU/UK), returned with a suggested retail price and margin %. It's an estimate to compare offers, not a customs quote.

What happens on a failed or zero-result run? It costs $0.00. A run with no delivery because the search channel is blocked or unavailable ends as FAILED, with RISK_CONTROL_ZERO or INFRA_ERROR in SUMMARY; a genuine NO_MATCH remains a clean zero-result run. A successful run adds a single $0.01 base fee plus per-event fees, and every run writes a SUMMARY ledger (charged vs intended) you can audit.

Can I monitor prices over time? Yes — fill watchlistOfferIds, attach a Schedule, and the Actor switches to Price Monitoring Mode (history curve + drop/stock alerts). See Price Monitoring Mode above.

---

🧭 Part of the 1688 sourcing toolkit

• 🖼️ 1688 Image Search Scraper — have a product photo instead of a keyword? Reverse-image-search 1688 and get the same sourcing-grade rows.
• 🎵 TikTok Shop Scraper — spot a product going viral on TikTok Shop, then bring the keyword here to find the 1688 factory behind it.

---

🤖 For AI agents / MCP

All four schemas are published: input schema, dataset schema, key-value-store schema and Actor output schema. SUMMARY separates NO_MATCH, RISK_CONTROL_ZERO and infrastructure/billing buckets instead of treating every zero-result run as success. It also exposes deliveryShape{requested,effective,actual,reason}, tokenPath (raw warm acceptance versus later business success), billingPlan, factual chargedCount, and costGuard.freeRows: 0. Apify schemas cannot issue dynamic cross-field warnings, so the maxItems/includeDetails auto-downgrade rule is documented statically in both field descriptions.

• Complete output schema — every delivered field (English titles, MOQ price ladders, supplier trust signals, dropship scores, landed cost, compliance) is typed and documented, so tool-calling loops can parse results without guesswork.
• API-first — one English keyword in; one POST to run-sync-get-dataset-items returns the final dataset in a single call. No Chinese required, no browser session, login or captcha step.
• Agentic payments ready — the effective cap is the lower of input and platform limits; work is pre-capped, detail/base costs are reserved, and search rows use the SDK's atomic push/charge path. The factual ChargeResult.chargedCount controls the delivered prefix, while settlement anomalies are machine-readable in billingInvariantViolation and errorBuckets.

Capability boundary

It does	It does not
One English keyword → 1688.com product rows with English titles and supplier signals; 20+ items with includeDetails:true adds MOQ price ladders, weight, evidence-backed dropship scores, estimated landed cost and compliance hints	Taobao, Tmall or Alibaba.com international — 1688.com only
Direct fetch by offerId (skip search entirely)	No login, no account, no cookies from you, and no ordering, purchasing or supplier contact
Price Monitoring Mode: snapshot a fixed watchlist over time, with a history curve and free price-drop / stock-tight alerts	No reverse image search — that is 1688 Image Search Scraper
Machine-translated English titles (titleCn keeps the original)	No supplier/company-level profiles — that is 1688 Supplier Finder

Minimal successful call

{
  "keyword": "phone case",
  "maxItems": 10,
  "includeDetails": false
}

That is the whole input. maxItems below 20 with details requested auto-downgrades to card-only anyway, so asking for cards directly is the cheapest first probe.

Field names are forgiving. keywords, keyword, searchKeywords, searchKeyword, searchTerms, searchTerm, query, search and q are all read; a string, an array of strings, or one comma/newline/semicolon-separated string all work. offerIds and watchlistOfferIds accept an array, a single value, or a delimited string, quoted or not. Nothing is reinterpreted silently: SUMMARY.keywordFieldUsed, maxItemsClamped / maxItemsRequested / maxItemsApplied, maxItemsIgnored and invalidOfferIds say exactly what we made of your input.

Out-of-contract values are rejected before the run starts, for free. Apify validates the input against the published schema, so maxItems above 200 or a sort outside the enum never becomes a run at all — the API answers 400 invalid-input naming the field (measured: Field input.maxItems must be <= 200, Field input.sort must be equal to one of the allowed values: "relevant", "sales", "price"). Inside the Actor the same two limits are enforced a second time — an oversized maxItems is clamped to 200 and reported as SUMMARY.maxItemsClamped, an unreadable one as maxItemsIgnored — for the callers whose input never passed schema validation (a hand-edited INPUT record, a local apify run).

What a run costs

List prices (FREE tier). A paid subscription tier costs less, and SUMMARY.economics.unitPrices reports the prices your run actually applied.

Call shape	Math	Total
1 card (cheapest probe)	1 × $0.005 + $0.01 base	$0.015
20 fully enriched products (Console starter prefill)	20 × $0.005 + 20 × $0.003 + $0.01 base	$0.17
40 fully enriched (API defaults when fields are omitted)	40 × $0.005 + 40 × $0.003 + $0.01	$0.33
200 fully enriched (the cap)	200 × $0.005 + 200 × $0.003 + $0.01	$1.61
Zero results, unusable input, or fully blocked	0 events	$0.00

maxItems cannot exceed 200 (the platform rejects a larger value before the run starts, and the Actor clamps it anyway), so $1.61 is the worst case for one run — an agent cannot accidentally order 10,000 rows. Set maxTotalChargeUsd for a harder ceiling of your own.

Reading the outcome

SUMMARY and OUTPUT hold the same record and both are written on every exit path.

errorCode	Run status	Charged	What it means
(absent)	SUCCEEDED	per delivered row	Rows delivered.
NO_MATCH	SUCCEEDED	$0.00	1688 genuinely has nothing for that keyword. One search request, no retries burned.
NO_INPUT	SUCCEEDED	$0.00	No usable keyword / offerId / watchlist. message lists every accepted field name and shape.
BUDGET_EXHAUSTED	SUCCEEDED	$0.00	maxTotalChargeUsd cannot fund a single row. No proxy, browser, push or charge was attempted.
PARTIAL_NO_MATCH, PARTIAL_RISK_CONTROL, PARTIAL_INFRA_ERROR	SUCCEEDED	delivered rows only	Some keywords failed, the rest delivered.
RISK_CONTROL_ZERO	FAILED	$0.00	1688's anti-bot layer blocked every request. Transient: retry later, usually minutes.
INFRA_ERROR	FAILED	$0.00	Token, network or parse failure with nothing delivered.
WATCHLIST_INVALID, SNAPSHOT_PARTIAL, KV_UNAVAILABLE, BILLING_LIMIT_REACHED	SUCCEEDED	delivered snapshots only	Price Monitoring Mode only; see that section above.

Probing this Actor is free. Every zero-delivery outcome above charges nothing, so an agent can validate its own call shape before committing budget.

Auditing your own spend

"economics": {
  "unitPrices":   { "search-item": 0.0045, "detail-item": 0.0027, "run-base-fee": 0.01 },
  "actualEvents": { "search-item": 20, "detail-item": 20, "run-base-fee": 1 },
  "expectedCharge": 0.154,
  "chargedUsdTotal": 0.154,
  "deliveredRows": 20,
  "totalEvents": 41,
  "rowsMatchRowEvents": true,
  "platformEvents": { "search-item": 20, "detail-item": 20, "run-base-fee": 1 },
  "platformCountsReconciled": true,
  "settled": true
}

expectedCharge is exactly Σ(actualEvents × unitPrices), platformEvents is the platform's own counter for the same run, and rowsMatchRowEvents / platformCountsReconciled turn the two comparisons a caller would otherwise have to script into booleans. settled: false marks a checkpoint written before settlement (a migration or an abort) — the numbers are so-far, not final. schemaVersion (semver, additive within a major) tells you which contract you are parsing; itemCount and chargedEvents are the same facts as flat keys.

The block above is a real 20-row run, taken on a subscription tier that pays 90% of list — which is why its unit prices read $0.0045 / $0.0027 instead of the $0.005 / $0.003 in the cost table. On the FREE tier the two agree.

---

🔧 Input configuration

Field	Type	Required	Default	Description
keyword	string	✅	—	English keyword, searched on 1688.com as typed; pet-supply terms are also mapped to Chinese search terms. Aliases keywords / searchKeywords / searchTerms / query / search / q are accepted, as a string or an array (see For AI agents above)
offerIds	string[]	—	—	Direct-fetch path: fetch these numeric IDs (e.g. 777995455975), bypassing keyword search. An array, a single value or a delimited string all work; IDs we cannot read as numeric are named in SUMMARY.invalidOfferIds and never billed. A detail request below 20 items auto-downgrades to card-only before browser/proxy work. includeDetails=false also delivers card rows through the mtop-primary transport. Price Monitoring is separate.
maxItems	integer	—	40 when omitted via API; Console prefill 20	1–200. The platform rejects a larger value with 400 invalid-input; inside the Actor it is clamped to 200 and disclosed as SUMMARY.maxItemsClamped. A requested detail batch below 20 is automatically card-only; see SUMMARY.deliveryShape. The 20-product full-detail Console starter costs $0.17 on the FREE tier.
includeDetails	boolean	—	true when omitted via API; Console prefill true	Requests enrichment. With maxItems < 20, effective mode is automatically card-only. false requests card-only directly and avoids detail-item charges, but card-only rows can lack MOQ, quantity-break ladders and weight.
targetMarket	enum	—	US	US / EU / UK — drives landed-cost duty and compliance rules
sort	enum	—	relevant	relevant / sales (most sold first) / price (low to high) — the delivered dataset arrives in that order
priceMin / priceMax	number	—	—	Approximate price range filter in CNY, anchored to the card's min (bulk/MOQ) price: passed to 1688's search and re-checked at delivery — cards whose min price is outside the range are dropped and never charged. Note: a card's price.max (one-piece / top-of-ladder price) may still exceed priceMax, since 1688 prices by quantity breaks
maxTotalChargeUsd	number	—	—	Additional hard billing ceiling. Effective cap is the lower of this and Apify's platform cap; 0 means no paid rows.
watchlistOfferIds	string[]	—	—	Price Monitoring Mode: up to 200 offer IDs to watch. Filling this switches the run from search to monitoring (takes priority over keyword). $0.015 per snapshotted offer per run. Any watchlist size works (1–200) — the DETAILS_MIN_20 minimum does not apply to monitoring mode
historyDays	integer	—	30	Monitoring curve window in days (1–400)
alertOnPriceDropPct	number	—	—	Fire a free priceDrop alert when price fell ≥ this % vs the previous snapshot
alertOnStockTightPct	number	—	—	Fire a free stockTight alert when the bookable amount shrank ≥ this % vs the previous snapshot
webhookUrl	string	—	—	POST the alert payload here when an alert fires (non-fatal, time-bounded)
includeTrendReport	boolean	—	false	Also deliver a weekly trendReport roll-up ($0.25)
proxyConfiguration	object	—	Residential (CN)	Defaults to Apify residential proxies; override only if you know why

Quick start input: use the search-first JSON in Quick start: 20 fully enriched products for $0.17 above. The Console Try form and Actor-level API example use phone case + 20 products + includeDetails: true. Existing API callers that omit maxItems / includeDetails retain the API defaults of 40 / true; per-event prices and those two API defaults are unchanged.

---

Reviews

Found a bug or have a wishlist? Open an Issue — a fixed bug helps you more than a one-star rating, and we answer fast.

If this run saved you sourcing hours, a quick review on the Store page helps other buyers find it — 30 seconds, hugely appreciated.