1688 Authorized Offer Comparison — price, MOQ, stock, and supplier change evidence

Compare buyer-owned, merchant-authorized, or licensed 1688 exports without login, scraping, URL fetching, or independent verification. The Actor compares closed snapshots, highlights changes, assigns review, and reconciles each delivered authorized 1688 offer comparison row with current-run KVS OUTPUT.

Legacy productUrls remains accepted and now produces one free migration diagnostic with zero source requests. Comparison rows require authorized records in offers.

What you get

Each unique accepted offerId becomes one authorized 1688 offer comparison row in the default Dataset. The row preserves the original monitor's familiar fields—watchName, source, targetId, targetUrl, found, changeType, changedFields, previous, current, evidenceUrl, partial, partialReason, error, checkedAt, and isDemo—and adds the evidence, decision, source-rights, failure, stable-identity, and settlement context needed for a reviewable commercial workflow.

You receive:

• deterministic comparison of normalized previous and current offer snapshots;
• baseline_created, changed, or no_change status, never an invented change;
• a sorted list of top-level snapshot fields whose normalized values differ;
• stable 1688-offer:<offerId> entity identity and SHA-256 record identity;
• buyer-supplied price range, currency, price tiers, MOQ, stock, unit, supplier fields, badges, and promotions;
• optional recorded detail.1688.com offer URL that is never fetched;
• optional source retrieval time with explicit freshness status and age;
• source label and rights statement carried into every comparison row;
• confidence based on evidence completeness, not on supplier quality or commercial attractiveness;
• explicit gaps, a recommended human-review action, review priority, and safeToAutomate:false;
• settlement-neutral billing intent in the Dataset row;
• authoritative delivered/paid/free/unknown settlement in the exact run's KVS OUTPUT;
• free diagnostics for legacy URLs and malformed runtime-received records;
• exact work, result, delivery, settlement, stop, terminal, KVS-write, exit, and replay counts/state;
• a hard runtime claim that the current product mode made zero source network requests and used no 1688 login.

The Actor does not fetch or verify records, identities, rights, factories, products, certifications, availability, commercial terms, demand, margin, or suitability for purchase. It does not decide whether to buy, reorder, negotiate, delist, approve, or reject an offer.

The output is designed to support a human review queue. A downstream system may safely automate storage, digest matching, routing, and ticket creation. It must not automate a supplier or purchasing decision from this evidence alone.

Who uses it

The Actor is for buyers and operators who already possess 1688 offer data they have a lawful and contractual right to process and deliver. Typical users include sourcing teams, merchant-authorized agencies, procurement operations, catalog QA teams, wholesale data integration teams, supplier portfolio analysts, internal commerce tooling teams, and implementation partners working from buyer-controlled exports.

Useful workflows include:

• comparing two exports from an authorized merchant or licensed integration;
• preparing a price/MOQ/stock change queue before a sourcing review meeting;
• recording a first reviewed snapshot as a baseline candidate;
• deduplicating repeated offer identities across export fragments;
• routing changed offers to a procurement ticket while leaving the final decision to a person;
• reconciling the Dataset length with named item-checked events for one exact Apify run;
• migrating an old URL-based Task without silently contacting 1688.

Do not use it to scrape 1688, bypass controls, copy unrelated catalogs, harvest contacts, republish without permission, infer confidential terms, or automate procurement. Never submit credentials, signed links, payment/contact data, or unnecessary confidential material.

The authorization sentence is a buyer attestation, not a legal opinion or independent rights check. Source metadata improves traceability; it does not make unauthorized data authorized.

中文说明

仅处理买方自有、商家授权或其他合法许可的 1688 导出。Actor 不登录、不抓取、不调用 1688 API，也不打开链接。授权、身份、价格、库存和采购适用性均未独立核验；所有结果必须人工复核。请勿提交密码、Cookie、签名链接、联系人或付款数据。

How to run

