Document / Drive Importer

When to use documents

Use **/import/document** when the catalog already lives in a file: supplier CSV, a JSON dump from another PIM, or a PDF spec sheet you need parsed into rows. Documents join the **same** products + variants tables as URL ingest. You do not get a parallel “document catalog.”

Supported formats

• CSV — UTF-8, header row required
• JSON — array of product objects or a wrapped { "products": [...] }
• PDF — text extraction; expect to review rows (PDFs are not a database)

Upload cap is **10MB**. MIME and size are checked before parse. Executables and HTML disguised as CSV are rejected.

CSV columns

Aim for headers the importer can map without guesswork:

• title (required)
• sku (required per sellable row; variants can share a parent via parent_sku or similar grouping)
• price, currency
• quantity / stock
• image_url or images (pipe- or comma-separated)
• color, size (or a single options column)

If your supplier uses item_name instead of title, rename the column before upload or expect a mapper miss in the job log. After the job completes, open the catalog and spot-check three SKUs.

Google Drive

Paste a **public** Drive share link. eListSync fetches the file after host allowlisting. Unsafe hosts, file://, and private IPs are rejected the same way as scraper SSRF.

Do not paste a Drive link that requires a Google login the server does not have. Make the file “anyone with the link” or download and upload the file directly.

Background jobs

Accepted documents enqueue a BullMQ ingest job. The API returns quickly; rows appear as the worker parses. Large CSVs should be watched in Destinations/System telemetry if you run them in a shared environment.

Failed rows should not delete successful ones. Re-upload a corrected file for the misses; duplicate SKUs update the canonical product rather than creating twins when the importer can match SKU.

Limits and errors

• 10MB file cap
• Hobby still counts ingested products toward the monthly product cap
• PDF with only images and no text will yield an empty extract — use CSV
• Password-protected PDFs are not supported

See Troubleshooting if the job sits in retry (queue) or returns 401 (session).