E-commerce pack
Products CSV import API
Import a product catalog CSV. SKU-keyed, GTIN-checksum-validated, multilingual category and weight hints.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=products_v1" \
-F "file=@your_data.csv"Canonical columns
The whole schema, printed as it ships.
Every canonical column, the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against. This is the shipped definition, not a summary of it.
products_v1- fields
- 9
- required
- 3
- validated
- 1
- hints
- 31
| Canonical column | Type | Required | Validators | Header hints the cascade matches |
|---|---|---|---|---|
sku | string | yes | — | skuartikelnummerréférencecodice articolocódigo |
name | string | yes | — | namenomnomenombre |
description | string | — | — | matched on the column name |
price | number | yes | — | preisprixprezzoprecio |
currency | string | — | — | währungdevisevalutamoneda |
gtin | string | — | gtin | gtineanbarcode |
category | string | — | — | kategoriecatégoriecategoriacategoría |
weight_g | number | — | — | gewichtpoidspeso |
in_stock | boolean | — | — | vorrätigen stockdisponibiledisponible |
Read the same definition as JSON at GET /v1/templates/products_v1. A hint match resolves on layer 2 — no LLM call, no token spend, just the flat per-map fee. Hover a validator id to see what it checks.
- 9 canonical fields
- 3 required
- 1 validated
- 31 header hints, 5 languages
Why it exists
Written for the file you actually receive.
The Products template is the catalogue row — the schema for a Shopify product CSV, a Magento catalog export, or an enterprise PIM dump. Each row carries a SKU (required), a name (required), an optional description, a price (required), an optional currency, an optional GTIN (validated via GS1 mod-10 checksum), a category, a weight in grams, and an in_stock boolean. The Products template is the workhorse import for migrations and quarterly catalog refreshes — most teams run it more often than any other e-commerce template. The GTIN validator accepts EAN-8, UPC-A, EAN-13, and GTIN-14 — all four lengths share the same mod-10 algorithm, so the validator is one path rather than four. The cascade picks up "artikelnummer", "référence", "codice articolo", "código" at zero cost.
price is required because an unpriced product is a draft, not a catalog entry. Currency is optional because most catalogs run single-currency; null means "the default for the workspace". weight_g is in grams (not ounces, not kilos) so cross-store rollups do not need a conversion table.
Migration scenarios & the foreign headers they ship
Migration scenarios for the Products template: full catalog ports between PIMs (Akeneo, Salsify, Plytix), Shopify-to-Shopify migrations during a rebrand, marketplace sync where the canonical catalog must mirror to Amazon / eBay / Etsy, and quarterly catalog refreshes when suppliers ship updated GTIN lists. Foreign headers we see daily: "SKU / Artikelnummer / Référence / Codice articolo / Código / Name / Nom / Nome / Nombre / Beschreibung / Description / Descripción / Descrizione / Preis / Prix / Prezzo / Precio / Währung / Currency / Devise / GTIN / EAN / Barcode / Kategorie / Catégorie / Categoría / Categoria / Gewicht / Poids / Peso / Vorrätig / En Stock / Disponible". The GTIN checksum validator catches barcode-typo corruption before it lands in the marketplace sync — a single bad GTIN can hide a whole product from Amazon search.
The cascade
Five layers, and the cheapest one wins.
Layers run in order and stop the moment a column resolves. That is the single biggest cost lever in the system: a column caught on layer 2 never reaches the metered layer 5.
- L1Statisticsno LLM
Auto-accepts a header that past confirmations already resolved the same way, at {minN:100, minRatio:0.95} or {minN:20, minRatio:1.00}.
- L2Heuristicno LLM
Normalises accents, punctuation and whitespace, then compares against the column name, the label, and every registered hint (DE / FR / IT / EN / ES).
- L3Fuzzyno LLM
Token-set ratio plus Levenshtein over the normalised strings. Auto-accepts at 0.80 — it absorbs typos and reordered words.
- L4Semanticcheap, cached
Embedding cosine between the header and the field’s label + hints. Catches the long tail of paraphrases.
- L5LLMmetered
Everything still unresolved goes up in ONE batched, collision-aware call, constrained to this template’s column set so it cannot invent a field.
Try it
One template id, two ways in.
REST for your import pipeline, MCP for your editor. Both run the same cascade and both honour the same schema-only clamp.
REST · POST /v1/uploads
Name the template; the cascade picks up the rest. The canonical definition is read-only at GET /v1/templates/products_v1.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=products_v1" \
-F "file=@your_data.csv"MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your editor and call the same cascade as a tool. Schema-only calls leave only column names and up to three clamped sample rows.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template_id: "products_v1",
headers: ["sku", "name", "description", "price"]
})Questions
Products CSV import — FAQ
Ready when you are
Map products in production — without shipping raw records.
Schema-only mode leaves only headers and a handful of clamped samples. Add full-data when you need row-level AI, routed in-region under a BAA.