1. Obtain an export from a buyer-owned source, a merchant-authorized workflow, a licensed 1688 integration, or another wholesale source whose terms permit your processing and downstream delivery.
2. Remove secrets, signed query strings, authentication material, personal contact data, private negotiation notes, customer data, and fields that are not part of the closed contract.
3. Choose a stable watchName. It labels the review scope but does not create an Actor-managed baseline.
4. For every offer, provide a numeric-string offerId, a required current canonical snapshot, and an optional previous canonical snapshot.
5. Use previous:null for the first comparison. The row will be baseline_created; save a reviewed snapshot in your own system if you want to compare it later.
6. Provide a traceable sourceName and a concise sourceLicense statement. Do not state rights you do not possess.
7. Optionally provide sourceRetrievedAt as a real UTC timestamp and an exact clean https://detail.1688.com/offer/<offerId>.html reference. The URL is recorded only.
8. Select the exact authorization sentence in the Input UI.
9. Start with one record and a maximum total charge that covers the automatic start event plus one item-checked row.
10. Wait for the exact run to finish. Read KVS key OUTPUT and require OUTPUT.runId to equal the platform run ID.
11. Reconcile Dataset length, run.deliveredRowCount, run.paidRowCount, run.freeRowCount, unknown counts, and the named counter before/after values.
12. If any push is unknown or settlement cannot be proved, do not rerun blindly. Investigate the original Dataset, KVS, and platform charged-event counters.
13. Route comparison rows to a human reviewer. The Actor always sets safeToAutomate:false.

Minimal accepted input:

{
  "schemaVersion": "2.0",
  "authorization": "I confirm I am authorized to process and deliver these 1688 offer records",
  "sourceContext": "buyer_owned_1688_export",
  "watchName": "usb-c-supplier-review",
  "offers": [
    {
      "offerId": "1000406623486",
      "offerUrl": "https://detail.1688.com/offer/1000406623486.html",
      "previous": null,
      "current": {
        "offerId": "1000406623486",
        "title": "USB-C cable wholesale pack",
        "priceMin": 3.6,
        "priceMax": 4.4,
        "currency": "CNY",
        "priceTiers": [
          {"beginAmount": 100, "price": 4.4},
          {"beginAmount": 500, "price": 3.6}
        ],
        "moq": 100,
        "stock": 15000,
        "unit": "piece",
        "supplier": {
          "id": "supplier-88",
          "name": "Example Authorized Supplier",
          "loginId": "seller88"
        },
        "badges": ["verified-export"],
        "promotions": []
      },
      "sourceName": "Buyer-owned 1688 export",
      "sourceLicense": "Buyer confirms authorization to process and deliver this export.",
      "sourceRetrievedAt": "2026-08-13T00:00:00Z"
    }
  ]
}

The checked-in examples/input.json compares two synthetic snapshots and produces a changed result. The example supplier label and terms are documentation fixtures, not a real supplier, customer, licence, product, transaction, or performance claim.

Pricing

The primary pricing noun is one authorized 1688 offer comparison row. The Actor uses pay per event. A run can incur the automatic apify-actor-start event. Each confirmed linked delivery of one unique accepted comparison can incur one item-checked event.

Tier	Actor start	One authorized 1688 offer comparison row
FREE	$0.00500	$0.00600
BRONZE	$0.00475	$0.00570
SILVER	$0.00450	$0.00540
GOLD	$0.00425	$0.00510
PLATINUM	$0.00410	$0.00492
DIAMOND	$0.00400	$0.00480

At FREE-tier event prices, one confirmed comparison plus the automatic start event is $0.011 before compute and storage. Ten confirmed comparisons plus start are $0.065. At DIAMOND event prices, one confirmed comparison plus start is $0.0088 and ten confirmed comparisons plus start are $0.052. The live Apify pricing panel is authoritative for the buyer's current tier and any future approved pricing change.

Legacy migration diagnostics, malformed-record diagnostics, duplicate identities, and records withheld before a push do not intentionally emit item-checked. When the platform cannot charge a linked comparison at the cap, SDK 3.7.x returns aggregate zero and withholds the Dataset item; the Actor never labels it as a delivered free comparison. A thrown push is unknown Dataset delivery. A returned push followed by an unreadable or contradictory counter is reconciled from the named counter and aggregate receipt as known or unknown Dataset delivery with unknown settlement. Neither uncertain state is automatically retried.

Before the first paid delivery, the runtime requires all of the following:

• a valid current hosted Apify run ID;
• exact pay-per-event mode;
• exactly two numeric pricing events: apify-actor-start and item-checked;
• one of the six approved tier pairs above;
• no default Dataset billing event and no unrecognized extra event;
• a readable maximum total charge and current charged amount;
• current spend that already includes at least the exact tier start event;
• an initial named item-checked counter of zero;
• enough remaining cap for the next comparison row.

