E-commerce pack
Returns CSV import API
Import return and refund records from CSV. Reason enum-bounded, status walks the RMA workflow.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=returns_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.
returns_v1- fields
- 8
- required
- 2
- validated
- 0
- hints
- 8
| Canonical column | Type | Required | Validators | Header hints the cascade matches |
|---|---|---|---|---|
id | string | yes | — | matched on the column name |
order_id | string | yes | — | matched on the column name |
customer_id | string | — | — | matched on the column name |
reason | enumdefectivewrong_itemno_longer_neededdamaged_in_shippingother | — | — | grundraisonmotivo |
amount | number | — | — | betragmontantimportomontoamount |
currency | string | — | — | matched on the column name |
status | enumrequestedreceivedinspectedrefundedrejected | — | — | matched on the column name |
requested_at | date | — | — | matched on the column name |
Read the same definition as JSON at GET /v1/templates/returns_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.
- 8 canonical fields
- 2 required
- 0 validated
- 8 header hints, 5 languages
Why it exists
Written for the file you actually receive.
The Returns template captures the row that closes the order loop — every refund, exchange, and warranty return. Each row carries an id, a foreign key order_id (required — every return points to an order), an optional customer_id, a reason enum (defective / wrong_item / no_longer_needed / damaged_in_shipping / other), an amount, a currency, a status enum that walks the return through requested → received → inspected → refunded / rejected, and a requested_at timestamp. E-commerce teams use this template for migrations, for monthly returns-rate reporting, and for feeding fraud-detection models that watch the requested_at / received_at gap. The reason enum is intentionally narrow — the canonical set is the cross-platform intersection, and richer taxonomies (size_too_small vs size_too_large) live in a forked template.
order_id is required because a return without an order is a chargeback or a write-off — different schema. amount is optional because some returns are exchanges with no money movement. currency is optional and inherits from the parent order in most downstream systems.
Migration scenarios & the foreign headers they ship
Migration scenarios for the Returns template: feeding a monthly returns-rate report at executive level, importing a 3PL's RMA log for reconciliation against in-house records, migrating between order-management systems where the RMA history must survive, and seeding a fraud-detection model that watches the requested_at / received_at gap as a signal. Foreign headers we see often: "Return ID / Retoure / Retour / Devolución / Reso / Order ID / Bestellnummer / Numéro de commande / Customer / Kunde / Cliente / Grund / Raison / Motivo / Motivazione / Betrag / Montant / Importo / Monto / Status / Statut / Stato / Estado / Requested / Beantragt / Demandé / Solicitado". The reason enum walks the bounded set that supply-chain dashboards aggregate on — extending it via fork is a one-line change when retailer-specific reason codes are needed.
The cascade
Six 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/returns_v1.
curl -X POST https://api.adaptivmapr.com/v1/uploads \
-H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \
-F "template=returns_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: "returns_v1",
headers: ["id", "order_id", "customer_id", "reason"]
})Questions
Returns CSV import — FAQ
How do I model partial returns (one item from a multi-item order)?
What about exchanges that swap one SKU for another?
Can a return have no associated reason?
How does the status enum map to RMA workflow tools?
Map returns 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.