1. Purpose
Explain how to load barcodes and other product identifiers onto SKUs that already exist, in one upload, using the Products CSV. Covers which column a GTIN belongs in, how to build the file from your own catalogue, and what happens when an identifier is already in use.
2. Scope
Covers assigning identifiers to existing products through the Products CSV upload. Uploading bundles and their components is covered in SWI-013. Reading and configuring primary and linked variants is covered in SWI-024. Creating products by hand is not covered here.
3. Roles & Responsibilities
Brand or catalogue owner: supplies the identifiers and owns which code belongs to which SKU.
Operations lead: runs the upload and resolves any rows the upload rejects.
Support: confirms which identifiers are already populated before the job starts.
4. When you need this
Barcodes are being introduced to a catalogue that was built without them.
Scan to pack, or any scanner step, needs codes on SKUs that do not have them.
A retail or marketplace channel has issued GTINs that must be matched to existing SKUs.
A supplier has changed the code on a product and a batch of SKUs needs updating together.
5. Key concept: GTIN is a family of codes, and barcode is where it goes
What people assume | What actually happens |
|---|---|
There is a GTIN field to fill in. | There is no field called GTIN. A GTIN goes in the barcode column, which is the code the scanner reads. UPC and EAN are simply GTIN formats, and each has its own column if you want the value stored separately as well. |
An upload needs every column filled in. | Only sku is required to update a product that already exists. A file with two columns, sku and barcode, is a complete and valid upload. |
A blank cell wipes the existing value. | Blank cells are ignored. Anything you leave empty keeps whatever it already had. |
An upload replaces the catalogue. | Rows are matched on SKU and updated in place. A SKU that is not already there is treated as a new product, and only then does it need a name. |
One SKU can only carry one code. | A SKU carries one primary barcode plus any number of barcode aliases, which is where older codes, secondary codes, and supplier or carton codes for the same item belong. |
Many codes for one SKU means many rows. | It is the opposite. Aliases are a list inside a single cell, so many codes for one SKU is one row with the codes separated by semicolons. One row per code would overwrite itself all the way down the file. |
Uploading aliases replaces the ones already there. | Aliases are added to what the SKU already holds, and duplicates are dropped. That is what makes it safe to upload in batches and to re-run a file after correcting it. |
6. Procedure — export, fill in the identifiers, upload
Open Products from the dashboard menu.
Click Actions, then Export All Products. The file that downloads uses exactly the same columns the upload expects, so your SKUs are already filled in and nothing has to be typed twice.
Open the file and format the sku column as Text before you do anything else, so that any SKU beginning with a zero keeps it.
Fill in the barcode column against each SKU. Use the upc, ean, isbn, or asin columns as well if you want those values stored separately.
Put any older or secondary codes for the same SKU in barcode aliases, separated by semicolons.
Delete every column except sku and the identifier columns you filled in. This is optional, and it makes the file quicker to check.
Save as CSV.
Back on the Products page, click Actions, then Upload Products.
Choose the file and upload it.
If you would rather start from an empty file than from your catalogue, the upload window has a Download CSV Template button that gives you the same columns with sample rows in them.
6A. Mapping many codes onto one SKU
This is the common case when cartons, cases, or a supplier's own labels each carry their own code but all resolve to the same item you hold. A list of codes usually arrives one code per row, and it has to be reshaped before it will upload.
The file wants one row per target SKU, not one row per code. Put the SKU in the sku column, and every code that belongs to it in the barcode_aliases column of that same row, separated by semicolons and no spaces. A row can hold as many codes as you need.
Leave the barcode column out of the file entirely when you do this. That column holds a single code, so a list of codes cannot go in it, and including it risks overwriting the code the SKU already scans by.
Because aliases are added rather than replaced, a large mapping can be split across several uploads, one product line at a time, and a file can be corrected and re-run without undoing what already landed.
7. Verification
The upload reports how many rows it processed, and lists any it could not.
Open two or three of the SKUs you updated and confirm the barcode now appears on the variant.
Scan one of the new codes at a pack bench or on a handheld and confirm it finds the right product.
If a row was rejected, the message names the SKU and the reason, so it can be corrected and re-uploaded on its own.
8. Constraints and caveats
You need full access to Products for the upload option to appear. Read-only users will not see it.
An identifier can only belong to one product at a time. If a code is already on another SKU, that row is rejected and names the SKU holding it, so the conflict has to be cleared before the code can move.
A rejected row stops only itself. Every other row in the file still goes through, so a file never has to be re-uploaded whole.
Blank cells never clear a value, and uploading aliases never removes the ones already held. Removing an identifier has to be done on the product itself.
Spreadsheet software strips leading zeros from any column it reads as a number, which silently corrupts both SKUs and barcodes. Format those columns as Text before saving, or edit the file in a plain text editor. GTINs are especially exposed to this, as many begin with a zero.
Aliases are stored trimmed and in capitals, so codes that differ only by spacing or case are treated as the same code and collapse into one.
SKUs are matched without regard to capitalisation, so a SKU typed in a different case from the one held in the catalogue still finds its product.
Where a warehouse system feeds the catalogue, it supplies its own GTIN into the barcode field, and a later sync can overwrite what you upload. Aliases are not fed by that sync, which is a further reason to keep mapped codes in the alias column.
9. Worked example
An apparel brand buying blank garments in bulk receives them in cartons whose labels each carry their own code for a specific style, colour and size, while the brand sells the goods under a single SKU per size. Hundreds of carton codes have to resolve to a dozen size SKUs.
Observation | Reading |
|---|---|
Hundreds of carton codes, but only a dozen SKUs to receive them against. | Roughly thirty codes per size, so the mapping is many to one and belongs in the alias column rather than the barcode column. |
The supplied list holds one code per row. | It has to be pivoted to one row per SKU, with that size's codes joined by semicolons, before it will upload. |
Half the SKUs already carry a barcode and half do not. | Loading the carton codes as aliases leaves the existing codes untouched, which the barcode column would not do. |
None of the SKUs hold any alias yet. | Nothing can be overwritten, so the upload can be run in batches, one product line at a time. |
The job comes down to reshaping the list from one code per row to one row per SKU, and a single upload. Scanning any carton label at receiving then pulls up the correct size, which is the point of the exercise: the warehouse scans what is printed on the carton in front of it, not what the brand happens to call the item.
10. Related documents
SWI-013 — Upload Product Bundles from a CSV
SWI-024 — Read and Configure Primary and Linked Variants