For each comparison, the runtime reads item-checked before the push and requires it to equal the number of already confirmed paid rows. It performs one linked Dataset push, reads the same named counter again, and requires an exact +1 delta plus the SDK's exact two-event aggregate receipt for one named row and its Dataset write. It never uses aggregate chargedCount > 0 alone as proof of the named comparison unit. eventChargeLimitReached=true can truthfully accompany the final paid row: it means another unit no longer fits, not that the current row was free.

The budget check uses integer micro-dollar arithmetic for finite caps. Unlimited platform caps are accepted only as the literal positive Infinity returned by the SDK. A budget stop happens before the next push and records the remaining accepted records as withheld. It is not a source error and does not change already delivered comparisons.

Input contract

The public contract is closed at the top level and inside each offer and snapshot. Unknown properties are rejected. Runtime validation remains authoritative for cross-field relations that ordinary JSON Schema cannot express, including repeated offerId equality, priceMin <= priceMax, tier prices inside the declared range, and duplicate identity selection.

The checked-in Dataset and OUTPUT JSON Schemas are the structural stage. Acceptance additionally requires the exported validateRow and validateOutput semantic validators; those functions reconstruct canonical decision, evidence, source, work, settlement, replay, and terminal relations that a portable structural schema cannot express exactly.

Top-level fields:

Field	Required	Boundary
schemaVersion	No	When present, exactly 2.0.
authorization	With offers	Exact sentence shown in the Input UI. Buyer attestation only.
sourceContext	With offers	One of four closed authorized-export categories. It must be selected explicitly and is not inferred by runtime.
watchName	Yes	1–80 trimmed characters, no C0/C1 controls. Returned in every row and OUTPUT.
offers	Modern path	1–50 closed offer objects. Cannot be combined with productUrls.
productUrls	Legacy path	1–50 nonblank strings. Free migration diagnostic only; never fetched.
maxChanges	No	Integer 1–50, default 20. Stops before delivering an additional changed row after the limit.
proxyConfiguration	Legacy only	Accepted and ignored. No proxy or direct network request is made.

Offer fields:

Field	Required	Boundary
offerId	Yes	Numeric string, 1–80 digits. It must match current.offerId, previous.offerId, and any recorded URL path.
offerUrl	No	Null or exact clean https://detail.1688.com/offer/<offerId>.html, maximum 500 characters. Recorded, never fetched.
previous	No	Null or canonical snapshot. Null produces baseline_created.
current	Yes	Canonical snapshot for the comparison.
sourceName	Yes	1–200 characters identifying the authorized export or licensed integration.
sourceLicense	Yes	1–700 characters describing the buyer's processing and downstream delivery basis. Recorded, not verified.
sourceRetrievedAt	No	Null or a real UTC ISO timestamp up to 40 characters.

Snapshot fields:

Field	Required	Boundary
offerId	Yes	Same numeric identity as the parent offer.
title	Yes	1–500 trimmed characters without C0/C1 controls.
priceMin	Yes	Finite number from 0 through 1,000,000,000. Must not exceed priceMax.
priceMax	Yes	Finite number from 0 through 1,000,000,000.
currency	Yes	Three ASCII letters, normalized uppercase. No conversion occurs.
priceTiers	No	0–50 closed {beginAmount, price} objects. Sorted and duplicate tiers removed. Each price must be inside the snapshot range.
moq	No	Null or finite number from 0 through 1,000,000,000.
stock	No	Null or finite number from 0 through 1,000,000,000,000.
unit	No	Null or 1–120 trimmed characters.
supplier	Yes	Closed object with required id and name, optional loginId. These are supplied facts, not verified identity.
badges	No	0–30 unique nonblank strings, each up to 240 characters.
promotions	No	0–30 unique nonblank strings, each up to 500 characters.

The runtime normalizes text, currency, tiers, string lists, timestamps, and clean offer URLs. Duplicate accepted offers use the first valid occurrence of the same offerId; later duplicates are counted and not delivered or charged. Malformed objects are counted invalid. If at least one valid record remains, the valid rows can continue and one free diagnostic can disclose the rejected count.

The Actor intentionally does not store a persistent baseline. The buyer supplies previous and current in the same run. This removes cross-run state races and keeps source history under the buyer's control. If you need scheduled monitoring, save the reviewed current snapshot in your own database and supply it as previous in the next intentional run.

