Orders CSV import API
orders_v1
Import this template via API. Import Shopify/Magento/WooCommerce-style orders from CSV. Status-bounded, currency-required, tax and discount parsed.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=orders_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- E-commerce
- FHIR resource
- —
- Risk level
- low
- Fields
- 9 (3 required, 0 validated)
Why this template?
The Orders template is the canonical schema for a storefront's purchase orders — the row a Shopify export, a Magento dump, a WooCommerce backup, or a homegrown order log all reduce to. Each row carries an id, a customer_id foreign key, a total amount, a required currency, a status enum (pending / paid / shipped / delivered / cancelled / refunded), a placed_at timestamp, an optional shipping_address_id, tax, and discount. E-commerce teams use this template when migrating between platforms (Shopify → BigCommerce, WooCommerce → Shopify), when consolidating multi-region storefronts into one warehouse, and when feeding a customer-facing "download my order history" feature. The cascade picks up "Bestellnummer", "numéro de commande", "numero ordine", "número de pedido" without an LLM call — international storefronts are the typical case, not the edge case.
Tax and discount are number-typed and locale-tolerant. The status enum is shipping-shaped (it tracks the order through the fulfilment chain, not just payment) so reports about delivery success work without joining a separate fulfilment table. Currency is required because cross-currency stores are common and per-row currency is the only safe modelling choice.
Migration scenarios & common foreign headers
Migration scenarios for the Orders template: full platform migrations (Shopify → BigCommerce, Magento → Shopify, WooCommerce → Centra), consolidating multi-region storefronts into one warehouse for analytics, feeding a customer-facing "download my order history" feature, and backfilling a fresh ERP with two years of order history. Foreign headers we see weekly: "Bestellnummer / Numéro de commande / Numero ordine / Número de pedido / Order ID / Customer / Kunde / Client / Cliente / Total / Gesamtbetrag / Totale / Currency / Währung / Devise / Status / Statut / Stato / Estado / Placed / Bestelldatum / Date de commande / MwSt / TVA / IVA / Tax / Rabatt / Remise / Sconto / Descuento". The cross-platform header coverage is exhaustive — most e-commerce migrations land cleanly without any LLM escalation.
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 |
|---|---|---|---|---|
| id | string | yes | — | bestellnummer · numéro de commande · numero ordine · número de pedido · order id |
| customer_id | string | — | — | kunde · client · cliente |
| total | number | yes | — | gesamtbetrag · total · totale |
| currency | string | yes | — | währung · devise · valuta · moneda |
| status | enum | — | — | status · statut · stato · estado |
| placed_at | date | — | — | bestelldatum · date de commande · fecha del pedido |
| shipping_address_id | string | — | — | — |
| tax | number | — | — | mwst · tva · iva · tax |
| discount | number | — | — | rabatt · remise · sconto · descuento |
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=orders_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/orders_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: "orders_v1",
headers: ["id", "customer_id", "total", "currency"]
})MCP install instructions →FAQ — Orders CSV import
How do I model order line items?
Line items belong in a separate template (one row per item). The canonical Orders row is the header; line items link by order_id.
What about gift cards and store credit?
Apply them as discount on the canonical row, or fork to add an explicit `payment_method` field. The shape stays narrow on purpose.
Can I import orders without a customer_id (guest checkout)?
Yes — customer_id is optional. Guest orders carry null in that column. Downstream upserts should not blow up on null.
How do I handle refunded orders that retain status=refunded but also have a separate Returns row?
Both are valid — the order status reflects the latest state, and the Returns table is the audit log. Use the Returns template alongside Orders to keep the lineage; do not collapse them.