Import stock items CSV

Import stock data with validation before committing changes.

Last updated:

Use this workflow to create or update stock in bulk from CSV.

Steps

  1. Open Inventory → Data exchange → Import stock items CSV.
  2. Use the Eden leaf in the page title if you want Eden opened with this page, the import docs, and suggested questions for the current validation state.
  3. Check the warehouse setup guard. Quantity imports need either an available default Location + Bin or CSV columns named location_code and bin_code.
  4. Upload your CSV file.
  5. Run validation. ChannelWeave creates a validation token for the exact file and options.
  6. Fix any errors. Use the downloadable error report when there are many row-level issues.
  7. Review the Ready to import summary. It repeats the item counts, Location + Bin destination, reference fact source, and new-group count before you commit.
  8. Preview and import. The import runs as a background job, shows progress, and is safe to poll with the same validation token. If a server restart or other interruption strands a job, ChannelWeave marks it failed so you can validate the file again instead of waiting forever. The final write is atomic: stock groups, stock products, stock items, reference facts, and opening balances commit together or roll back together.

Helpful options

  • Update existing items by SKU
  • Create missing stock groups during import
  • Reference fact source for reference_fact[...] columns. Choose Data Exchange, Discogs, or Manual. This does not change the inventory movement source.
  • Permission: users need the stock-import permission before they can open the page or call the import APIs.

Supported fields

Common import columns include:

  • sku (required)
  • stock_name (product title, required; no import length cap)
  • stock_description (no import length cap)
  • unit_of_measure (max 64 characters; new stock defaults to the customer base unit when the column is omitted or blank; validation fails if no default stock unit is configured)
  • unit_of_issue
  • group_code (max 32 characters), group_name (max 64 characters), and group_description (max 2,000 characters)
  • location_code (max 16 characters)
  • bin_code (max 10 characters)
  • quantity_on_hand
  • reorder_level and reorder_quantity
  • is_active
  • internal_barcode (max 200 characters), manufacturer_barcode (max 64 characters), and manufacturer_barcode_format
  • weight_kg and volume_m3
  • cost_price, sale_price, and tax_code

Numeric values must use a dot for decimal places and must not include thousands separators. Ambiguous comma values such as 1,5 or 1,000.00 stop validation with a clear error instead of being guessed. Quantity, reorder, cost, and sale price fields allow up to four decimal places; weight allows four; volume allows six.

Reference facts

Use reference_fact[Name] columns when you want catalogue facts kept with the stock item for later listing preparation.

For example:

  • reference_fact[Format]
  • reference_fact[Catalog#]
  • reference_fact[Release year]

Each non-blank value is saved under Stock item → Reference facts with the selected Reference fact source. Leave the source as Data Exchange for a plain spreadsheet import, or choose Discogs when the catalogue facts came from a Discogs collection export. Existing facts with the same source and name are updated; facts from other sources are left alone. Reference fact names are kept to 200 characters and values are kept to 2,000 characters.

If validation detects a Discogs-style reference fact such as reference_fact[Discogs Release ID] while the source is still Data Exchange, the page suggests switching the source to Discogs and re-validating.

Blank values clear standard optional stock fields when the column exists in your CSV. Blank reference_fact[...] cells are skipped so they do not delete saved reference facts. Leave a column out entirely when you do not want that field changed. Values longer than a documented maximum length stop validation with a clear error; ChannelWeave does not trim them silently during import.

When quantity_on_hand is present, ChannelWeave records the imported quantity through the warehouse inventory ledger. Choose a default Location + Bin in Step 2, or include both location_code and bin_code columns in the CSV for per-row destinations. The imported quantity appears in Stock history as a Data Exchange opening balance or quantity update rather than a stock-only summary edit. The page shows this setup requirement before validation and keeps Validate file disabled until a default destination is selected or the CSV contains both destination columns.

Validation checks

Typical checks include:

  • The user has permission to import stock
  • Required fields are present
  • Product title is supplied in the stock_name column
  • Numeric values are valid
  • New stock can resolve a base unit of measure from unit_of_measure or the customer default
  • Quantity imports can be assigned to a stock Location + Bin
  • Duplicate SKUs are handled
  • SKU policy rules are respected
  • Barcode policy rules are respected
  • Stock group references can be resolved or created when that option is enabled

Validation results show blocking errors before warnings, so the issue that stops the import is visible even when many non-blocking warnings are present. Repeated row warnings are grouped by message, with row counts, so one repeated policy warning does not hide a different issue. Use the downloadable validation report when you need the complete row-by-row list.

The Eden leaf updates after validation. When blocking errors or warnings are present, Eden opens with a clean input and suggested questions based on the file summary, Location + Bin destination, Reference fact source, and first grouped validation issues. Pick a suggestion to ask whether a warning blocks import, what to fix first, or whether the import settings look safe. If you open full-page Eden from the modal, Eden shows Back to Import stock.

Warnings remain non-blocking when the validation result shows 0 blocking errors. For example, the active barcode-policy warning for manufacturer_barcode means manufacturer barcodes can improve later scanning or catalogue matching, but it does not stop a Discogs collection import from using SKU and ChannelWeave-generated internal barcodes.

The preview table shows mapped CSV columns rather than a fixed set of fields. Defaulted values, such as Active = true when is_active is not supplied, are called out below the preview instead of being mixed into the CSV preview.

After import

  • Review the progress card until the background import job completes
  • If you close and reopen the page while an import is running, the browser re-attaches to the remembered job and resumes the progress card.
  • If the same CSV and options were already imported, ChannelWeave shows the original import date and keeps Import stock disabled rather than replaying a fresh success.
  • Download the error report if validation or execution fails
  • Use the success actions to review results on Stock items, open Stock groups when the import created groups, or return to Data exchange.
  • Check Data exchange activity for run history
  • Open a stock item or stock group detail to see Data Exchange create/update provenance in Record change history; quantity changes remain in Stock history.
  • Spot-check a few updated items before relying on downstream listings or purchase orders

ChannelWeave keeps the uploaded CSV payload only while a queued or running job needs it. Once the job reaches a terminal state, the job retains its summary and error report but purges the CSV text.