Happy, partial, and failure output

The following examples are deterministic local fixtures. They are not claims about a live canary, customer, or current production run. A final Store acceptance receipt must replace local identifiers with the exact immutable build, run, Dataset, KVS, pricing, and browser evidence.

Happy local fixture:

{
  "buildId": "local-contract-fixture-v2",
  "runId": "local-test-1688-offer-run",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "dataset": {
    "recordType": "china_1688_supplier_monitor",
    "entityId": "1688-offer:1000406623486",
    "changeType": "changed",
    "changedFields": ["priceMax", "priceMin", "priceTiers", "promotions", "stock"],
    "safeToAutomate": false,
    "recommendedAction": "REVIEW_OFFER_CHANGE",
    "billing": {
      "billingEligible": true,
      "billingIntent": "linked_push_item_checked",
      "eventName": "item-checked",
      "settlementSource": "current_run_kvs_output"
    }
  },
  "output": {
    "kind": "authorized_1688_offer_comparison_output",
    "status": "COMPLETE",
    "runId": "local-test-1688-offer-run",
    "watchName": "usb-c-supplier-review",
    "input": {"requestedCount":1,"uniqueCount":1,"duplicateCount":0,"invalidCount":0,"legacyInputCount":0},
    "run": {"attemptedCount":1,"successfulCount":1,"failedCount":0,"deliveredRowCount":1,"paidRowCount":1,"freeRowCount":0,"withheldRowCount":0,"unknownDeliveryCount":0,"unknownSettlementCount":0,"baselineCreatedCount":0,"changedCount":1,"noChangeCount":0,"partial":false,"budgetStopped":false,"changeLimitStopped":false,"fatalError":null,"replaySafe":false,"safeToAutomate":false},
    "delivery": {"eventName":"item-checked","attemptedPushCount":1,"resultChargeCountBefore":0,"resultChargeCountAfter":1,"confirmedEventDelta":1,"confirmedDatasetWrites":1,"lastAttempt":{"stableId":"sha256:73d2d0448d54c7d1e6e9ea73f6774d6d0bcd116bf151ea7247bc7779daa41dd0","state":"confirmed_paid","resultChargeCountBefore":0,"resultChargeCountAfter":1,"delta":1,"aggregateChargedCount":2,"eventChargeLimitReached":false}},
    "source": {"mode":"buyer_authorized_export_only","networkRequestsMade":0,"platformLoginUsed":false,"sourceContext":"buyer_owned_1688_export"},
    "terminal": {"outcome":"COMPLETE","failureStage":null,"primaryKvsWrite":"confirmed","recoveryKvsWrite":"not_attempted","exit":"requested"}
  }
}

Legacy migration fixture:

{
  "buildId": "local-contract-fixture-v2",
  "runId": "local-test-1688-legacy-run",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "dataset": {
    "recordType": "run_advisory",
    "failureType": "legacy_product_urls",
    "found": false,
    "partial": true,
    "recommendedAction": "MIGRATE_TO_AUTHORIZED_EXPORT",
    "billing": {"billingEligible":false,"billingIntent":"free_diagnostic_dataset_write","eventName":null,"settlementSource":"current_run_kvs_output"}
  },
  "output": {
    "status": "PARTIAL",
    "runId": "local-test-1688-legacy-run",
    "input": {"requestedCount":0,"uniqueCount":0,"duplicateCount":0,"invalidCount":0,"legacyInputCount":1},
    "run": {"attemptedCount":0,"successfulCount":0,"failedCount":0,"deliveredRowCount":1,"paidRowCount":0,"freeRowCount":1,"withheldRowCount":0,"unknownDeliveryCount":0,"unknownSettlementCount":0,"baselineCreatedCount":0,"changedCount":0,"noChangeCount":0,"partial":true,"budgetStopped":false,"changeLimitStopped":false,"fatalError":null,"replaySafe":false,"safeToAutomate":false},
    "delivery": {"eventName":"item-checked","attemptedPushCount":1,"resultChargeCountBefore":0,"resultChargeCountAfter":0,"confirmedEventDelta":0,"confirmedDatasetWrites":1,"lastAttempt":{"stableId":"sha256:b49c9253a83835df29b82c57292ef5f11240314508f8ca0006b312f37022c2f4","state":"confirmed_free_diagnostic","resultChargeCountBefore":null,"resultChargeCountAfter":null,"delta":null,"aggregateChargedCount":null,"eventChargeLimitReached":null}},
    "source": {"mode":"legacy_migration_diagnostic_only","networkRequestsMade":0,"platformLoginUsed":false,"sourceContext":null},
    "terminal": {"outcome":"PARTIAL","failureStage":null,"primaryKvsWrite":"confirmed","recoveryKvsWrite":"not_attempted","exit":"requested"}
  }
}

