1688 SKU Normalizer and Price Change Detector

CatalogDelta imports authorized Chinese supplier CSV/XLSX files, standardizes SKU records, and compares an optional earlier export. It is designed for overseas ecommerce, Amazon operations, and procurement teams working with 1688 supplier data.

This Actor transforms data you provide. It does not scrape websites, log in to marketplaces, follow product URLs, or collect account credentials.

Choose the right first run

Your goal	Input	Recommended setting	Main result
Check whether a new file is usable	Current CSV/XLSX	Enable Validate only	Aggregate readiness and errors; no SKU-detail output
Standardize one supplier export	Current CSV/XLSX	Keep safe auto-detection	Full normalized current-SKU CSV
Find price or stock changes	Current + earlier CSV/XLSX	Add correct observation times and currency when required	Full results plus a focused action CSV
Connect an API or automation	JSON snapshots	Select Paste JSON snapshots	The same normalized result contract

Current release 0.12.9 synchronizes the public description with the validated 0.12.8 runtime; the executable behavior is unchanged. The default auto-detect upload remains free of the documentation-only generic mapping example. Published Run ZRGLqK7RyfSxVpKvw proved that an upload with no mapping field received the auto_detect_v1 default, resolved a generic CSV, validated one SKU with zero errors, and wrote no SKU rows or custom SKU events in validation-only mode. It retains 0.12.7's stricter generic identity detection and mapping validation, plus the exact-decimal action-list thresholds from 0.12. The complete project suite has passed 68 automated tests plus published cloud checks; these are technical checks, not customer demand or revenue evidence.

Start in two minutes

1. Select Upload CSV or Excel.
2. Keep Auto-detect safely (recommended), or choose the exact Gycharm preset. For a custom supplier file, select the generic format and edit the field mapping.
3. Upload the current file and enter its observation time.
4. For Shopify/TikTok target files, enter the currency used when the export was created; the file itself does not identify it.
5. Optionally upload an earlier file to detect price and stock changes.
6. For a dry quality check, enable Validate only (no SKU output).
7. Confirm data authorization and run.

The format adapters were validated against three public real-format samples distributed by the Gycharm 1688 export tool: normal XLSX, Shopify-target CSV, and TikTok-target XLSX. Auto-detection selected the correct dedicated preset and accepted all 151, 79, and 79 rows respectively without rejected records. Unknown or ambiguous fingerprints are rejected instead of guessed. This is interoperability evidence, not a claim of affiliation with Gycharm, Shopify, TikTok, or 1688, and it does not replace validation on an authorized customer's private export variant.

The published 0.4.1 build also processed the complete 79-row Shopify-target and 79-row TikTok-target samples through Apify's file-upload path in validation-only mode. Both runs reported 79 valid rows and zero errors while writing zero dataset rows and emitting zero custom per-SKU events. The temporary file store was deleted after verification.

The published 0.5.1 build then repeated the default auto-detect path for all three complete samples. It selected gycharm_1688_export_v1, gycharm_1688_shopify_export_v1, and gycharm_1688_tiktok_export_v1 correctly, accepted 151/79/79 rows with zero errors, and again produced zero dataset rows and zero custom per-SKU events in validation-only mode.

The production build was also tested in Apify with 1,000 current and 1,000 previous SKUs. It saved 1,000 result rows and registered exactly 1,000 normalized-current-sku events without reaching the charge limit. Because the run was executed by the Actor owner, Apify recorded zero customer-accounted events; this proves event-count consistency, not creator revenue.

Input

Confirm that you are authorized to process the data, then use either file upload or JSON:

• current_file: required CSV/XLSX in file mode;
• previous_file: optional earlier export in the same format;
• current_observed_at and previous_observed_at: timezone-aware ISO 8601 times;
• file_currency: optional three-letter currency code, required for valid price comparison when the selected file format does not declare currency;
• file_adapter: defaults to strict auto-detection; the resolved adapter is recorded in RUN_SUMMARY;
• field_mapping: optional column mapping for generic files;
• current_snapshot and previous_snapshot: JSON API alternative;
• stale_after_days: optional, default 7;
• max_current_skus: optional safety limit, capped at 10,000.
• action_min_price_change_amount: optional non-negative decimal in each row's own currency, applied only to price-only action rows;
• action_min_price_change_percent: optional non-negative decimal percentage, applied only to price-only action rows;
• validation_only: optional dry quality check that produces only aggregate summary and errors.

