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 assistant icon in the page title if you want AI assistant 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, startup requeues interrupted work and schedules waiting jobs. Work commits in 250-row checkpoints; each checkpoint's Stock, Reference facts, import provenance and opening balances commit together. Earlier checkpoints remain committed if later work fails. Review the error report and validate the file again when a job has failed terminally.

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)
  • stock_internal_notes (operator-only; 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 records you independently reviewed against Discogs. 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.

Discogs Collection CSV

A manually downloaded Discogs Collection CSV has a dedicated profile at Control Centre → Discogs tools → Import Collection. Upload the unmodified provider export: the server maps its supported columns, generates one copy-safe SKU per row, fixes the Reference fact source to Discogs, and forbids Stock group creation. The profile requires Release ID, Date Added, Artist and Title; it composes Artist — Title as the merchant-facing Stock name while retaining Artist and Release Title as separate Reference facts. Validation blocks malformed or duplicated copy identities instead of guessing.

The profile accepts up to 50,000 data rows within a 50 MB UTF-8 file. New rows open with quantity 1 at the selected default Location + Bin, or at an optional explicit destination mapped from their CollectionFolder. Unmapped folders use the default. Repeat imports may update mapped names, Internal notes and Discogs Reference facts, but preserve existing Stock quantity, location and active status. Rows missing from a later CSV are never deleted or deactivated. ChannelWeave remembers which source row belongs to each imported Stock item only to make deliberate repeat imports safe; this does not create a Discogs account connection or live synchronisation.

Validation separates added, changed, unchanged and absent source copies. Unchanged source fingerprints skip Stock writes and edit events; absent copies are informational only. Execution commits 250-row checkpoints with visible progress, so a retry can continue safely after interruption without duplicating already imported Collection copies. Earlier checkpoints remain committed if a later one fails.

The normal Inventory → Data exchange → Import stock items CSV page remains the provider-neutral path for a CSV already prepared with ChannelWeave column names.

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 assistant icon updates after validation. When blocking errors or warnings are present, AI assistant 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 AI assistant from the modal, the AI assistant 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 stock 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 in Stock catalogue, open Stock groups when the import created groups, or return to Data exchange.
  • If imported products still have no default listing description, choose Draft missing descriptions with the AI assistant. This is a separate, optional step: the deterministic import completes first, then AI assistant drafts up to 100 channel-neutral descriptions from the imported Stock facts.
  • 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.

Draft missing descriptions with AI

The post-import AI assistant action is available only to a user who can both import and manage Stock. It considers only Stock rows recorded as exact members of that completed import result and skips products that already have a description. Existing descriptions are never replaced.

Every successful import entry in Inventory → Data exchange → Activity keeps a Review AI descriptions action, including while its queue is empty. This is shared Stock-import behaviour and is not limited to Discogs files.

For Discogs Collection imports, Control Centre → Discogs tools retains a Review AI descriptions action for the latest completed Collection import. The action remains available before any candidates have been generated; the empty review page offers Continue drafting when eligible blank descriptions remain.

Generated descriptions are stored in a separate review queue, not on the Stock product. Before drafting, ChannelWeave prepares a buyer-visible fact set: it leaves out internal SKUs and units of measure, source-only identifiers and URLs, blank or placeholder values, unknown release-year sentinels, and a duplicate release title. Fact labels and values are bounded before they enter the prompt. It also removes Discogs numeric artist and label disambiguators wherever they occur, including before delimiters, and drops placeholder entries embedded in label or catalogue-number lists. Recognised Discogs format shorthand is expanded into plain wording. Comma, semicolon and plus delimiters are normalised, and repeated media such as LP + LP become Double LP. Picture-disc and marbled-vinyl shorthand is expanded, while colour and heavyweight-vinyl values remain edition details rather than being mistaken for additional media. AI assistant then targets one concise plain-text paragraph of two to four sentences and does not pad a sparse record with generic claims.

Every returned draft passes deterministic structural and catalogue checks before it reaches the review queue. These checks enforce the exact product title, required format facts, core artist/date/label/catalogue-number/condition roles, and known unsafe or awkward wording. They reduce common mistakes but are not a semantic proof that every sentence is correct, so human review remains required. If the first answer fails these checks and the catalogue facts support a complete sentence plan, ChannelWeave uses that independently validated plan instead of waiting for another model response. The plan supports coordinated labels containing punctuation and releases supplied across multiple media, such as an LP with a CD. Otherwise ChannelWeave makes one corrected drafting attempt. A second rejected answer fails safely for retry and is never offered as review-ready copy.

Open Review AI descriptions to compare each draft with the exact Reference facts supplied to the AI assistant, then edit the text if needed. Choose Accept description to save one reviewed value to Stock, select several drafts and choose Accept selected, or skip drafts you do not want. Both individual and bulk acceptance submit the current textarea value. ChannelWeave keeps the original AI-generated copy immutable and records the accepted reviewed copy separately. Background polling does not replace the list while a draft editor has focus, so in-progress edits and the caret are preserved.

Accept selected and Skip selected appear only while at least one ready draft is selected. Select ready drafts on this page remains available when the selection is empty.

The Outstanding count shows the complete unfinished workload for that import: eligible blank descriptions not yet drafted, drafts being generated, drafts ready for review and drafts needing attention. The separate Ready to review count shows the generated drafts awaiting a decision. Accepted, skipped and already-described items are not included.

While a batch is active, the review page refreshes its summary and rows every two seconds. A transient polling failure is shown on the page and retried after the same delay, so the user does not need to reload the review queue. A persistent status strip distinguishes Ready to start, Drafting in progress, Batch complete, Drafting paused and completion of all eligible description work. Each Continue drafting action queues at most 100 outstanding items, retrying failed drafts first and then filling the batch with eligible descriptions not yet drafted. The action is unavailable while any draft is queued or generating.

Each review-ready candidate also preserves the exact product title used for generation and an optimistic fingerprint of that title plus the raw first 24 Reference fact rows. Acceptance rechecks that source input and the Stock description. If the title or source facts changed, the description is no longer blank, or the candidate is no longer ready, ChannelWeave reports a conflict and writes nothing. This keeps concurrent corrections authoritative rather than accepting stale copy or overwriting a newer description.

Each run queues at most 100 products so large imports stay bounded. Finish or review that batch, then choose Continue drafting for the remaining blank descriptions. Failed drafts are prioritised and the remaining batch capacity is used for the next blank descriptions. Failed drafts remain visible until retried or skipped. If processing is interrupted, ChannelWeave safely returns stalled work to the queue after five minutes without duplicating a draft that is still active.