Terminal states and operational meaning:

State	Meaning	Required response
COMPLETE	All unique valid offers were confirmed delivered and paid.	Reconcile the exact run and send rows to human review.
PARTIAL	A free diagnostic, invalid record, budget/change limit, or confirmed-free row occurred without fatal failure.	Read counts and withheld work before deciding on another intentional run.
FAILED before a push	Input, current run/Dataset identity, pricing, pre-push counter, KVS, or exit failure prevented safe completion.	Correct the named cause; do not assume a comparison was delivered.
unknown_delivery	The linked push threw. Dataset delivery and settlement are unknown.	Never blind-retry; reconcile the original run.
settlement_unknown	Push returned, so Dataset delivery is known, but named settlement could not be proved.	Never blind-retry; reconcile Dataset and charged-event counters.
settlement_anomaly	Named and aggregate settlement facts contradict the allowed paid/withheld lattice.	Stop automation and investigate the exact run.
confirmed_withheld	The linked call returned chargedCount=0, the named counter stayed flat, and the SDK withheld the Dataset item at the charge limit.	No row was delivered or charged; stop before remaining records.
output_write_failed	Primary current-run KVS write failed; one bounded recovery write was attempted.	Use platform run status and preserved recovery evidence; no automatic rerun.
exit_failed	Primary OUTPUT was written but the platform exit request failed.	Treat run as failed and inspect the current KVS receipt.

replaySafe is true only when no Dataset push was attempted. After any paid, free, or unknown push attempt, it is false. A new run always incurs a separate start event and can deliver and charge the same comparison again. The Actor does not provide cross-run idempotency.

Field dictionary

Legacy-compatible row fields:

Field	Meaning and boundary
watchName	Buyer-defined comparison label. It does not identify an Actor-managed persistent baseline.
source	Constant 1688; describes the supplied offer format, not a source request.
targetId	Numeric-string offer ID for a comparison; empty on a diagnostic.
targetUrl	Clean recorded detail.1688.com offer URL or empty string. Never fetched.
found	True for a valid comparison candidate, false for a free diagnostic. It does not mean externally verified.
changeType	baseline_created, changed, no_change, or error.
changedFields	Sorted top-level canonical snapshot field names whose normalized values differ.
previous	Buyer-supplied previous canonical snapshot or null.
current	Buyer-supplied current canonical snapshot or null on diagnostics.
evidenceUrl	Same recorded URL as targetUrl; preserved for compatibility, not fetched evidence.
partial	True only on diagnostic/advisory rows. Run-level partial truth lives in OUTPUT.
partialReason	Closed diagnostic reason or empty string.
error	Bounded diagnostic summary or empty string.
checkedAt	Current UTC processing timestamp; no remote check occurred.
isDemo	Always false. Documentation fixtures are not emitted as live demo rows.

Decision and evidence fields:

Field	Meaning and boundary
schemaVersion / contractVersion	Preserved Dataset envelope 1.0.0; additive decision contract 2.0.0.
recordType / intelligenceType	Comparison versus diagnostic classification.
stableId / entityId	Fixed-source SHA-256 identity and readable 1688-offer:<offerId> identity.
observedAt / firstSeenAt / lastSeenAt	This run's UTC processing time; there is no cross-run state.
freshness	Fresh/recent/older/unknown, age, basis, and observation time derived only from supplied retrieval time.
change	Comparison status, deterministic basis, and changed top-level fields.
confidence / confidenceScore / confidenceBand	Evidence completeness and gaps, never supplier or commercial confidence.
evidence / dataGaps	Digests of supplied evidence and explicit unverified boundaries.
recommendedAction / priority	Human-review route based on comparison and supplied freshness.
safeToAutomate / summary	Always false plus a bounded evidence summary, not a purchasing recommendation.
failureDiagnostics / failureType / retryable	Null for comparisons; closed non-retry diagnostic facts for advisories.
billing	Pre-settlement eligibility and intent; same-run OUTPUT is settlement authority.
sourceContext / sourceName / sourceLicense / sourceRetrievedAt	Buyer-supplied provenance, rights statement, and optional export time; not verified.
requestDigest / inputDigest	Digests of the normalized request and individual offer record.

