1. Purpose
To create or replace many product bundles in one pass by uploading a CSV, and to get the file shaped correctly the first time. The format is not the one most people assume, and guessing it produces bundles that look created but are wrong.
2. Scope
Covers bulk creation and replacement of assembly bundles through the CSV upload on the Products page. Does not cover building a single bundle by hand on a product record, production or make to order builds, or kitting jobs on the warehouse floor.
3. Roles & Responsibilities
Role | Responsibility |
|---|---|
Client or brand | Supplies the bundle list, and confirms which SKUs are genuinely live. |
Operator or 3PL admin | Shapes the file, runs the upload, and reads the error report. Requires full access to Products. |
Support | May run the upload on a customer's behalf when they are blocked, then sends this document so the next one is self serve. |
4. When you need this
Use it when onboarding a brand that sells kits, when a catalogue changes enough that bundles need rebuilding in bulk, or when a previous upload appeared to succeed but every bundle came out holding a single component.
5. Key concept: the bundle SKU column is a delimiter, not a label
This is the single thing that makes uploads fail, and it accounts for nearly every support ticket on this feature.
What people assume | What actually happens |
|---|---|
The bundle SKU column tells the system which bundle each row belongs to, so I repeat it on every row of that bundle. | A filled bundle SKU cell starts a brand new bundle. Repeating it on eight rows creates eight separate bundles, each holding one component. |
If I get the format wrong, the upload will tell me. | It will not. Repeating the bundle SKU is valid input, so the upload reports success. The damage is only visible later, on the product records. |
The first row just names the bundle. | The first row names the bundle and carries its first component. It is doing two jobs at once. |
So the rule is: name the bundle once, on its first row, then leave that column empty for every remaining component.
6. How the file must be shaped
Three columns, lower case with underscores, spelled exactly like this. Header matching is case sensitive, so Bundle SKU or BUNDLE_SKU will fail every row.
bundle_sku,line_item_sku,quantity
KIT-ALPHA,COMPONENT-1,1
,COMPONENT-2,2
,COMPONENT-3,1
KIT-BETA,COMPONENT-1,4
,COMPONENT-9,1
That file creates two bundles. KIT-ALPHA holds three components, KIT-BETA holds two. Note that COMPONENT-1 appears in both, which is fine and normal.
Column rules:
bundle_sku is required on the first row of each bundle and must be empty on every continuation row.
line_item_sku is required on every row, including the first.
quantity is required on every row, must be a whole number greater than zero, and has no default. Leaving it blank is an error, not a shortcut for one.
7. Procedure
Confirm every bundle SKU and every component SKU already exists in Ship Side Kick, and that none of them is archived. The upload will not create products, and an archived product is indistinguishable from a missing one in the error report. Unarchive anything you need first.
Go to Products in the left navigation. Make sure the Products tab is selected rather than Variants, otherwise the Actions menu will not offer the upload.
Open the Actions menu and choose Upload Bundles.
Click Download CSV Template and build your file on top of it. Starting from the template guarantees the headers are right.
Fill in your bundles following section 6. Name each bundle once, then leave the bundle SKU column empty for its remaining components.
Save the file as plain CSV. In Excel, do not choose "CSV UTF-8", which adds an invisible character to the first column heading and makes every row fail at once. Choose "CSV" or "Comma Separated Values" instead.
Choose the file and upload it. The file must be under 5 MB.
Read the result message. If any rows failed, click Download Failed Bundles CSV before closing the dialog, then work through section 9.
Fix the rows the report flags and re-upload only the corrected bundles. Re-uploading a bundle replaces its components outright, so a corrected file does not create duplicates.
8. Verification
Do not trust the success count alone. It counts rows accepted, not bundles shaped correctly.
Open two or three of the uploaded products and check the component list on each. Pick the bundle with the most components in your file, because that is where the delimiter mistake shows up most clearly. If a bundle you expected to hold eight components holds one, the bundle SKU was repeated on every row and the file needs reshaping per section 5.
Also confirm the total. If the result reports far more bundles than your file described, the upload split your rows into separate bundles.
9. What the error file tells you
The download contains every row of every rejected bundle, in the original file order, with an error column appended. It reports all failures at once rather than stopping at the first. Rows that were fine but belong to a rejected bundle are included too, so the file stays re-uploadable once corrected.
Important: one bad row rejects the whole bundle, not just that row.
What the error column says | What to do |
|---|---|
Missing bundle_sku, a bundle must be started before its component rows | Component rows appear before any bundle has been named. Usually a stray blank row, or a file that begins mid bundle. Add the bundle SKU to the first row of that group. |
Missing line_item_sku for bundle "..." | Every row needs a component SKU, including the row that names the bundle. |
Invalid quantity "...". Quantity must be a positive number. | The cell is blank, zero, negative, or not a number. Enter a whole number of one or more. |
Bundle SKU not found, or Component SKU not found | That SKU does not exist in Ship Side Kick, or it exists but is archived. Create or unarchive it, then re-upload. Matching is exact, so check for typos, trailing spaces, and near misses such as a missing suffix. |
Bundle SKU not specific, or Component SKU not specific | Two or more variants share that SKU or alias, so the system cannot tell which one you mean. Resolve the variant links and set a primary, then re-upload. |
Not imported: bundle "..." had errors on other rows. | Nothing is wrong with this row. It was rejected because a sibling row in the same bundle failed. Fix the sibling. |
An unfamiliar or technical looking message on a bundle's first row | Something failed while saving. Common causes are a fractional quantity such as 1.5, or a bundle listed as a component of another bundle, which is not supported. Raise it with support if the cause is not obvious. |
10. Constraints and caveats
Never list a bundle's own SKU as one of its components. Depending on whether that bundle already had a component list, this is either rejected with a confusing message or saved without complaint as a bundle that contains itself. Delete those rows rather than leaving them in and relying on the error report to catch them.
Re-uploading replaces, it does not merge. An existing bundle has its entire component list swapped for whatever the new file says. There is no additive mode.
Re-uploading flattens a hand built bundle. If someone assembled a bundle in the app with multiple named steps, descriptions, or step locations, an upload collapses all of it into a single step called Assembly and renames the bundle's component list. That work cannot be recovered, so avoid re-uploading bundles that were carefully built by hand.
Repeating a bundle SKU further down the file does not add to it. The later group silently replaces the earlier one, and the last occurrence in the file wins. Keep each bundle in one contiguous block.
A bundle cannot contain another bundle. Nesting kits is not supported.
Every uploaded bundle yields exactly one unit per build. If a build should produce more than one finished unit, that has to be set on the product record after upload.
Duplicate components are not combined. Listing the same component twice in one bundle creates two separate lines rather than adding the quantities together.
If the file structure is malformed, for example a row with more or fewer commas than the header, the entire upload is refused and nothing imports. You will get a message about an invalid CSV format and no error report.
11. Worked example
A brand's bundle list arrives as a spreadsheet of a few hundred rows, one row per component. The upload reports success, creates fewer bundles than the file describes, and leaves every multi component kit holding a single component.
Observation | Reading |
|---|---|
The run reports a bundle count close to the number of rows in the file rather than the number of bundles in it. | The bundle SKU is repeated on every row, so each row becomes its own bundle. The count is inflated and almost every bundle is wrong. |
A kit known to have eight components shows only one, and not the first in the list. | Each row has become a separate single component bundle sharing the same SKU. The one left visible is whichever group was processed last. |
Named SKUs report as not found although they are live on the sales channel. | They are archived in Ship Side Kick. Archived products read as missing, and unarchiving them resolves it. |
A file that has just been reviewed and confirmed correct fails in its entirety. | It has been saved as CSV UTF-8, which puts an invisible character on the first column heading, so no row can find its bundle SKU column. |
A few bundles are skipped for listing their own SKU as a component. | Rows copied from a source spreadsheet where the kit and its only component are the same item. Those rows should be deleted. |
Reshaping the file to one row per bundle, with its components listed against it, is what makes the run correct. Expect a residue on any first pass: SKUs the brand has agreed to ignore, self referencing rows to delete, and the occasional component SKU that genuinely does not exist.
12. Related documents
SWI-004 — Read the Inventory Screen, for how bundle stock is displayed once bundles exist
SWI-002 — Move Inventory Between Locations