CSV import and export

Open Import / export. Export produces a UTF-8, spreadsheet-friendly CSV of positive-quantity items for all games or a selected game. It is a collection interchange format; it is not a complete server backup.

Recommended workflow

1. Export a small existing collection to obtain valid set and printing identifiers.
2. Preserve the column headers and leading zeroes in collector numbers.
3. Edit quantities and variant fields as needed.
4. Select the file and the import mode.
5. Choose Check file. Correct every reported error.
6. Choose Import, then verify quantities in Collection.

Checking a file is a dry run. It reports valid rows without importing them; the imported count stays zero in dry-run responses.

Format

game,set_code,collector_number,name,language,finish,condition,quantity,manual_price,notes
mtg,DOM,168,Llanowar Elves,fr,foil,NM,2,,
sorcery,001,abundance-b,Abundance,en,standard,EX,1,4.50,binder 2

These are the application's example rows; they require matching printings in the receiving server's imported catalog.

Column	Required	Interpretation
game	Yes	Installed game ID, such as mtg or pokemon-asia
set_code	Yes	Set code (case-insensitive), or stored external set ID
collector_number	Yes	Printed number, or external printing ID for games without one
quantity	Yes	Signed delta in add mode; absolute nonnegative quantity in set mode
name	No	Informational; it does not disambiguate the printing
language	No	Defaults to the printing's first language or en
finish	No	Defaults to the printing's first finish, otherwise provider default
condition	No	Defaults to NM; normalized to uppercase
manual_price	No	Nonnegative unit amount, at most two decimal places
notes	No	Up to 1,000 characters

Use the exact lowercase header names shown above. Commas, semicolons and tabs are accepted as delimiters; double quotes escape delimiter-containing cells in the normal CSV manner. UTF-8 BOM is accepted. Decimal commas are accepted in price fields, but must be quoted in comma-delimited files.

For Yu-Gi-Oh!, a printed number can correspond to several rarity printings. If set and collector number match several entries, import is refused; exporting the stored external printing identifier can resolve the ambiguity. Name and finish do not serve as a second-stage lookup discriminator.

Import modes

Add quantities to my collection (add): positive quantities add copies; negative quantities remove copies; zero is invalid. Importing the same positive file twice adds it twice.

Replace quantities of listed items (set): each listed variant is set to the specified quantity, including zero. Unlisted items remain unchanged. This is not a full replacement of the collection.

Avoid duplicate rows for the same variant. Add mode applies every delta; set mode processes rows in order, so later quantities can supersede earlier ones.

Blank manual price or notes cells do not clear existing values during import. Use the item editor or PATCH API to clear them. A nonblank imported price or notes value updates the resulting item.

Validation and limits

• Maximum upload: 5 MiB (5 × 1,024 × 1,024 bytes).
• Maximum rows: 50,000.
• Quantity magnitude: at most 100,000 per CSV row.
• Manual price: less than 10,000,000,000 with no more than two decimal places.
• Notes: 1,000 characters maximum; NUL characters are rejected.
• The API reports at most 200 row errors.

The full file is validated before mutations. Any parse or validation error imports nothing. If a stock conflict occurs during application, the transaction is rolled back. Dry-run validation does not guarantee that a later removal will succeed: current stock can change between checking and importing.

Text resembling a spreadsheet formula is prefixed with an apostrophe on export; Zukan removes that protective prefix when reimporting. Preserve collector numbers as text to prevent spreadsheet conversion.

What export does not contain

Accounts, sessions, source configuration, stock transaction history, full catalogs, price history and images are not included. Use Backup and restore for disaster recovery.

Implementation references

• backend/app/services/csv_io.py
• backend/app/api/collection.py
• web/src/pages/ImportExport.tsx