KVS OUTPUT fields:

Group	What it proves
runId / requestDigest	Exact hosted run and normalized request binding.
input.*	Requested, unique, duplicate, invalid, and legacy partition.
run.attemptedCount / successfulCount / failedCount	Paid-work partition.
run.deliveredRowCount / paidRowCount / freeRowCount / withheldRowCount	Delivery, settlement, and unpushed work.
run.unknownDeliveryCount / unknownSettlementCount	Unknown delivery or settlement.
run.baselineCreatedCount / changedCount / noChangeCount	Successful comparison categories.
run.partial / budgetStopped / changeLimitStopped / fatalError / replaySafe	Incompleteness, stop, failure, and replay state.
delivery.*	Named event, attempts, counters, exact confirmed delta, known writes, and final attempt facts.
source.*	Zero-network/no-login mode and context; diagnostic modes carry null context.
terminal.*	Outcome, failure stage, primary/recovery KVS writes, and exit request.

Evidence and boundaries

Evidence in this Actor is deliberately narrow. It proves what the runtime saw in the buyer's normalized input, what comparison it computed, what digests bind those records, and what the platform reported about the current run's Dataset and named billing event. It does not prove external reality.

The evidence chain is:

1. normalize a closed buyer-supplied record;
2. require matching numeric offer identity across parent and snapshots;
3. calculate an inputDigest for the normalized record;
4. deduplicate by offerId, first valid record wins;
5. calculate a request digest after defaults and deduplication;
6. compare normalized top-level snapshot fields deterministically;
7. build a settlement-neutral Dataset row with evidence digests and explicit gaps;
8. validate the exact row shape and decision lattice;
9. prove budget and named counter state before delivery;
10. perform one linked Dataset push with item-checked;
11. prove exact named counter +1, known free delivery, or an explicit unknown/anomalous state;
12. write and validate current-run KVS OUTPUT;
13. request terminal platform exit, with one bounded recovery receipt if KVS or exit handling fails.

The Actor makes no source request. targetUrl and evidenceUrl are recorded references only. An HTTPS URL is not proof that a page exists, belongs to the stated supplier, is canonical, is safe, is public, is licensed, or contains the submitted data. The runtime accepts only the exact clean 1688 detail URL shape to avoid storing arbitrary URL forms; it still does not open or verify it.

Freshness is based only on sourceRetrievedAt. When absent, freshness is unknown. A future timestamp is also unknown. A recent timestamp proves only when the buyer says the export was retrieved, not when 1688, a merchant, or a supplier last changed the offer.

Confidence is evidence completeness. It decreases for missing offer URL, missing retrieval time, and the fixed unverified boundaries. A higher score does not mean the supplier is trustworthy, the offer is genuine, the stock exists, the price is available, the licence is valid, the product is compliant, or the purchase is advisable.

SHA-256 digests support equality and tamper comparison. They are not encryption, anonymization, permission, authenticity, non-repudiation, or proof that the input was true. Do not put personal data or secrets in a field merely because the output also contains a digest.

Decision routing

Every comparison is evidence for a person, not an automated verdict.

Comparison	Priority	Recommended action	Meaning
changed	HIGH	REVIEW_OFFER_CHANGE	At least one normalized supplied field differs. Review the actual changes and source rights.
baseline_created	MEDIUM, or LOW if older	SAVE_REVIEWED_BASELINE	No previous snapshot was supplied. Save only after human review.
no_change	MEDIUM, or LOW if older	RETAIN_CURRENT_REVIEW_STATE	Supplied canonical fields match. This does not prove external continuity.
legacy diagnostic	HIGH	MIGRATE_TO_AUTHORIZED_EXPORT	Old URL input was intentionally not fetched.
invalid diagnostic	HIGH	REVIEW_INPUT_RECORDS	One or more runtime-received objects failed the closed contract.

Automation that is appropriate:

