Toolkite

How to Convert JSON to CSV When Your Data Won't Cooperate

Oct 9, 2026 · AI-assisted

You paste a JSON payload into a converter, hit the button, and the CSV comes out with [object Object] in half the columns. Or the header row looks fine but every nested field is just... gone. If that's where you are, the problem usually isn't the converter — it's the shape of the JSON you fed it.

Most JSON that comes out of an API is nested. CSV is flat. Something has to give, and the tool has to decide how to flatten it. Here's how to figure out what's actually breaking and fix it without uploading your data anywhere.

Why Your JSON to CSV Conversion Is Breaking

There are four failure modes I see over and over, and they each look different in the output.

1. Nested objects become [object Object]. This happens when the converter treats a nested object as a single cell value. JavaScript stringifies it, and you get that useless label. The data isn't lost — it just wasn't flattened.

2. Arrays collapse into one cell. If your JSON has "tags": ["red", "blue", "green"], a naive converter writes red,blue,green into one column. That's fine for reading, terrible for filtering in Excel or loading into a database.

3. The header row is wrong. Sometimes the first object in your array has different keys than the rest. If the converter only looks at the first item to build headers, later fields silently disappear.

4. The file is too big and the tab froze. Browser tools have memory limits. If you're pasting a 40MB payload into a free tool, the tab will hang before you ever see a result.

None of these are mysterious once you know which one you're hitting. The fix is the same in every case: flatten before you export.

The Fix: Flatten First, Then Convert

Toolkite's JSON ↔ CSV Converter runs entirely in your browser using PapaParse and SheetJS. Nothing gets uploaded. That matters if your JSON contains customer records, API keys, or anything you'd rather not send to a random server.

Here's the workflow that actually works:

  1. Paste or drop your JSON. You can paste it directly or drop a .json file. The free tier handles files up to about 25MB.
  2. Pick your direction. JSON→CSV, CSV→JSON, or JSON→Excel (.xlsx) if you're handing the file to someone who lives in spreadsheets.
  3. Let it flatten nested structures. On the free tier, nested JSON flattens up to 10 levels deep. That covers the vast majority of API responses — things like user.address.city or order.items[0].sku.
  4. Download or copy the result. No account, no email, no waiting.

If your JSON is deeper than 10 levels or you're converting a batch of files at once, the optional Pro tier ($9.99 one-time) raises the file cap to 50MB, does deeper flattening, and handles up to 10 files in a batch. It also adds custom delimiters and an API URL fetch option. For most people converting one payload at a time, the free tier is enough.

What "flattening" actually produces

Say your input looks like this:

{
  "id": 42,
  "customer": {
    "name": "Dana",
    "address": { "city": "Austin", "zip": "78701" }
  }
}

A flattened CSV gives you columns named id, customer.name, customer.address.city, and customer.address.zip. That dotted-path convention is the same one most data tools use, so it round-trips cleanly if you later need to un-flatten.

Arrays are the trickier case. If you have an array of objects inside a record, you have two honest choices: explode it into multiple rows (one row per array item, repeating the parent fields), or join the values into a single delimited cell. Which one you want depends on whether you're going to pivot the data later. If you're loading into a database, explode. If you're sending a summary to a client, join.

Edge Cases That Trip People Up

Mixed types in one field. If price is sometimes a number and sometimes the string "N/A", CSV doesn't care — it's all text once it's written. But Excel might reformat your numbers, strip leading zeros from zip codes, or turn 1-2 into a date. If that matters, export to .xlsx instead of .csv, or open the CSV in a text editor first to confirm the values are intact.

Unicode and emoji. CSV is plain text, so this usually just works. If you see é instead of é, your spreadsheet app opened the file with the wrong encoding. Re-import it and specify UTF-8.

Empty arrays and nulls. A field that's null becomes an empty cell. A field that's [] may become an empty cell or an empty string. Neither is wrong, but if you're doing downstream validation, decide which one you want and check the output before it hits production.

Very wide objects. If your JSON has 200 keys, you'll get 200 columns. That's correct but unreadable. Consider trimming the payload before conversion — most of the time you only need a handful of fields anyway.

Prevention: Stop the Problem Before It Starts

A few habits save a lot of back-and-forth:

  • Inspect the JSON shape first. Paste it into a formatter or just look at the first record. If you see { inside a value, you have nesting and you'll need flattening.
  • Decide on your column naming convention up front. customer.address.city vs customer_address_city vs city — pick one and stick with it, especially if this is a recurring export.
  • Test with a small slice. Convert the first 5 records before you run the full file. If the headers look wrong, you'll know in seconds instead of minutes.
  • Keep the original JSON. CSV is lossy by nature. Don't delete the source until you've confirmed the CSV has everything you need.

If you're also generating test payloads to try this against, the mock data generator can produce realistic nested JSON in the browser without an account. And if you're cleaning up text fields before or after conversion, text tools handle the boring stuff like trimming and removing empty lines.

When a Browser Tool Isn't the Right Answer

I'll be straight with you: if you're converting JSON on a schedule, or the payloads are hundreds of megabytes, a script is the better tool. jq and Python's pandas.json_normalize are both excellent for this, and they'll run headless in a pipeline.

But for one-off conversions — a client sent you an API dump, you need to open it in Excel, you don't want to install anything — a browser tool wins on time-to-result. And when the data is sensitive, keeping it on your machine instead of uploading it to a server is the whole point. Toolkite's privacy page spells out the details; the short version is that conversion happens locally and nothing is stored server-side.

The rule of thumb: script it if it's recurring, click it if it's a one-time thing, and always flatten before you export.

FAQ

Why does my JSON to CSV conversion show [object Object] in some columns?

That means the converter treated a nested object as a single value and stringified it. The data is still there — it just wasn't flattened into separate columns. Use a converter that flattens nested JSON (Toolkite's free tier goes 10 levels deep) and you'll get proper dotted-path column names instead.

How do I handle arrays inside my JSON when converting to CSV?

You have two options: explode the array into multiple rows (one row per item, repeating the parent fields) or join the values into one delimited cell. Explode if you plan to filter or load into a database; join if you just need a readable summary. The right choice depends on what happens to the CSV next.

Is it safe to convert JSON with customer data using an online tool?

It depends on the tool. Anything that uploads your file to a server is a risk. Toolkite's converter runs entirely in your browser using PapaParse and SheetJS, so the file never leaves your device. That's the main reason to prefer a client-side tool for anything sensitive.

What if my JSON file is too large for the free converter?

The free tier handles files up to about 25MB. If you're past that, the optional Pro tier raises the limit to 50MB and adds batch conversion for up to 10 files. For very large or recurring jobs, a command-line tool like jq or a Python script is usually the better fit.

Why did my zip codes lose their leading zeros after conversion?

That's Excel, not the converter. Spreadsheets auto-detect numeric-looking strings and reformat them. Export to .xlsx instead of .csv, or import the CSV with the column set to text format. The underlying data is correct — the display is what changed.

Can I convert JSON directly to Excel instead of CSV?

Yes. Toolkite's converter supports JSON→Excel (.xlsx) alongside JSON→CSV, which avoids the encoding and number-formatting quirks that come with CSV. If you're handing the file to someone who lives in spreadsheets, .xlsx is usually the smoother choice.