Amazon Flat File Explained

An Amazon flat file is not one template. It is a category specific workbook generated from Seller Central, and the version for Tools and Home Improvement is not the version for Apparel. Anyone offering a downloadable generic Amazon flat file is offering something that will fail on upload, which is why there is no download on this page.

What is worth understanding is the structure, because it is the same across every category and it explains almost every error the feed processing report will give you.

Where to get the current flat file

Seller Central, then Catalogue, then Add Products via Upload, then Download an Inventory File. Pick the product type that matches what you are listing, not the closest broad category.

Download it fresh each time. Amazon revises these templates without announcement, and an old copy produces validation errors naming columns that no longer exist, which sends people looking for a problem in their data that is actually a problem in their template version.

If you sell in more than one marketplace, download the template for the marketplace you are listing in. The UK and US versions of the same product type differ on required fields and on accepted values.

How an Amazon flat file is structured

Three header rows matter, and confusing them is the most common way to break the file before you have typed anything.

Row one carries the group headings, things like Basic, Discovery, Offer. Cosmetic, and safe to ignore.

Row two carries the field names Amazon actually reads: item_sku, external_product_id, feed_product_type. This row is the contract. It must not be edited, reordered or deleted.

Row three carries the human readable labels you work from: Seller SKU, Product ID, Product Type.

Data starts at row four.

Deleting row two because it looks like a duplicate of row three is the single most common way to break an Amazon flat file. The upload either fails outright or, worse, processes against the wrong columns.

Two tabs do the explaining. Data Definitions lists which fields are required for that product type and what each one means. Valid Values lists every accepted entry for every constrained field. A value that is not on that list fails, however sensible it looks, and this is where most of the time goes on a first upload.

The fields behind suppressed listings

A suppressed listing is worse than a rejected one. It uploads successfully, appears in your inventory, and does not appear to customers. Nothing has failed, so nothing tells you.

The usual causes are consistent.

Missing or invalid product identifier. external_product_id and external_product_id_type have to agree, and the identifier has to validate. A GTIN with a transposed digit passes the format check and fails the checksum.

Missing item_type_keyword. This maps the product into Amazon's own browse tree and is required in most categories. Without it the product exists and is not in any category a customer can browse to. It is not obviously important, and it is skipped constantly.

Image below the minimum. Amazon requires the main image on a white background, with the product filling most of the frame, and above the category's minimum dimensions. Undersized images suppress rather than warn.

Title over the category limit. Limits vary by category and the file does not enforce them. A title three characters too long suppresses the whole listing.

Missing required attributes for the product type. These are listed on the Data Definitions tab and change between template versions, which is another reason to download fresh.

Reading the feed processing report

The processing report is the diagnostic, and it is worth reading in full rather than scanning the error count.

It names the row and the field for each error, and it distinguishes errors from warnings. Warnings are the ones that produce suppressed listings, so they matter more than the label suggests.

Errors referencing a field you have left blank usually mean that field is conditionally required: required because of something else you entered. Variation fields behave this way, as do several of the compliance fields.

Fix and re-upload the whole file rather than a patch file. Partial uploads against a family that failed halfway create relationships that are harder to unpick than a clean re-run.

Parentage and variations

Variations use parent and child rows, and this is the part worth getting right first time because it is the hardest to undo.

A parent row has parentage set to parent, carries no inventory, no price and no barcode, and exists only to hold the family together.

Each child row carries parentage set to child, the relationship type (usually variation), the parent SKU, and the variation theme.

The variation theme must be one Amazon recognises for that category. SizeColor is valid in Apparel and meaningless in Industrial. The Valid Values tab lists the themes available for the product type you have downloaded.

The theme cannot be changed once the family is created. Changing it means deleting the family and rebuilding it, which loses the reviews and the sales rank attached to those ASINs. That is the single most expensive mistake in this file, and it is made at the point where somebody picks a theme without checking whether it is the one they will still want in a year.

Keeping a flat file workflow manageable

Three habits make the difference between a bad week and a routine job.

Upload ten products first. The processing report on ten rows is readable. The report on two thousand is a spreadsheet exercise of its own.

Keep the source data outside the flat file. The workbook is a delivery mechanism, not a place to hold a catalogue. Once product data lives in Amazon's template, the next template revision makes it stale, and every other channel needs its own copy.

Map rather than retype. Hold your product data in your own structure, with your own attribute names, and map it into whichever category template Amazon currently wants. The mapping is the real work, it has to be redone each time Amazon revises a template, and it is far cheaper to redo a mapping than to rebuild a catalogue.

Where this fits with other channels

Amazon is the strictest of the marketplace formats but not a special case. Every channel wants the same product described in its own vocabulary, with its own required fields and its own valid values, and each one changes on its own schedule.

Maintaining that channel by channel is how catalogue teams end up spending most of their time on reformatting rather than on the catalogue. Holding one governed record per product and generating each channel's file from it is the alternative, which is what SKULaunch does through marketplace syndication. Amazon still gets its flat file. Nobody types it.