Usermaven
Dark mode

Import conversions from a CSV

What you'll build: historical or offline conversions imported in bulk from a spreadsheet, previewed, validated, and deduplicated before a single row counts. Time: about 10 minutes plus file preparation. You'll need: a CSV file and permission to create integrations in Usermaven.

CSV import is the safe way to get conversions into Usermaven in bulk: when you're migrating from another tool, backfilling months of sales, or importing anything your systems can export but not send live. The flow is built so you always see what will happen before it happens.

File requirements

  • Encoding: UTF-8 (with or without BOM)

  • Delimiter: comma, semicolon, or tab

  • Header row: required, with unique column names

  • Size: up to 50 MB or 250,000 data rows

  • Timestamps: no more than 24 months in the past, no more than one hour in the future

email,user_id,anonymous_id,event_name,amount,currency,external_id,occurred_at
buyer@example.com,,,offline_sale,129.99,USD,deal_123,2026-07-01T12:30:00Z

You don't need every column, but you do need:

  • At least one identity column, email, user_id, or anonymous_id. If your website identifies users with a user ID, use the same one here for the strongest match.

  • A stable external_id an order number, deal ID, or transaction ID that never changes for that conversion. This is strongly recommended: it's what makes re-imports and overlapping files duplicate-safe.

A Download template button in the upload step gives you a correctly shaped starting point.

The import flow

  1. Upload. Go to Events → Event sources → New event source → CSV import,Enter a Source name, then upload your CSV file. Usermaven reads sample rows to detect your columns.

  2. Map fields. Point each Usermaven field at the right column: identity, event name, time (with format and timezone), revenue, currency, External ID, ad click IDs if you have them, and any custom attributes. You can add filters to import only rows that match a condition.

  3. Click Preview event to review how a sample row will be converted into a Usermaven event before continuing. See exactly how a sample row becomes a Usermaven event. Revenue transforms are available here, if your export has formatted amounts like $1,299.00, the Strip symbols transform cleans them up.

  4. Dry run. This step is mandatory, and it's your safety net. Usermaven validates the entire file and reports: Will import, Invalid, Filtered, and Duplicates, with a sample of the resulting events. Your mapping is frozen at this point, so what you approved is exactly what runs.

  5. Import. Rows are processed in resumable batches. If the import is interrupted, it resumes without re-importing rows that have already been processed.


image.png

When some rows fail

Invalid rows never block valid ones. After the import, download errors.csv from the imports tab, it lists each failed row's original line number and a plain-language reason. Fix those rows in your spreadsheet and upload again: with External IDs in place, the rows that already imported are recognized as duplicates and skipped, and only your corrections come through.

How duplicate protection works

  • With External ID mapped (recommended): Usermaven remembers every ID it has imported for this source. The same conversion can appear in any number of overlapping files and it will only ever count once.

  • Within a single file: duplicate External IDs (or identical rows when no External ID is mapped) are detected during the Dry Run, and only the first occurrence is imported.

  • Without External ID: protection is weaker, and Usermaven asks you to explicitly acknowledge that re-uploading overlapping rows can double count before it lets you import.

A note on historical attribution

Backdated events join the person's existing history, a sale imported from last quarter lands on the right person with their original first-touch attribution. What Usermaven won't do is invent history: if an imported event can't be tied to a known person or session, it still counts in your event and revenue totals, but person-level attribution for it may remain unavailable. That's honest data, not a bug.


Was this article helpful?