Seller Profit Guard · How it works · CSV privacy

Seller CSV column mapper

Map two materially distinct synthetic seller schemas to stable canonical order-item and payment-event fields. Check one-to-one coverage, required targets, collisions, sample width, currency and date semantics, private or formula-like examples, size limits, dated evidence, and nine explicit controls. Hard failures mask derived results. The tool never transforms, reconciles, stores, imports, or authorizes production data.

Maintained by Seller Profit Guard Editorial Team. Last reviewed: 2026-07-31.

Seller CSV mapping flow from synthetic source schemas through canonical targets, semantic evidence, decision, monitoring, and restoration — Translate source-specific names into a documented canonical schema without treating a clean mapping as import or reconciliation proof.

Validate structure first

Use the separate CSV Import Validator before mapping. Column mapping assumes the synthetic fixture already has a declared delimiter, consistent row width, stable header names, safe fields, and no unresolved parsing error.

Mapping cannot repair malformed CSV records.

Use synthetic headers and values

Enter only invented header names and invented sample values that reproduce the mapping question. Do not paste buyer, customer, address, payment, bank, credential, private order, statement, or raw CSV content into a public worksheet.

The default fixtures contain no real records.

Define a canonical schema

A canonical schema is a seller-controlled set of stable field names and meanings used after source-specific headers are translated. It should document each target's grain, datatype, unit, currency, date event, timezone, null rule, and allowed transformation.

A name alone does not define meaning.

Keep source and target separate

The left side of each mapping line is a synthetic source header; the right side is a lower_snake_case canonical target. Preserving both sides makes the translation reviewable and avoids overwriting source evidence with internal terminology.

The worksheet never rewrites the source file.

Map Scenario A at order-item grain

The order-item fixture maps Order ID, Line Item SKU, Quantity, Item Total, and Created At to order_ref, sku, quantity, item_total, and ordered_at. This invented schema illustrates grain; it is not an official Etsy header specification.

Order and line-item identifiers may differ in real exports.

Map Scenario B at transaction grain

The payment fixture maps Transaction ID, Type, Gross, Fees, Net, and Occurred At to transaction_ref, transaction_type, gross_amount, fee_amount, net_amount, and occurred_at. It stays separate from orders because statements describe financial events.

A payout, deposit, sale, and adjustment can have different grains.

Use one mapping per line

Write `Source Header = canonical_target`. Lines without one equals separator, a source, or a target are malformed. Multiple equals signs remain part of the target and fail the lower_snake_case rule rather than being guessed.

Explicit syntax makes version diffs readable.

Require source-header existence

Every mapped source name must exist in the declared synthetic header list after case-insensitive comparison. A typo or stale mapping blocks because it would otherwise produce a silently empty canonical field.

Case handling for production sources requires a separate versioned rule.

Prevent duplicate source assignments

A source header may map only once inside a scenario. Mapping the same field to two targets can duplicate a value or hide a derived-field requirement; create an explicit transformation outside this one-to-one worksheet instead.

One-to-many derivation is a different control.

Prevent target collisions

Two source headers cannot map to the same canonical target in this worksheet. A collision can overwrite one value or conceal competing definitions, especially for gross, fee, net, date, identifier, and SKU fields.

Resolve precedence and derivation before reuse.

Use lower_snake_case targets

Canonical targets begin with a lowercase letter and contain lowercase letters, digits, and underscores. The naming rule supports deterministic comparison, but it does not validate a field's definition, type, or business meaning.

Document semantics alongside every target.

Declare required targets

List the canonical fields the receiving analysis truly needs. Missing required targets block even when overall coverage is high, because one critical identifier, amount, date, type, or SKU field can make a dataset unusable.

Required sets remain workflow-specific.

Measure mapping coverage

Coverage equals valid one-to-one mappings divided by declared synthetic source headers. It shows how much of the fixture is intentionally handled, but a high percentage cannot override missing required targets, collisions, privacy issues, or semantic uncertainty.

Unmapped optional fields can produce Review.

Set a coverage threshold

The default is 100%. A lower threshold can classify an otherwise valid mapping with optional unmapped headers as Review, not Ready. Thresholds never waive structural mapping errors, required targets, privacy, evidence, or declared conflicts.

Coverage policy requires a named owner.

Require dated evidence and nine confirmations

Use a real source-review date and policy-effective date, keep the policy date no later than the source review, and affirm all nine synthetic-data, source-version, canonical-definition, grain, currency/date, privacy/formula, counterexample, restoration, and mapping-authority controls. Any missing confirmation blocks the worksheet.

The confirmations record seller responsibility; they do not certify production semantics.

Bound mapping size

Set a maximum of 1–100 synthetic source headers per scenario and keep each scenario's headers, samples, mappings, required targets, and date semantics within 50,000 characters. Oversized public worksheets block rather than becoming an uncontrolled substitute for protected mapping infrastructure.

The default limit is 100 headers per scenario.

Keep mapping contracts distinct