• store the row and OUTPUT receipt;
• compare digests for duplicate processing;
• route HIGH-priority changes to a review queue;
• create a ticket containing the stable identity and changed field names;
• attach the recorded source and rights statement;
• block downstream automation when safeToAutomate:false;
• preserve the exact run ID and settlement state;
• notify an operator that a manual decision is required.

Automation that is not appropriate from this output alone:

• order inventory;
• change a selling price;
• approve or reject a supplier;
• publish or delist a product;
• negotiate or send a supplier message;
• assert a licence or brand right;
• calculate reliable landed margin;
• treat stock or price as verified current truth;
• profile seller staff or collect contact data;
• retry an unknown delivery.

If your organization needs automated purchasing or repricing, combine this evidence with an independently authorized live source, verified supplier and product controls, contractual rules, inventory and finance systems, explicit approval thresholds, and a separate human-approved automation policy. This Actor intentionally does not provide those controls.

Commercial playbooks

Authorized export comparison

Compare two authorized exports, route changed rows to review, and store the exact KVS OUTPUT beside the imported batch.

First baseline intake

Submit previous:null. Save the resulting baseline_created snapshot only after a reviewer checks identity, rights, currency, price, MOQ, and variants.

Supplier portfolio review

Use one stable watchName, submit at most 50 records, and sort review by priority, changedFields, and freshness. The batch is not proof of portfolio completeness.

Migration from the old URL Task

Legacy productUrls creates one free migration diagnostic and no network work. Replace it with authorized offers; repeated legacy runs do not monitor anything.

Change-budget review

Use maxChanges to bound changed rows, not total rows. Read changeLimitStopped and withheldRowCount before starting another intentional run.

Evidence quality improvement

Supply a clean recorded URL when permitted, real retrieval time, precise source label, and truthful rights statement. Never invent fields to raise completeness.

Exception handling

For unknown_delivery, settlement_unknown, or settlement_anomaly, freeze retry and preserve run, Dataset, KVS, counters, logs, digests, and the operator's classification.

Integration recipes

Apify API

Submit JSON with your Apify token kept outside input. Set a bounded charge cap, poll the created run, then fetch Dataset and OUTPUT. Reject a mismatched OUTPUT.runId.

Scheduled Task

A schedule is useful only when an authorized upstream system refreshes current. The orchestrator obtains the export, loads the last reviewed snapshot, starts one bounded run, verifies OUTPUT, routes review, and saves only approved current snapshots. Static scheduled input can repeatedly charge identical rows.

Webhook

Queue the run ID from a run-finished webhook. Fetch OUTPUT, verify identity/terminal/counts, and make the consumer idempotent by run ID.

MCP or agent workflow

An MCP client may submit records already present in its authorized workspace. It must not invent authorization, browse 1688, or decide a purchase; require citations to identity, changes, gaps, and safeToAutomate:false.

Database upsert

Use entityId as the offer key and (runId,inputDigest) as the attempt key. Append observations; do not overwrite reviewed history.

Ticketing and CRM

Create review tickets only after OUTPUT confirms delivery. Use entity/run as the key, summary as title, priority, changedFields, source context, gaps, freshness, and the KVS receipt. Do not copy supplier contacts.

Operating guide

Start with one synthetic or non-sensitive authorized fixture. Confirm Input prevalidation, Dataset projection, and OUTPUT before increasing batch size. Keep the same normalized record rules in the upstream exporter so comparisons do not report formatting-only changes.

Before each run, confirm source and downstream rights, remove personal data and secrets, keep offer IDs/currency/units stable, use UTC retrieval times, load only a reviewed previous snapshot, and set a bounded charge cap. Afterward, require the exact run ID, zero network requests, exact Dataset and paid/free/unknown partitions, and human review.

For COMPLETE, Dataset length must equal known writes; paid + free + unknown settlement must equal delivered rows; event delta must equal paid rows; successful change categories must equal successful work. For PARTIAL, inspect diagnostics, invalid, stop, and withheld counts. For FAILED, inspect the sole error, failure stage, terminal writes, and replay state. Never infer that a failed operation was not delivered.

The runtime validates OUTPUT before writing it. A failed primary write gets one bounded output_write_failed recovery attempt. A failed platform exit gets one exit_failed recovery write. No paid work continues after either condition.