Files support UTF-8 and GB18030 CSV, TSV, and unencrypted XLSX. Each file is limited to 15 MB, 200 columns, and 10,000 SKU rows. Historical time must be strictly earlier than current time.

Auto-detection uses exact required header fingerprints. It never chooses a preset from filenames or product contents. Generic auto-detection requires both a recognized product identity header and a recognized SKU identity header; files that depend on custom attribute columns must use an explicit mapping. Unknown mapping keys, empty header names, invalid attribute mappings, and invalid default currencies are rejected before import instead of being silently ignored. If current and previous files resolve to different formats, the run stops before comparison. To use a custom mapping, select Generic CSV/XLSX explicitly.

The Shopify-target preset reads Handle, Variant SKU, Variant Price, option pairs, and inventory quantity. The TikTok-target preset reads Seller SKU, Retail Price (Local Currency), variation pairs, and the store-specific Quantity in ... column. Common quantities such as 724套 are recognized. Currency is intentionally left unknown unless you provide file_currency; CatalogDelta never guesses a local currency.

Product and SKU identifiers must be strings so leading zeros are preserved. Do not include people, orders, account details, passwords, cookies, tokens, or unrelated free text.

Data readiness before output

Every RUN_SUMMARY includes a privacy-minimized data_readiness object. It reports:

• normalization_status: ready, review_required, or not_ready;
• price_comparison_status: not_requested, ready, partial, or not_ready;
• inventory_status: available, partial, or unavailable;
• aggregate counts for source versus derived identities, single/range/missing prices, missing currency or price basis, known stock, historical matches, and comparable prices;
• fixed suggested_action_codes such as providing currency or a previous snapshot.

These fields contain counts and fixed codes only. They do not echo product IDs, SKU IDs, attributes, prices, or file contents. In validation-only mode, use this report to correct the input before creating per-SKU output.

RUN_SUMMARY.cost_preview also multiplies the validated billable-current-SKU count by the live Apify runtime price for normalized-current-sku, when that price is available. It reports decimal strings in USD and never guesses a missing price. The estimate covers only custom per-SKU events: it explicitly excludes any Actor-start event, platform compute or storage, tax, and exchange fees. It is not a bill, payout, or revenue figure; review Apify's billing screen before a paid run.

Published build 0.8.1 verified this boundary with a synthetic validation-only run: one billable candidate produced a USD 0.003 custom-event preview while the run wrote zero dataset rows and emitted zero normalized-current-sku events. Apify separately recorded one Actor-start event and platform resource usage, so the preview is intentionally not presented as a total run cost.

The published 0.6.1 build verified this report on all three complete public samples. It identified 119 single-value plus 32 range-price rows in the 151-row normal export, and it flagged all 79 rows in each Shopify/TikTok target export as missing currency. All three validation runs wrote zero dataset rows and emitted zero custom per-SKU events.

Operational impact at a glance

Every summary also includes operational_impact, a privacy-minimized decision view. It reports counts for price increases, price decreases, unknown price direction, newly out-of-stock SKUs, restocked SKUs, other stock transitions, new SKUs, non-comparable SKUs, and historical rows not observed in the current snapshot. Counts can overlap when one SKU has both price and stock changes. No identifiers, prices, attributes, or source locations appear in this object.

Published build 0.10.1 verified all categories in one synthetic validation-only run: one increase, one decrease, one newly out-of-stock SKU, one restock, one other stock transition, one new SKU, and one historical row not observed. The run emitted zero per-SKU events and no SKU-detail output.

Output

The default dataset contains normalized current SKU results. Historical-only missing_from_snapshot rows are written to the separate run-scoped dataset alias unbilled_context so they are not included in the custom paid event. RUN_SUMMARY records that dataset's ID. The key-value store also contains:

• SAFE_CURRENT_RESULTS_CSV: CatalogDelta-generated UTF-8 CSV for successfully written current SKU rows, with all 26 fields and spreadsheet-formula protection;
• SAFE_ACTIONABLE_RESULTS_CSV: the protected current-result subset whose primary outcome is not unchanged, for direct operations follow-up;
• SAFE_HISTORICAL_CONTEXT_CSV: the same protected format for historical-only rows, when any exist;
• RUN_SUMMARY: resolved adapter, data readiness, operational impact, custom-event cost preview, CSV-artifact status, execution mode, counts, aggregate changes/quality flags, idempotency key, and platform billing totals without raw product content;
• ERRORS: validation errors with array locations, not complete source records.