The order-item and payment-event scenarios must use materially different source-header, mapping, and required-target contracts. Copying one mapping into both scenarios blocks because it tests one grain twice while claiming broader coverage.

Distinct contracts do not prove a valid cross-source join.

Match sample width

The invented sample has one pipe-separated value per synthetic header. A width mismatch blocks because the worksheet cannot reliably associate examples with header positions.

The sample demonstrates types; it is not production evidence.

Check formula-like headers and samples

Synthetic headers or invented sample values beginning with ASCII equals, plus, at, nonnumeric minus, full-width formula prefixes, or leading tab, carriage-return, or line-feed controls block. This prevents a public fixture from normalizing spreadsheet formula risk as ordinary content.

Valid finite negative amounts can remain numeric examples; blocking is a risk signal, not a spreadsheet sanitizer.

Declare currency explicitly

Each monetary scenario uses a three-letter currency code. The code documents units but does not prove that source amounts share that currency, determine conversion dates, or settle accounting treatment.

Mixed-currency sources need separate conversion fields and evidence.

Define date event semantics

State what event the mapped date represents—such as order creation or statement transaction occurrence—and whether the value is UTC, offset-based, or interpreted in a named timezone. Event meaning and timezone are both required.

A parseable timestamp can still represent the wrong event.

Validate date samples

A target ending in `_date` requires a real `YYYY-MM-DD` calendar date. Targets ending in `_at`, `_time`, or `_timestamp` require an ISO timestamp with `Z` or an explicit numeric UTC offset. Permissive values that a runtime might guess, such as `1`, block.

This is a bounded syntax check, not proof of event meaning, locale, daylight-saving, settlement, or reporting semantics.

Screen unsafe headers

Synthetic source lists containing private-person, contact, address, payment-card, bank, token, password, secret, access-key, or credential-like headers block the worksheet. Remove unnecessary sensitive columns before public modeling.

Mapping a private header does not make it safe.

Read Block

Block means a schema, width, syntax, source, collision, required-target, target-name, formula, date, currency, privacy, evidence, scope, threshold, or declared-conflict control failed. Stop reuse and repair the mapping evidence.

Block does not modify either file.

Read Review

Review means required targets and structural controls pass, but optional source headers remain unmapped or coverage is below the declared threshold. A named reviewer must accept, map, or exclude them before reuse.

Review is not platform or import acceptance.

Read Ready

Ready means both synthetic fixtures have complete one-to-one coverage and clear implemented evidence controls. It proves only the entered worksheet, not complete production mapping, source semantics, platform compatibility, reconciliation, privacy compliance, or import authorization.

Test transformations separately in an isolated local workflow.

Separate mapping from transformation

Renaming a header is not the same as parsing dates, converting currencies, allocating fees, normalizing signs, splitting compound values, joining records, or deriving totals. Record transformations as versioned code with input and output examples.

This mapper models direct one-to-one names only.

Separate mapping from reconciliation

A payment statement and order-items export can both map cleanly yet fail to reconcile because identifiers, periods, currencies, event dates, transaction types, refunds, deposits, and aggregation grains differ.

Use a separate reconciliation control after mapping.

Respect platform-specific schemas

Etsy distinguishes downloadable order items, orders, payment sales, and deposits. Shopify documents current product CSV columns, dependencies, older header compatibility, and overwrite consequences. Treat each documented source version as its own schema.

Never invent a universal marketplace export.

Preserve field definitions

For every canonical target, record label, business definition, source field, transformation, datatype, unit, currency, sign, timezone, null rule, uniqueness, grain, examples, exclusions, effective date, owner, and reviewer.

Without definitions, stable names can still carry unstable meaning.

Version mapping changes

Store source fingerprint, canonical schema version, mapping version, transformation version, evidence period, change reason, impact assessment, approver, effective date, prior mapping, and restoration rule.

Do not silently overwrite accepted mappings.

Run counterexamples

Test missing required targets, duplicate source headers, duplicate assignments, target collisions, stale source names, invalid targets, width mismatch, formula-like samples, invalid dates, invalid currency, unsafe headers, short scope, and open conflicts.

Every Block and Review rule needs a failing fixture.

Prepare a safe local test

Use a protected copy, isolated receiving target, synthetic or approved minimal dataset, logged mapping version, expected row and value results, backup, stop conditions, and restoration test. The public worksheet cannot perform this step.

Never experiment directly on the only production copy.

Monitor schema drift

Compare current source header fingerprint, order, types, units, enums, date formats, currency, identifiers, and grain with the accepted mapping. Stop when a change is unexplained or a required source disappears.

Do not auto-map new columns by name similarity.

Release through quality gates

Index this cluster only after tool logic, counterexamples, sources, answer quality, metadata, schema, images, links, privacy, similarity, mobile behavior, backups, build, ordered release, deployment, and live checks pass.

Search signals are measured later, not used as release permission.

Sources and further reading

