1688 SKU Normalizer and Price Change Detector

Turn authorized Chinese supplier exports into a clear SKU change report: what became more expensive, what went out of stock, what returned, and which records need checking before you act.

CatalogDelta is built for procurement and ecommerce teams who already receive 1688 or Chinese supplier CSV/XLSX files. Upload a current export, optionally add an earlier one, then open the readable report or download protected CSV results.

This is a file transformation tool, not a scraper. It does not fetch product URLs, log into marketplaces, or collect passwords, cookies or tokens.

Choose your workflow

Your goal	What to provide	Setting	What you get
Check a new export before producing SKU output	Current file; earlier file optional	Validate only	Readiness, errors and a custom-event cost preview; no SKU details
Clean a supplier catalogue	Current file	All valid current SKUs	Full normalized current-SKU results and protected CSV
Review changes between exports	Current and earlier files	Full export or Actionable rows only	Price/stock impact, prioritized report and action CSV
Repeat monitoring with less output	Two complete source exports	Actionable rows only, with optional price thresholds	Only selected current action rows are delivered and trigger the custom SKU event
Integrate with your own workflow	JSON snapshots	Paste JSON snapshots	The same normalized result contract

First run: upload → validate → review

1. Select Upload CSV or Excel and keep Auto-detect safely. For an unsupported supplier layout, choose Generic CSV/XLSX and map its columns.
2. Upload your current file and enter its actual observation time, including timezone.
3. If comparing changes, upload a strictly earlier export from the same workflow.
4. Enter the actual export currency when the file does not declare one. This is required for comparable prices in Shopify/TikTok-target exports; the Actor never guesses currency.
5. Confirm authorization and enable Validate only for your first unfamiliar file. Review readiness and errors before proceeding.
6. Disable validation, choose your delivery mode, and set an appropriate Apify spending limit. After the run, open Output → Open supplier change report (HTML). If the browser downloads it, open the downloaded file locally.

The report shows analysis coverage, delivered/suppressed counts, price and stock impact, data checks, cost preview and suggested follow-up. Its detail table contains up to 100 actually delivered action rows, with data-quality issues first. Use the protected action CSV for all delivered actions. Validation-only and rejected reports are aggregate-only.

When prices cannot be compared, the report explicitly says Price comparison unavailable and shows the current price or range plus the reason. It does not attach the current currency to an incompatible historical price or imply a currency conversion. Check the original snapshots to resolve the mismatch.

Pricing with worked examples

Current custom event: USD 0.003 per successfully delivered current SKU result — USD 3 per 1,000 results.

Example run	Analyzed current SKUs	Delivered current results	Custom SKU event subtotal
Full export	5,000	5,000	$15.00
Action-only; 20% meet the policy	5,000	1,000	$3.00
Action-only; nothing meets the policy	5,000	0	$0.00
Validate only	5,000	0	$0.00

These examples cover only the custom SKU event, not the total run bill. Any configured Actor-start event, platform resources, tax or exchange fees are separate; check the live Pricing tab and Apify billing. Validation does not mean the entire platform run is free.

Unchanged and threshold-suppressed current rows are still analyzed in action-only mode, but are not delivered or charged as custom SKU events. Rejected records and historical-only rows do not trigger this event. The default remains full export. No pricing changes are introduced in release 0.12.11.

What to do with the results

• Price increase: check the supplier quote, margin and order terms before buying.
• New stockout or restock: confirm availability before changing replenishment or listings.
• Non-comparable price or low-confidence identity: resolve the data issue first; do not treat an uncertain match as a reliable business change.
• First observation: review the new-to-this-snapshot SKU. It does not prove a new product launch.
• Historical SKU not observed: investigate coverage. It does not prove delisting.

For the next comparison, retain the complete original source export as the previous snapshot and provide a fresh full export as current. Do not use the action-only CSV as a baseline: it intentionally omits rows and is an output schema, not the original supplier format. CatalogDelta does not fetch fresh exports or persist a cross-run baseline automatically.

Inputs and supported formats

Input	Purpose
current_file / previous_file	Current CSV/XLSX and optional earlier export
current_observed_at / previous_observed_at	Actual timezone-aware ISO 8601 observation times
file_adapter	Strict auto-detection by default, exact preset, or explicit generic mapping
field_mapping	Column mapping when Generic CSV/XLSX is selected
file_currency	Actual three-letter currency when absent from the export
current_snapshot / previous_snapshot	JSON alternative; identifiers must be strings to preserve leading zeros
stale_after_days	Observation-age warning threshold; default 7
max_current_skus	Safety limit; maximum 10,000
delivery_mode	all_valid_current (default) or actionable_only
action_min_price_change_amount / action_min_price_change_percent	Optional non-negative decimal thresholds for price-only changes
validation_only	Aggregate checks without SKU-detail outputs or custom SKU events

