Bulk import product costs (CSV)

You can update costs for hundreds or thousands of products in one upload instead of editing each product by hand. This guide covers the exact format, what each column does, and how to fix common errors.

Where to find it

1. Go to Products (sidebar → Products).
2. Click Bulk edit (CSV) in the top-right, or scroll to the bottom of the page and expand Bulk import product costs (CSV).

Download a starter file first

Two download options:

• Download sample — a tiny example file with 3 rows showing the expected format. Best for first-time users who want to see how it should look.
• Download my products — a CSV pre-filled with your current products, their current COGS, category, fulfillment, and shipping. Edit in Excel / Sheets, save as CSV, upload back.

Both files are UTF-8 with a BOM, so Excel opens them without mangling characters.

Required columns

You need one column from each group:

Product identifier (one of):

• sku_id — the TikTok product ID (preferred, most reliable match)
• tiktok_product_id — same as sku_id
• product_name — fallback if you don't have the SKU
• name — alias for product_name

Cost (one of):

• cogs — flat cost per unit in pounds (e.g. 4.25 or £4.25; the £ prefix is optional)
• cogs_pct — cost as a percentage of average sale price (0-100). Requires that the product has at least one sale already.

Optional columns

Any column we don't recognize is silently ignored — safe to leave internal columns in your own spreadsheet.

Header aliases — we're flexible

All of these are accepted and map to the same thing:

• Product Name, product_name, name, title, product
• SKU, sku, sku_id, product_id
• Cost, COGS, cogs, cost_per_unit, unit_cost
• Fulfillment, fulfillment_type

Headers are case-insensitive and tolerant of spaces vs underscores.

File format

• Encoding: UTF-8 (with or without BOM). If Excel asks, choose "CSV UTF-8 (Comma delimited)".
• Line endings: any of LF / CRLF / CR — all work.
• Quoting: RFC 4180. Wrap fields containing commas, quotes, or newlines in double quotes; escape inner quotes by doubling them ("").
• Comments: lines starting with # are ignored, so you can add notes to the top of your file.

Limits

• 5 MB max file size
• 10,000 max data rows per upload
• 100 most recent errors returned (we tell you the full count even if we truncate)

Over the limit? Split into multiple files and upload each.

What happens when you upload

1. We parse the file locally in your browser first and show a preview with detected columns and the first 15 rows.
2. You review and click Import.
3. We re-parse on the server, validate every row, and run a batched update (500 products per database round-trip).
4. You see a result: X updated · Y skipped · Z errors.

Skipped rows are rows that parsed fine but didn't match any product you own — not an error, just nothing to do. Errors are rows with invalid values (bad numbers, missing costs, out-of-range percentages).

Common errors and how to fix them

"CSV must include a product identifier column"

Add a column called sku_id or product_name and try again.

"CSV must include a cost column"

Add cogs (dollars) or cogs_pct (0-100) and try again.

"Row N: invalid number for cogs"

Check for typos — 4.2o (letter O instead of zero), random letters, or European decimals (4,25 instead of 4.25). Our parser rejects ambiguous commas because 1,23 could be either "one hundred twenty-three" or "one point two three".

"Row N: cogs_pct must be between 0 and 100"

Use 35, not 0.35, for 35%.

"Row N: no average sale price yet — can't compute cogs from a percentage"

The product hasn't had any sales yet, so we can't calculate a dollar cost from a percentage. Use a flat cogs value instead.

"File appears to be UTF-16"

Re-save from Excel as CSV UTF-8 (Comma delimited) — the other CSV option (UTF-16) produces a file we can't read.

Idempotent by design

Uploading the same file twice is safe. Nothing breaks, nothing duplicates — you just get the same final state. If you want to "undo" an upload, fix the values in the CSV and re-upload.

Dedupe behavior

If a product appears in multiple rows of the same file, the last row wins. We'll warn you in the result summary but won't fail the whole import.

Export → edit → re-import workflow

The typical power-user loop:

1. Download my products → get your current state
2. Open in Excel or Sheets, edit COGS
3. Save as CSV (UTF-8)
4. Upload — see "X updated" in the result

Works even if you add columns to your working copy (we ignore unknown columns).

Not supported

• .xlsx binary files — Save As CSV first
• Multiple sheets — one file, one dataset
• Formulas — stored as literal text, not evaluated
• European 1,50 decimals — ambiguous with thousand separators; use periods

Still stuck?

Email support@foregrade.app with the CSV attached (don't worry — it's only your product list, nothing sensitive). We'll tell you what's wrong and usually reply within a few hours on weekdays.