Retain input and receipts only for the stated purpose and policy period. Restrict access, avoid personal data, provide correction/deletion routes, and do not reuse records for outreach or profiling. Alert on failed/unknown/anomalous settlement, KVS recovery, unexpected pricing, excessive diagnostics or duplicates, and stale/unknown freshness. Zero source requests proves only runtime behavior—not upstream authorization or accuracy.

FAQ

Does this Actor scrape 1688?

No. Version 0.2 makes zero source requests. It does not log in, use a proxy, call an API, open an offer URL, download HTML, or render a page. It processes only the JSON records supplied in the run input.

Why keep the 1688 name, and can I submit public URLs?

The closed shape targets authorized 1688 exports and preserves legacy fields. Public accessibility is not a commercial licence; URL-only input produces a free migration diagnostic and is never fetched. The authorization sentence records your attestation but does not prove permission.

Where does previous come from, and what does null mean?

Use your own reviewed authorized history. Null produces baseline_created, a review candidate—not proof that an offer is new.

What exactly is compared?

The Actor compares normalized offer ID, title, prices, currency, tiers, MOQ, stock, unit, supplier, badges, and promotions. Tiers are sorted; other lists preserve first-occurrence order. no_change means only that supplied normalized records match.

Is confidence a supplier rating or purchasing approval?

No. It measures evidence completeness only. Every row is safeToAutomate:false; the Actor cannot verify or approve a supplier, product, licence, price, stock, or purchase.

Why does the Dataset row say billing eligible rather than paid?

The Dataset row states pre-settlement eligibility and intent. Current-run OUTPUT classifies paid, free, anomalous, or unknown. The first valid duplicate wins; malformed records can produce one free diagnostic. maxChanges limits changed rows, not total rows.

Can I retry a failed run?

Only after classifying the original run. Never blind-retry unknown or anomalous delivery. Dataset alone is insufficient: require same-run OUTPUT and reconcile counters. Every new run has a new start event.

What data should never be submitted?

Never submit credentials, cookies, tokens, private links, contacts, payment data, or unnecessary confidential fields. SHA-256 is not anonymization. Control Apify retention, deletion, and downstream copies.

Can an authorized API feed this Actor?

Yes. Your own licensed integration may convert its response into this closed shape and select licensed_1688_integration; this Actor still makes no API request.

Sources and rights

This release deliberately replaces the previous public-page retrieval mode. The prior code contacted detail.1688.com and m.1688.com, parsed offer content, stored baselines, and resold a per-check output. That mode lacked preserved written permission for automated commercial retrieval and downstream redistribution, so it is not part of version 0.2.

The relevant official source policies identified during the release audit include:

• 1688 Terms of Use, effective 26 August 2025: https://terms.alicdn.com/legal-agreement/terms/common_platform_service/20240913201059451/20240913201059451.html
• 1688 Legal Notice: https://terms.alicdn.com/legal-agreement/terms/b_platform_service_agreement/20230919145316133/20230919145316133.html

Those documents were used to set a conservative product boundary. This README does not reproduce their full text and is not legal advice. Buyers should review the current terms, their own agreement, the rights of merchants/suppliers and other rightsholders, and applicable law before processing or delivering records.

Version 0.2 accepts four source contexts:

• buyer_owned_1688_export: the buyer controls the export and has the required rights;
• merchant_authorized_1688_export: a merchant has authorized the buyer's processing and delivery;
• licensed_1688_integration: an integration licence covers the records and intended downstream use;
• other_licensed_wholesale_export: another documented licence covers compatible 1688 offer records.

Selecting a context and entering the authorization sentence do not create permission. Preserve the actual contract, licence scope, permitted fields, attribution, retention duties, and termination date outside the Actor. Put only a concise non-secret statement in sourceLicense.

Product titles, supplier labels, badges, promotions, and other offer fields may be protected by contract, copyright, database rights, trademark, confidentiality, privacy, or other rules. Submit only the minimum fields required for review. Do not submit images, free-form descriptions, seller contacts, or personal profiles.

The buyer acts as the party choosing the purpose, source, records, and downstream recipients. The buyer must provide any required notices, lawful basis, access controls, correction route, retention/deletion policy, data-subject process, merchant/supplier process, and internal approval policy. Apify and the Actor runtime provide processing infrastructure; they do not verify your rights.

The operational promise is closed validation, deterministic comparison, zero source requests, exact run reconciliation, bounded recovery, and human review. It does not promise external coverage, accuracy, availability, or permission.