1. Purpose
Teach Shipsidekick a second SKU for a product that already exists, so that a supplier's code, an older code or a marketplace's code finds the right item instead of returning nothing. Covers where to add it, which screens honour it, and which ones do not.
2. Scope
Adding, reading and removing SKU aliases on a product variant. Barcode aliases and bulk identifier loading are covered in SWI-027. Reading a catalogue where several listings already share a SKU is covered in SWI-024, and that is a different situation: those listings link on their own and need no alias.
3. Roles & Responsibilities
Role | Responsibility |
|---|---|
Brand or catalogue owner | Owns the SKU scheme and confirms that two codes genuinely mean the same item |
Operations lead or 3PL admin | Adds the alias on the variant that holds the stock, and checks it resolves |
Support | Confirms which variant is primary or standalone before an alias is added |
4. Key concept — an alias covers what a person types, not what a handheld reads
An alias is not a second SKU everywhere in the product. It is honoured on some lookups and ignored on others, and the split is not visible on screen. This table is the reason this document exists.
Where the code is entered | Does an alias match? |
|---|---|
Product search boxes in the app, including the picker that adds a line to a purchase order, a kit or a mission | Yes |
Products CSV upload | Yes |
Orders CSV upload | Yes |
Bundle components named inside a Products CSV upload | Yes |
Handheld scanner | No. The scanner reads the SKU, the barcode and barcode aliases only. Give the item a barcode alias instead, per SWI-027. |
Purchase order line item CSV upload | No. That upload matches the SKU column alone, so a file of supplier codes still has to be translated before it is uploaded. |
Bundles CSV upload | No |
Inventory adjustment CSV upload | No |
The short version is that an alias fixes searching and most spreadsheet work, and does nothing for the warehouse floor. A code that has to work on a handheld needs a barcode alias, not a SKU alias, and the two are separate lists on the same variant.
5. Procedure — add the alias
Go to Products in the left navigation and click Variants at the top of the table.
Search for the SKU that the catalogue already holds, which is the one carrying the stock. If several listings share it, open the one badged Primary. See SWI-024.
Open the variant.
Next to the SKU field, click Add aliases. Once a variant has some, the same button reads as a count instead, such as 2 aliases.
In Add New Alias, type the other SKU in full, spelled and capitalised exactly as it appears on the paperwork you want to match.
Click Add Alias. It appears as a chip under Current Aliases.
Repeat for any further codes that mean the same item, then save the variant.
Enter, comma and space all commit the alias as well as the button, which means a SKU containing a space cannot be typed here. Aliases are single tokens.
If the alias is refused, the message names the reason. An alias another primary variant already covers is refused outright, because two products can never both answer to one code. An alias that matches another primary's own SKU opens a warning first, because accepting it makes that other variant point at this one. Confirm that only when the two really are the same item.
6. Procedure — remove an alias
Open the variant and click the aliases button next to the SKU field.
Under Current Aliases, click the x on the chip.
Confirm if you are asked to, then save the variant.
Removing an alias can hand that code back to another variant, so the confirmation is worth reading rather than clicking through. Anything that was resolving through the alias stops resolving as soon as the variant is saved.
7. Verification
The alias appears as a chip under Current Aliases on the variant.
Typing the alias into a product search box returns the product, and the row that comes back carries the catalogue's own SKU rather than the alias.
The alias resolves to one product only. If two come back, the same code has been added in more than one place and one of them is wrong.
A code that has to work on a handheld is tested by scanning it, not by searching it. A SKU alias will not answer.
8. Constraints and caveats
Aliases can only be set on a primary or a standalone variant. Adding one to a variant that is linked to a primary is refused, and the message names the primary to use instead.
Alias matching in search is exact and case sensitive, unlike the SKU itself, which matches on part of the value and ignores capitalisation. A partial alias, or the right code in the wrong case, returns nothing.
One code can only ever resolve to one product. An alias already covered by another primary variant is refused rather than shared.
Aliases are added rather than replaced when they arrive by CSV, so a file can be re-run safely and a large mapping can be split across several uploads.
An alias does not change the SKU. Reports, exports and the store listing all continue to show the catalogue's own SKU, which is the intended behaviour and not a sign the alias failed.
Aliases cannot contain a space.
Adding an alias does not backfill anything. Records that already failed to match, such as a purchase order line that was never added, are not repaired by adding the alias afterwards.
9. Worked example
A 3PL onboards a brand whose catalogue arrives from a connected store, then keys the brand's supplier purchase orders in by hand. Several lines cannot be found in the product picker at all, and the operator reports them as missing from the catalogue.
Observation | Reading |
|---|---|
A code from the supplier sheet returns nothing in the picker | The catalogue holds the item under a different code. The store's scheme and the supplier's scheme were built separately, and neither side is wrong. |
Searching the product name instead returns the item immediately | Confirmation that the product exists. Only the code is unmatched, so nothing needs creating. |
Some sizes of one product line use one code shape and others use another | Common where a listing has been rebuilt over time. The catalogue is the source of record for what a code means here, whatever the supplier's sheet says. |
The supplier code is added as an alias and the picker then finds it | Working as intended. The line can be keyed from the supplier's own paperwork from then on. |
A CSV of supplier codes is uploaded to the purchase order and still rejects every row | Expected. The purchase order upload matches the SKU column only, per section 4. The alias serves the picker, not that file. |
The same supplier code is scanned at the pack bench and finds nothing | Expected. The scanner does not read SKU aliases. That code needs a barcode alias, per SWI-027. |
Resolution: the aliases go on the primary or standalone variant for each item, which makes every later purchase order keyable straight from the supplier's paperwork. The codes that also have to work on a handheld are added a second time as barcode aliases.