The CSV records contain customer product data and must follow the same retention and access rules as the datasets. They include a UTF-8 BOM for spreadsheet compatibility. Validation-only and rejected runs do not create any SKU-detail CSV record. If a convenience CSV cannot be written, RUN_SUMMARY.csv_artifacts reports the failure while the dataset remains the source of truth.

The action list includes price changes, stock changes, newly observed SKUs, and non-comparable rows. It excludes unchanged rows and all historical-only context. Optional exact-decimal amount and percentage thresholds can suppress small price-only changes; when both are set, meeting either available threshold keeps the row. Stock changes, new rows, and non-comparable rows always remain actionable. If a sole configured metric is unavailable, the row is retained for review. RUN_SUMMARY.csv_artifacts.action_filter reports only the policy and aggregate counts. The list is a convenience view, not a different billing scope: billing still follows successfully saved valid current results in the default dataset.

Published build 0.9.1 verified both paths with synthetic data. A normal run created direct Output links for one current and one historical protected CSV row; a validation-only run created neither record. A separate attack-string check confirmed that =1+1, @SUM(1,1), and +synthetic were apostrophe-prefixed in the downloaded CSV.

Published build 0.11.1 verified the action-list boundary with three synthetic runs. A changed current SKU produced one full row and one price_changed action row; an unchanged current SKU produced one full row and no action record; validation-only mode produced no SKU-detail CSV. Raw streamed downloads retained all 26 fields and the UTF-8 BOM. These were owner tests, not customer usage or revenue.

Published build 0.12.1 verified threshold behavior with three more synthetic runs. With amount and percentage thresholds both set to 1.00, three valid current rows still produced three dataset rows and three custom events, while one small price-only row was removed from the two-row action CSV. A same-size price change accompanied by a stock change stayed actionable. The default policy remained backward compatible, and validation-only mode reported candidate/suppressed counts while writing zero SKU rows and emitting zero custom per-SKU events.

The Actor does not infer that a product is delisted. missing_from_snapshot means only that a historical SKU was not observed in the current snapshot.

Validate before creating SKU output

Enable validation_only to verify that a file parses, identities are usable, snapshots are ordered correctly, prices are comparable, and quality flags are understood. CatalogDelta calculates aggregate outcomes in memory, writes no SKU dataset rows, and emits no normalized-current-sku events. The run still writes RUN_SUMMARY and ERRORS. If the Store pricing configuration includes a separate Actor-start event, that start event may still be charged by Apify.

Result preview

product_id	sku_id	previous_price_amount	price_amount	currency	change_type	delta_amount	stock_status
852984040749	S852984040749黑色	23.00	25.00	CNY	price_changed	2.00	in_stock
852984040749	S852984040749白色	25.00	25.00	CNY	stock_status_changed	0.00	out_of_stock

Every default-dataset row includes raw and normalized attributes, match confidence, comparison reason, quality flags, source location, and billing eligibility. The Output tab can export the dataset as JSON, CSV, Excel, XML, or RSS through Apify. Those converted files are generated by Apify; CatalogDelta does not claim that the platform neutralizes spreadsheet formulas. For data containing untrusted text, use the CatalogDelta-generated protected CSV links above, JSON, or the local CLI's protected result.csv.

Price comparison rules

CatalogDelta uses fixed-point decimal arithmetic. It compares only single-value prices with the same currency and the same price basis. Missing prices, range prices, currency mismatches, and price-basis mismatches are retained as not_comparable rather than being guessed or converted.

Pay per event scope

The intended event is normalized-current-sku: one event for each successfully saved, valid current SKU result, including unchanged, changed, new, and not-comparable results. Historical-only missing_from_snapshot rows and rejected records are not charged. The pricing configuration must not also assign a price to the default-dataset-item synthetic event, because that would create a second charge for the same current result. The custom event count held by the platform charging manager is the billing source of truth.

Active launch price: USD 0.003 per saved valid current SKU result, equivalent to USD 3 per 1,000 results. Rejected records and historical-only rows are not charged.

Ready-made tasks

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

Data responsibility

You control the Actor's Apify input and output storages and must set a retention period that matches your legal basis and customer agreement. Remove the run storages when they are no longer needed. Platform infrastructure does not replace your responsibility to confirm authorization, minimize data, restrict access, and honor deletion requests.