Woo GTIN Fallback Review

Review why an already mapped native WooCommerce update CSV may not fall back to Global Unique ID matching. This Actor compares your proposed CSV with a complete current export and reports the ID, SKU, and normalized GTIN evidence for each proposed row.

It uses an original small comparator based on a frozen native WooCommerce 11.2.0 source-rule profile (selected by input version 11.2). It does not connect to your shop or write products. Prepare supplier column mapping before submitting the CSV.

Try the original demo

Run with:

{ "mode": "demo" }

The included fictional CC0 fixture contains two current products and four proposed rows:

Proposed identifiers	Result
ID 999, empty SKU, GTIN 00123	gtin_fallback_blocked
Empty ID, SKU OLD-SKU, GTIN 00123	gtin_fallback_blocked
Empty ID and SKU, GTIN 00123, type simple	gtin_match_eligible
Empty ID and SKU, GTIN 00999, type variable	type_mismatch_review

Demo uses only this fixture. Supplying custom CSV data with mode: "demo" is rejected. There is no custom report event for demo; the platform start fee still applies.

Review your CSV files

Use mode: "review", supply currentCsv and proposedCsv as complete CSV strings, and set each acknowledgement to true:

• rightsConfirmed: you are authorized to upload and process both files in your Apify storage.
• confirmUpdateExistingProducts: the native importer will use Update existing products.
• currentExportComplete: the current export contains the complete target catalog. A partial export cannot establish that an ID, SKU, or GTIN is absent.
• globalUniqueIdMappingConfirmed: the declared column is mapped to native Global Unique ID.

The frozen profile accepts nativeWooVersion: "11.2" and binds it to the exact 11.2.0 tag and commit. Other versions are unsupported; this is not a support claim for every 11.2.x release. The Actor does not detect your installed WooCommerce version.

The default exact column name is GTIN, UPC, EAN, or ISBN. Because it contains commas, the CSV header must be quoted:

ID,SKU,Type,"GTIN, UPC, EAN, or ISBN"
11,PROJECT-A,simple,00123
12,PROJECT-B,simple,00999

globalUniqueIdHeader is fixed to this native header; custom overrides are rejected. Map supplier columns to these native names before running. The current export must include ID, SKU, Type, and the quoted Global Unique ID header. Missing current headers produce incomplete-coverage diagnostics. Duplicate headers and header whitespace aliases are rejected. Keep original identifier strings and leading zeros intact. Empty fields and absent columns are different evidence.

sample-review-input.json uses the same fictional rows in review mode, includes the four acknowledgements, and is a charged custom-mode example when a useful report is delivered. Replace the two strings with your authorized native CSV data for a real review.

How to read the report

The review records separate ID and SKU matches and preserves both original and parsed evidence. A truthy parsed ID or SKU blocks GTIN fallback; the Actor does not infer a generic ID-over-SKU update target. If ID and SKU identify different current rows, inspect identifier_conflict_review.

Integer ID strings use the native absolute-integer form within the supported 64-bit range: 0 and 000 parse to zero and do not block fallback; -11 parses to 11. Other PHP coercion forms and overflow remain unknown. An empty SKU or the single string 0 is false under native PHP truthiness and does not block fallback. Sanitation-sensitive SKU/GTIN text is unsupported rather than guessed.

With false parsed ID and SKU, a nonempty normalized GTIN can be eligible when exactly one current row matches and the parsed base type agrees. GTIN normalization retains ASCII digits, X, x, and hyphens, including leading zeros and case. The report preserves original and normalized GTIN strings. Duplicate normalized identifiers are ambiguous; no row is selected silently.

Type parsing removes virtual and downloadable flags, lowercases the remaining tokens, and uses the first native base type (simple, variable, variation, grouped, or external). A present blank Type cell or a flag-only Type defaults to simple. Quote composite CSV values such as "simple, virtual". Absent proposed Type can produce type_unknown_review; unknown plugin types are unsupported.

ID matching uses the parsed absolute integer. SKU and normalized GTIN candidate evidence uses exact strings from the supplied export. Case-fold-only candidates make the relevant SKUmatchKnown or GTINmatchKnown evidence unknown; actual database collation is not simulated.

Row status	Meaning
gtin_fallback_blocked	Supplied truthy ID or SKU has no exact current match while GTIN candidates exist; that identifier prevents fallback.
id_sku_present_review	Supplied truthy ID or SKU blocks fallback, with matched or unmatched evidence. Read match-known flags and the reason code; this does not establish import success.
identifier_conflict_review	ID and SKU match different current rows; no update target is promised.
gtin_match_eligible	Parsed ID and SKU are false, normalized GTIN uniquely matches, and parsed base type agrees.
type_mismatch_review	A unique GTIN candidate has a different parsed base product type.
ambiguous	Supplied identifier evidence or normalized GTIN has duplicate candidates.
gtin_no_current_match	Normalized GTIN has no candidate in the declared complete usable export.
no_mapped_identifier	Parsed ID/SKU are false and normalized GTIN is empty.
variation_creation_unknown	An unmatched proposed variation needs parent, order, or attribute checks outside this diagnostic.
missing_current_coverage	Current headers, identifiers, or the completeness acknowledgement do not support absence claims.
collation_unknown	GTIN case-fold candidates can change the result under database collation.
type_unknown_review	Proposed Type is absent, so no same-type claim is made.
unsupported_version / unsupported_configuration	Frozen version or required update/mapping configuration is unavailable.
unsupported_identifier_format / unsupported_gtin_format / unsupported_product_type	Native coercion, sanitation, GTIN mapping, or product type is outside the supported deterministic subset.

