E-commerce pack
Customers CSV import API
Import e-commerce customers from CSV. Email-validated, phone-validated, lifetime stats carried as numbers.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=customers_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.
customers_v1- fields
- 9
- required
- 2
- validated
- 2
- hints
- 28
| Canonical column | Type | Required | Validators | Header hints the cascade matches |
|---|---|---|---|---|
id | string | yes | — | matched on the column name |
email | yes | email | e-mailmailcorreocourriel | |
first_name | string | — | — | vornameprenomprénomnombregiven name |
last_name | string | — | — | nachnamenomcognomeapellidosurname |
phone | phone | — | phone | telefontéléphonetelefonophonemobile |
default_shipping_address_id | string | — | — | matched on the column name |
created_at | date | — | — | matched on the column name |
lifetime_orders | number | — | — | anzahl bestellungennombre de commandesnumero ordininúmero de pedidos |
lifetime_value | number | — | — | lifetime valueumsatz gesamtchiffre d'affaires totalricavi totalivalor total |
Read the same definition as JSON at GET /v1/templates/customers_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
- 2 required
- 2 validated
- 28 header hints, 5 languages
Why it exists
Written for the file you actually receive.
The Customers template is the buyer-side counterpart to Orders. Each row carries an id, a validated email (required), optional first and last names, an optional phone, an optional default shipping address id, a created_at timestamp, and two lifetime stats: lifetime_orders and lifetime_value. The lifetime fields are denormalised because most downstream tools expect them on the customer row rather than computed at query time; that denormalisation is per-workspace policy, and the template carries it cleanly. E-commerce teams use this template to migrate between platforms, to seed a CDP, to refresh an RFM segmentation, and to feed a loyalty program. The cascade catches multilingual "lifetime value" variants without escalation because that header is one of the most-localised in retail data.
email is required because cross-platform customer identity is built on email — phone-only customers belong in a separate template. lifetime_value carries the same locale-tolerant number parsing as the orders template. created_at is the customer's creation timestamp, not their first order — those two often diverge and the template preserves the difference.
Migration scenarios & the foreign headers they ship
Migration scenarios for the Customers template: cross-platform customer base migrations during a re-platforming project, CDP seeding for the first time (Segment, mParticle, RudderStack), refreshing an RFM segmentation before a marketing campaign, and feeding a loyalty program with a year of order-derived lifetime stats. Foreign headers we see weekly: "Customer ID / Kundennr / Numéro client / Email / E-Mail / Correo / Courriel / Vorname / Prénom / Nombre / Nachname / Nom / Apellido / Telefon / Téléphone / Teléfono / Default Shipping / Lieblings-Lieferadresse / Anzahl Bestellungen / Nombre de commandes / Número de pedidos / Lifetime Value / Umsatz Gesamt / Chiffre d'affaires total / Ricavi totali". The cross-platform header coverage is heavy on commerce-specific vocabulary that does not appear elsewhere in the catalogue.
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/customers_v1.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=customers_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: "customers_v1",
headers: ["id", "email", "first_name", "last_name"]
})Questions
Customers CSV import — FAQ
Ready when you are
Map customers 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.