Supported files: UTF-8 or GB18030 CSV, TSV, and unencrypted XLSX; maximum 15 MB, 200 columns and 10,000 SKU rows per file. Uploaded-file downloads accept Apify HTTPS storage, not arbitrary websites.

Strict header fingerprints recognize Gycharm 1688 normal, Shopify-target and TikTok-target exports, plus common generic layouts with product and SKU identity columns. Unknown or ambiguous layouts stop with corrective errors instead of guessing. Both snapshots must resolve to the same adapter. Explicit mappings must use valid column names; do not combine a custom mapping with auto-detection.

Three public real-format samples from the Gycharm export tool were tested: 151 + 79 + 79 rows. These are compatibility checks on those sample variants, not evidence of compatibility with every private supplier export or of affiliation with Gycharm, Shopify, TikTok or 1688.

Matching, comparison and action rules

1. Match by source, product ID and SKU ID. Without a SKU ID, a valid product ID plus non-empty normalized attributes can form a low-confidence fallback key.
2. Conflicting duplicate identities are rejected. Identical duplicates are deduplicated.
3. Compare single-value prices only when currency and price basis match. Decimal arithmetic is exact; no currency conversion is guessed.
4. Missing prices, range prices, currency mismatches and price-basis mismatches remain not_comparable.
5. Action rows include price/stock changes, newly observed SKUs and non-comparable rows. Historical-only and unchanged rows are excluded.
6. Thresholds affect price-only action rows. If both amount and percentage are configured, meeting either available threshold keeps the row. Stock changes, first observations and non-comparable rows stay actionable; an unavailable sole metric stays for review.

Amount thresholds are evaluated in each row's own currency. Prices across currencies are never added into a claimed saving.

Output contract

Output	Contents
RUN_REPORT	Static HTML decision brief; at most 100 delivered action rows; no scripts, tracking or external assets
Default dataset	Delivered normalized current results; full export or selected action rows according to delivery mode
SAFE_CURRENT_RESULTS_CSV	All delivered current rows, 26 fields, UTF-8 BOM and formula-like text protection
SAFE_ACTIONABLE_RESULTS_CSV	Delivered action rows with the same protected CSV format
unbilled_context dataset / SAFE_HISTORICAL_CONTEXT_CSV	Historical-only records not observed in current; no custom SKU event
RUN_SUMMARY	Resolved adapter, aggregate readiness/impact, coverage, cost preview, artifact status and billing counts
ERRORS	Stable error codes and source-array locations, not full source records

Each detail row includes original/normalized attributes, observation times, previous/current price and stock, exact deltas, matching confidence, quality flags, comparison reason and source location.

CSV artifacts exist only when corresponding rows were delivered. Validation-only and rejected runs create no SKU-detail dataset or CSV. Reports and summaries explicitly distinguish analyzed candidates, selected candidates, suppressed rows, actual writes and runtime-recorded events. Owner test events do not establish customer charges or creator revenue.

The custom-event cost preview uses the live runtime price when available, otherwise reports it unavailable. It is not a bill. If a spending or processing cap stops delivery, the summary reports partial coverage; do not read a partial run as “nothing changed.” The dataset remains authoritative if a convenience report or CSV write fails.

Apify's own CSV/Excel conversions are separate from CatalogDelta's formula protection. For untrusted supplier text, choose the CatalogDelta-generated protected CSV or JSON.

Examples and troubleshooting

Try these synthetic examples; their fixed observation dates may trigger stale-data warnings. Real inputs must use actual observation times.

• 1688 SKU normalization
• Two-snapshot price comparison
• Stock change detection

No changes found? Check that you supplied an earlier full export, both files cover the same source, times are ordered correctly, and thresholds are appropriate. Confirm readiness and complete coverage before interpreting zero actions.

File rejected? Use the generic mapping for an unknown layout. Check string identifiers, required headers, file limits and the error codes. Fix currency or price basis before expecting a comparable delta.

Need help with a format? Open an issue describing the headers, error code and intended workflow. Share a small synthetic or redacted example only if you are authorized. Never post private supplier files, credentials or signed storage links publicly.

Data responsibility and release status

Process only authorized product data. Exclude people, orders, payment/account details and unrelated free text. Reports and CSVs can contain supplier data: protect them and apply the same retention/deletion rules as the run datasets. You control your Apify input/output storage access and must delete it when no longer needed; platform infrastructure does not replace your authorization obligations.

Release 0.12.12 makes incompatible-price reports explicit while preserving the readable report, correct quiet-run statistics, dataset fields and delivery defaults. Strict TypeScript compilation and 87 automated tests pass locally. These are technical checks, not a guarantee of private-format compatibility, accuracy on unseen data, market demand or revenue. Build history is in the Changelog.