Exports Are Contracts
Every CSV download teaches customers what to expect next month. Inconsistent headers, mystery encodings, and Excel-breaking IDs create support tickets forever. Treat exports like a versioned API.
The Non-Negotiables
Ship these defaults unless a partner contract says otherwise.
- UTF-8 encoding (document BOM if you add one for Excel).
- Explicit delimiter (usually comma).
- Header row with stable, documented names.
- RFC 4180-style quoting for commas, quotes, and newlines.
- Content-Type: text/csv; charset=utf-8 plus Content-Disposition for downloads.
Headers and Column Stability
Never rename columns casually.
| Practice | Why |
|---|---|
| snake_case or documented CaseStyle | Predictable for scripts |
| Stable order | Positional importers do not guess |
| Additive changes only | New columns at the end when possible |
| Version query param or filename | orders_v2.csv when breaking |
| No duplicate headers | Parsers map the wrong fields |
Values: Nulls, Dates, Money, IDs
Ambiguity here is silent data corruption.
- IDs and postal codes as text (preserve leading zeros).
- Dates as ISO 8601 (YYYY-MM-DD or full timestamp).
- Decimals with . and no currency symbols or thousands separators.
- Booleans as true/false or 0/1—documented.
- NULL as empty field (or agreed token like \N for Postgres COPY).
Step-by-Step: Excel-Friendly Downloads
Customer-facing exports usually open in Excel first.
- Export UTF-8; consider BOM for Windows Excel users.
- Force text for long numeric IDs.
- Avoid formulas or leading = that Excel may interpret.
- Test open-in-Excel and open-in-Sheets before release.
- Offer XLSX too when formatting or multiple sheets matter (CSV to Excel).
API and App Implementation Tips
Server details that prevent 2 a.m. pages.
- Stream large exports; do not build multi-GB strings in memory.
- Filter and column-select in the query—do not dump SELECT * by default.
- Log export job IDs, row counts, and checksums.
- Rate-limit and authz-check who can export PII.
- Prefer async jobs + download links for huge reports.
HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="orders_2026-07-25.csv"Real-World Examples
Exports done right.
SaaS admin export
Column picker, UTF-8 BOM option, async email link for >100k rows, changelog when headers change.
Finance nightly file
Fixed schema, semicolon delimiter for EU bank, checksum sidecar file, SFTP delivery.
Developer-facing API
Comma UTF-8 no BOM, documented nulls, OpenAPI note on text/csv responses.
Common Mistakes
The classics.
- Locale-dependent delimiters without documentation.
- Changing header names between releases.
- Letting Excel "help" before the file leaves your pipeline.
- Embedding raw user text without quoting.
- Emailing multi-hundred-MB attachments.
Best Practices Cheat Sheet
Ship this with your runbook.
- UTF-8 + documented delimiter.
- Stable headers; version breaking changes.
- ISO dates; string IDs; plain decimals.
- Proper quoting; correct MIME headers.
- Stream large files; verify row counts.
Why Use Convert CSV Online?
Convert CSV Online is free, browser-based, and requires no account for everyday conversions. Validate sample exports in the Online CSV Editor, convert to Excel for stakeholder review, or reshape JSON API dumps to CSV before you codify the production exporter. Client-side workflows work on Windows, macOS, and Linux browsers.
Prototype the contract
Agree on a sample file first—then implement the exporter to match it exactly.
Conclusion
Great CSV exports are boring: stable headers, UTF-8, explicit delimiters, careful types, and honest MIME headers. Make the boring path the only path.
FAQ
What encoding should CSV exports use?
UTF-8. Add a BOM only when your Excel-on-Windows users need it—and document that choice.
How do I make CSV downloads open correctly?
Send Content-Type text/csv; charset=utf-8 and Content-Disposition with a .csv filename.
Should export headers ever change?
Avoid breaking renames. Add columns additively or ship a new versioned export.
How should dates appear in CSV exports?
Use ISO 8601 (YYYY-MM-DD or timestamps with timezone) to avoid locale ambiguity.
How do I export large CSVs?
Stream from the database or job worker, and deliver via download link instead of a single huge HTTP body when possible.
When should I export XLSX instead of CSV?
When users need multiple sheets, formatting, or typed columns that Excel constantly corrupts in CSV.
References
Convert your CSV in the browser
Preview, clean, and convert CSV files free with Convert CSV Online—no installation and no account required for everyday conversions.