Feed format
JSONL
Newline-delimited JSON feed
A JSONL feed is one JSON object per line, each describing a single product, with no enclosing array. It is the only text format documented here that can carry nested values such as a variant dictionary, and it is read by streaming a line at a time rather than parsing the whole file.
Specification
- File extension
-
.jsonl.ndjson - Content type
- application/x-ndjson; charset=utf-8
- Compression
- Gzip, and OpenAI requires it: the file is submitted as .jsonl.gz.
- One product is
- One complete JSON object per line, separated by a newline, with no commas between them and no surrounding array. Attribute names are object keys, so unlike a delimited file each row carries only the fields it actually has.
- Escaping
- Standard JSON escaping applies inside each value, and every object must be on exactly one line, so any newline inside a string must be escaped as \n rather than written literally. Numbers that are really identifiers must be quoted as strings, or leading zeros are lost the moment the file is parsed.
A valid newline-delimited json feed
Two products, every required attribute, nothing omitted for brevity. Copy it and replace the values.
{"item_id":"SHIRT-BLK-M","title":"Northbound Oxford Shirt, Black, Medium","description":"A long-sleeved Oxford shirt in 100% brushed cotton.","url":"https://example.com/products/oxford-shirt?variant=101","image_url":"https://cdn.example.com/oxford-black.jpg","availability":"in_stock","price":"49.00 GBP","brand":"Northbound","seller_name":"Northbound","gtin":"05012345678900","group_id":"SHIRT-OXFORD","listing_has_variations":true,"variant_dict":{"Colour":"Black","Size":"Medium"}}
{"item_id":"SHIRT-BLK-L","title":"Northbound Oxford Shirt, Black, Large","description":"A long-sleeved Oxford shirt in 100% brushed cotton.","url":"https://example.com/products/oxford-shirt?variant=102","image_url":"https://cdn.example.com/oxford-black.jpg","availability":"out_of_stock","price":"49.00 GBP","brand":"Northbound","seller_name":"Northbound","gtin":"05012345678917","group_id":"SHIRT-OXFORD","listing_has_variations":true,"variant_dict":{"Colour":"Black","Size":"Large"}}Which channels accept it
| Channel | Support | Notes |
|---|---|---|
| OpenAI | Supported | Accepted gzipped as .jsonl.gz. Parquet is preferred for large catalogues. |
| Google Shopping | Not supported | Google takes text or XML files, with the Content API for programmatic updates. |
| Meta | Not supported | Meta takes CSV, TSV, XML or Google Sheets. |
| Microsoft Advertising | Not supported | Microsoft takes tab-delimited text or XML. |
| Not supported | Pinterest takes CSV, TSV or XML. |
What breaks a newline-delimited json feed
Pretty-printed JSON is not JSONL
The format depends on one object per line, so any JSON encoder configured to indent its output breaks it. This is easy to do by accident and produces a file that is valid JSON in spirit and unreadable to a line-based parser.
Identifiers must be quoted strings
A GTIN written as a bare number in JSON is a number, and 05012345678900 becomes 5012345678900 when parsed. Quoting every identifier is not optional, and it is the mistake that survives longest because the file looks correct until something reads it.
Missing keys and null are different statements
Because each object carries only its own fields, omitting a key says nothing about the attribute while sending null explicitly says it has no value. Some consumers treat the second as an instruction to clear the field, so the choice should be deliberate rather than whatever the encoder does with empty values.
Nested values need a schema decision, not just a mapping
JSONL can carry a variant dictionary or a list of images as real structure, which is its advantage over a delimited file. It also means two generators can produce equally valid JSONL with different shapes, so the nested parts have to follow the channel's documented schema exactly rather than a reasonable interpretation of it.
Frequently asked questions
What is the difference between JSON and JSONL for a feed?
A JSON feed would be one array containing every product, which has to be parsed in full before anything can be read. JSONL is one object per line with no array, so a consumer can stream a catalogue of any size a line at a time.
Which channels accept a JSONL product feed?
Of the channels documented here, OpenAI, which takes it gzipped as .jsonl.gz. Google, Meta, Microsoft and Pinterest all expect delimited text or XML files instead.
How do I stop GTINs losing their leading zeros in JSON?
Quote them as strings. A bare number in JSON is parsed as a number, and every leading zero disappears at that moment regardless of what the file looked like.
Can a JSONL feed be pretty printed?
No. Each object has to occupy exactly one line. Indented output is the most common way a generator produces a file that looks like valid JSON and is not valid JSONL.
Errors this format causes
Related concepts
- Product feed A product feed is a structured file listing every item a shop sells, with one row per purchasable item and one column per attribute the destination understands. Sales channels use it to build their own copy of a catalogue, which is why a feed is a translation of a shop's data into another system's schema rather than an export of it.
- Variant-level feed A variant-level feed emits one row for each purchasable variant rather than one row per product, because sales channels treat every size, colour and material as a separately buyable item with its own price, stock and barcode. A Shopify product with four sizes in three colours is one product in the admin and twelve items to a channel.
Primary sources
Channel specifications change. These are the official documents this page is based on.