W3C: Model for Tabular Data and Metadata on the Web: Official column titles, datatypes, required values, identifiers, schemas, and annotated-table context.
W3C: CSV on the Web Primer: Official examples of documenting columns, defining schemas, and validating tabular data.
W3C: Metadata Vocabulary for Tabular Data: Official column references, schema compatibility, datatype, and validation vocabulary.
IETF RFC 4180: Informational CSV record, header, field-count, quote, charset, interoperability, and privacy context.
OWASP: CSV Injection: Current formula-prefix, control-character, full-width variant, and mitigation limits.
Etsy Help: Download sold transactions: Official distinction among order items, orders, Etsy Payments sales, and Etsy Payments deposits.
Shopify Help: Using CSV files: Official platform-specific header, dependency, version, overwrite, encoding, and import-risk examples.
Seller Profit Guard methodology: Evidence, formula, privacy, correction, release, monitoring, and rollback controls.
Seller Profit Guard data privacy: Local-first boundaries for headers, samples, mappings, statements, orders, credentials, and raw files.

Related Seller Profit Guard tools

Etsy CSV profit calculator: Run a local order profit check with editable fee and SKU cost assumptions.
Payment reconciliation tool: Compare order rows with statement activity and flag unmatched rows.
SKU cost library: Save or import material, labor, packaging, shipping, and target margin assumptions.
Variant risk checker: Find missing SKUs and variation cost risks before a listing scales.
Etsy title checker: Review listing-title clarity, repetition, keyword chains, and mobile scanning.
Etsy tag checker: Review all 13 tag slots for duplicates, repeated meaning, and truthful coverage.
Free shipping threshold calculator: Estimate when a shipping subsidy can still meet a target margin.
Return window loss estimator: Model expected reverse shipping, restock work, recovery, and replacement loss.
Etsy Ads break-even calculator: Estimate target-safe Etsy Ads spend, ACOS, and ROAS after fees, fulfillment, and expected return loss.
CSV data privacy: Understand what the local-first workflow needs and what it does not need.
CSV Column Mapping Fields and Rules: Define synthetic headers, invented samples, one-to-one mappings, required targets, currency, date semantics, coverage, evidence, privacy, and decisions.
Order-Item CSV Mapping Example: Map a synthetic order-item export to stable identifiers, SKU, quantity, amount, and order-created timestamp fields with complete evidence.
Payment Statement CSV Column Mapping: Map a synthetic payment statement to transaction reference, type, gross, fee, net, and occurred timestamp without collapsing financial grain.
Seller CSV Column Mapping Mistakes: Find source-version, grain, collision, required-field, sample, type, currency, date, transformation, privacy, authority, and rollback errors.
CSV Mapping Data Sources and Evidence: Map source documentation, fingerprints, dictionaries, canonical definitions, receiving requirements, samples, owners, and rollback evidence.
CSV Mapping Decision Thresholds: Set required-target, coverage, collision, drift, test, reconciliation, approval, stop, and restoration controls without weakening semantic quality.
Order vs Payment CSV Column Mapping: Compare order-item and payment schemas while preserving distinct grains, identifiers, measures, timestamps, transformations, and authority.
Weekly Seller CSV Mapping Routine: Run source fingerprint, schema, synthetic mapping, privacy, transformation, backup, test, reconciliation, drift, and restoration checks weekly.
How to Interpret CSV Mapping Results: Read header counts, valid mappings, coverage, required gaps, collisions, privacy findings, errors, and decisions without overstating semantic proof.
CSV Column Mapping Audit Template: Audit source and canonical versions, grain, mappings, definitions, types, units, currency, dates, transformations, privacy, tests, approval, and restoration.
CSV Privacy Redactor Formula and Input Contract: Define purpose, source, grain, header-only input, required allowlist, keep, remove, review, retention, ownership, and restoration.
CSV Privacy Redactor Worked Example: Order Export: Reduce an invented Shopify-like order schema to item-level profit fields while removing contact, address, notes, payment-reference, and device columns.
CSV Privacy Redactor for a Support-Ticket Export: Build an aggregate refund-reason schema without carrying buyer contacts, messages, attachment links, or secrets into profit analysis.
Date and Currency Normalizer Formula Contract: Define source pattern, calendar validation, UTC offset, decimal convention, currencies, rate direction, observation date, rounding, and evidence.
Date and Currency Normalizer US Worked Example: Reperform one MM/DD/YYYY event, negative UTC offset, comma-grouped decimal-point amount, USD source, EUR target, and dated rate.
Export Schema Contract: 9 Inputs Before Automation: Define expected and observed headers, types, required fields, aliases, additions, version dates, row grain, and rollback before automating an export.
Export Schema Checker Example: One Added Column: Work a complete export schema example where an optional field is added without breaking a name-based parser or exposing seller rows.

Use the interactive tool

Enable JavaScript to open the calculator and process browser-local inputs. The explanatory content and source links remain available without JavaScript.

This tool provides operating estimates, not tax, accounting, legal, financial, or marketplace-policy advice. Verify current official sources and your own records before changing prices or operations.