Products CSV import API
products_v1
Import this template via API. Import a product catalog CSV. SKU-keyed, GTIN-checksum-validated, multilingual category and weight hints.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=products_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- E-commerce
- FHIR resource
- —
- Risk level
- low
- Fields
- 9 (3 required, 1 validated)
Why this template?
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 & common foreign headers
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.
Schema
The canonical column set, with 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.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| sku | string | yes | — | sku · artikelnummer · référence · codice articolo · código |
| name | string | yes | — | name · nom · nome · nombre |
| description | string | — | — | — |
| price | number | yes | — | preis · prix · prezzo · precio |
| currency | string | — | — | währung · devise · valuta · moneda |
| gtin | string | — | gtin | gtin · ean · barcode |
| category | string | — | — | kategorie · catégorie · categoria · categoría |
| weight_g | number | — | — | gewicht · poids · peso |
| in_stock | boolean | — | — | vorrätig · en stock · disponibile · disponible |
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=products_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/products_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "products_v1",
headers: ["sku", "name", "description", "price"]
})MCP install instructions →FAQ — Products CSV import
How do I model variants (size, colour)?
One row per variant SKU. The canonical row is variant-level because that is what fulfilment runs on; product-group rollups happen downstream.
What about multi-currency pricing?
One row per currency, or a separate `prices` table linked by SKU. The canonical row is one currency to keep migration straightforward.
Can I import without GTIN?
Yes — GTIN is optional. Inline marketplaces without barcoded products work cleanly.
What about multi-image and rich-text descriptions?
Both belong in a media-and-content table linked by SKU, not on the canonical product row. The catalog template keeps the row narrow so PIM-to-PIM migrations stay portable.