Transactions CSV import API
transactions_v1
Import this template via API. Import ledger or payment transactions from any CSV. Amounts parsed, currency captured, status enum-bounded.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=transactions_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Core
- FHIR resource
- —
- Risk level
- low
- Fields
- 7 (3 required, 0 validated)
Why this template?
The Transactions template lands payment, ledger, and Stripe-export-shaped data into a single canonical row. It is the schema you reach for when a finance team hands you a year of bank reconciliations as CSV, when you migrate off Square mid-quarter, or when a marketplace partner ships you a monthly settlement file. Six fields are enough to carry the entire row through cleanly: id (the payment processor reference), amount (number, locale-tolerant), currency (string, not enum — ISO-4217 is too long to enumerate), status (one of pending / succeeded / failed / refunded), customer_id for the foreign key back to your CRM, and a free-text description that captures the wire memo or invoice line. Teams use the Transactions template for migrations, daily reconciliation pipelines, and to back the customer-facing "download my activity" export.
The amount field accepts US ("1,234.56"), EU ("1.234,56"), and Swiss ("1'234.56") number formats; locale is detected per column, not per cell, so a mixed file is rejected with a clear error rather than silently mis-parsed. The status enum is deliberately small — chargebacks and disputes live in a separate template so the line-item shape does not bloat.
Migration scenarios & common foreign headers
The Transactions template lights up for: monthly Stripe-to-warehouse syncs that feed a finance dashboard, mid-quarter PSP migrations (Stripe → Adyen, Square → Stripe) where you need to backfill the new platform with the old payment history, marketplace settlement file ingestion from Amazon / Etsy / Shopify Payments, and bank-reconciliation imports from SEPA / ACH CSVs. Common foreign headers the cascade resolves at zero cost: "Transaction ID / Betrag / Montant / Importe / Currency / Währung / Devise / Status / Statut / Stato / Customer / Kunde / Cliente / Date / Datum / Description / Beschreibung". The locale-aware number parser is the single most important detail — Swiss apostrophe-separated amounts are the silent killer of homegrown CSV importers.
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 | — | — |
| amount | number | yes | — | betrag · montant · importe · amount |
| currency | string | yes | — | währung · devise · moneda · valuta |
| status | enum | — | — | status · statut · estado · stato |
| customer_id | string | — | — | kunde · client · cliente |
| created_at | date | — | — | — |
| description | string | — | — | beschreibung · description · descripción · descrizione |
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=transactions_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/transactions_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: "transactions_v1",
headers: ["id", "amount", "currency", "status"]
})MCP install instructions →FAQ — Transactions CSV import
Does AdaptivMapr deduplicate by transaction id?
No. The template ingests; downstream upsert on id is your job. We surface duplicate ids in the dry-run report so you can decide whether to skip, merge, or reject.
Do I need to provide currency on every row?
Yes. Currency is required because amount semantics depend on it. Sources that ship one-currency-per-file should add a constant column upstream rather than assuming a default.
Can I add custom status values?
Fork the template and edit the enum. We deliberately keep the canonical set small so cross-system reconciliation works without translation tables.
How are refunds modelled?
A refund is a row with status=refunded and the same id as the original — the amount can be negative or positive depending on your ledger convention. The template does not enforce either; pick one per workspace.