fallbackEligible is a boolean or null when eligibility is unknown. Read row reason codes, candidate row numbers, and the unsupported/incomplete counts before using a result.

This diagnostic does not simulate the complete importer or promise that an update will succeed. Custom hooks, translated fields, site database collation, variation creation, parent ordering, attributes, product status, and other importer behavior remain outside its scope. It does not validate the check digit or commercial correctness of a GTIN, repair supplier mappings, or create an import-ready patch.

Saved outputs

A completed report delivers:

• REPORT.json in the default key-value store: every proposed row, supplied ID/SKU, original and normalized GTIN, separate ID/SKU match references, GTIN candidate current-row references, eligibility, status/reason code, exact candidate counts, limits, frozen rule profile, and final billing. currentIdentityEvidence saves the complete current-row identity table once; use source-row references to inspect those identities.
• REVIEW.csv in the same store: every proposed row with original/parsed identifiers, GTIN strings, match row references, eligibility, declared Type, status/reason, and source version/hash. Spreadsheet formula cells are guarded; use REPORT.json for exact original evidence, parsed Type, match-known flags, exact candidate totals, and the complete current identity table.
• OUTPUT: final run summary, links, and billing state.
• One nonempty default Dataset summary containing status, mode, totalRows, usefulRowCount, counts, ruleProfile, and billing. Proposed records and the current identity table stay in REPORT.json rather than the Dataset summary.

The Dataset summary is saved before the custom report event, so its billing can remain pending. Read OUTPUT and REPORT.json for the final authoritative billing state. An unknown charge outcome stays unconfirmed; it is not silently retried. Actor Output links expose all these artifacts.

Price and limits

The custom event identifier_precedence_review_completed costs $0.05 per delivered useful identity review report, at most one event per run. It is charged after the accessible complete report is saved. It is not a per-row fee.

The automatic platform event apify-actor-start is $0.00005 per start event at the configured 256 MiB memory, with the platform minimum of one event. The Actor does not manually charge this event. Allow $0.05005 for one useful review including the start allocation. There is no default Dataset item charge.

Original demo, invalid input, and diagnostic-only/all-unknown reviews have zero custom report events. A report that includes at least one useful row and other unknown rows has one report event and visible coverage counts. Funded event capacity is checked before any useful Dataset, key-value-store, or checkpoint content is saved. Insufficient budget returns diagnostics instead of useful report details. Resuming a run does not intentionally duplicate its report fee.

Each CSV is limited to 5,000 data rows, 5 MiB UTF-8, and 200 columns. CSV quoting is parsed with csv-parse; identifiers stay strings. The Actor accepts text only and does not fetch files or URLs. Both review outputs include every bounded proposed row (up to 5,000); proposed-row detail is not truncated. Each row's IDmatches, SKUmatches, and GTINcandidateCurrentRows reference arrays contain at most 50 references per field. IDmatchCount, SKUmatchCount, and GTINcandidateCount retain exact totals; candidatesTruncated and candidateDetailCap expose this limit. Coverage also reports candidateReferencesTruncatedRows. The complete current identity evidence remains available once in REPORT.json, so a capped reference list is not a claim that no further candidates exist.

Source and license

The source-rule profile is pinned to native WooCommerce 11.2.0, commit 1699191d5074a22e7f6c43ff2da8fa9942905435. The combined importer/abstract-importer SHA-256 is 13ccde0d3f978c6951e3b149d6eae4a00eccb8293ddb8bd5554b2e546604fbda. The report's ruleProfile and evidence/source-profile.json preserve the same binding and hash method. Immutable upstream references are the CSV importer and abstract importer. See the official native CSV importer documentation for the import workflow. This product is an independent diagnostic and is not affiliated with WooCommerce.

The comparator is original JavaScript; WooCommerce PHP importer code is not copied or executed. SDK apify is pinned to 3.7.2, and csv-parse is pinned to 7.0.2 in the shipping lockfile. The evidence/csv-parse-license.txt is included; upstream software license notices remain with the dependencies.

The fictional fixture CSV values in this SKU are original project material dedicated under CC0-1.0. LICENSE-FIXTURES.txt describes the fixture-only dedication. This does not license uploaded customer data or upstream software.