# Migrate starting stock and cut over to Starshipit WMS
URL: https://support.starshipit.com/articles/14700000000049-migrate-starting-stock-and-cut-over-to-starshipit-wms
Canonical: https://support.starshipit.com/articles/14700000000049-migrate-starting-stock-and-cut-over-to-starshipit-wms
Markdown: https://support.starshipit.com/articles/14700000000049-migrate-starting-stock-and-cut-over-to-starshipit-wms.md
Updated: 2026-07-20

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Prepare, import, validate, and reconcile starting stock when moving warehouse operations to Starshipit WMS.

Use this guide to move your opening stock into Starshipit WMS, reconcile the result, and switch warehouse operations over at a controlled point in time.

## Before you begin

Complete these checks before preparing the opening balance:

- Make sure your role can adjust inventory in WMS.
- Sync your product catalogue and resolve missing or duplicate SKUs.
- Configure each product's tracking type before loading stock. Changing a product from Standard to Batch or Serial after the load does not add the missing tracking details.
- Create every warehouse location that will hold opening stock. Confirm each location allows the relevant products and, for a 3PL warehouse, the relevant client stock.
- Convert quantities to the parent product's inventory unit. The Starting Stock page excludes child unit-of-measure products because WMS tracks their inventory against the parent SKU.
- Decide who will approve the final source-system export, who will load it, and who will sign off the WMS result.
- Review your [commerce inventory sync settings](/articles/14700000000018-shopify-inventory-sync). A successful opening balance creates stock movements that can queue writeback to enabled commerce platforms.

:::warning
Starting Stock adds stock to WMS. It does not replace an existing balance, and there is no user-facing undo or rollback action. Uploading and saving the same quantities again will add them again.
:::

## Prepare the Starting Stock template

1. Go to [the Starting Stock page](https://wms.starshipit.com/dashboard/setup/starting-stock).
2. Select the **Default location** you want WMS to use while preparing the file.
3. Select **Load more products** until that action no longer appears. CSV values can only be staged for products already loaded into the page.
4. Select **Import via CSV instead**.
5. Select **Download a pre-filled template with your products**.
6. Save an unchanged copy of `starting-stock-template.csv` for reference.
7. Enter the final quantity and location for each product you want to load. Leave products with no opening stock blank.

The canonical Starting Stock file uses these columns in this order:

| Column | What to enter | How WMS uses it |
| --- | --- | --- |
| `sku` | The exact SKU already synced to WMS. Preserve leading zeros. | Required to match the row to a visible product. Matching is not case-sensitive. |
| `product_name` | The pre-filled product name. | For your reference only. WMS does not use it to find the product. |
| `quantity` | A positive whole number. | WMS stages digits only. Blank, zero, negative, and decimal quantities are not saved as starting stock. |
| `location` | The exact name of an existing WMS location. | Matching is not case-sensitive. A blank or unmatched name leaves the product on its current or default location in the form. |

Keep the header row and column order unchanged. The importer reads values by column position and treats the first non-empty row as the header.

:::caution
Review every location after import. An unknown location name does not reject the row; WMS keeps the location already selected for that product instead.
:::

The Starting Stock template supports one quantity and one location per product. Do not add duplicate rows for a SKU to represent multiple locations. The last matching row replaces the earlier staged value. Use Starting Stock for one location, then add the remaining location balances through **Stock Adjustments**, or use Stock Adjustments for the complete multi-location load.

## Handle batch, serial, and expiry details

The Starting Stock template has no batch number, serial number, or expiry date fields. Keep tracked products out of this file and load them through **Stock Adjustments** so their traceability data is recorded.

:::important
Do not use Starting Stock for batch- or serial-tracked inventory. A serial-tracked row cannot be added without its serial number. A batch-tracked row needs its batch details preserved for later allocation and traceability.
:::

For a small tracked-stock load:

1. Go to **Stock Adjustments**.
2. Select the product and its location.
3. Enter a positive quantity change.
4. Select **Stock Receipt**, or your configured opening-balance reason, and enter `Opening Balance` as the reference.
5. For a batch-tracked product, enter the **Batch number** and, when applicable, the **Expiry date** in `DD-MM-YYYY` format.
6. For a serial-tracked product, enter one unique **Serial number** and a quantity of `1`. Add a separate adjustment for every unit.
7. Select **Add to batch**, review the queued rows, then select **Submit adjustments**.

For a larger tracked or multi-location load, add and validate a representative adjustment, then export the queued batch and use that export as your adjustment CSV template. The adjustment file supports these opening-balance fields:

| Field | Requirement for an opening balance |
| --- | --- |
| `sku` | Required. Must match an existing parent product. |
| `quantityChange` | Required. Use a positive whole number; use `1` for each serial-tracked unit. |
| `reason` | Required. Use a configured adjustment reason such as `Stock Receipt`. |
| `locationName` | Required. Must match an existing location. |
| `batchNumber` | Required for a batch-tracked product. |
| `expiryDate` | Optional for a batch-tracked product. Use `DD-MM-YYYY`. |
| `serialNumber` | Required for a serial-tracked product and must be unique. |
| `reference` | Use `Opening Balance` to make reconciliation easier. |

Manual adjustment CSV files must be 5 MB or smaller. Imported rows are validated before they enter the on-screen queue. When you submit the queue, WMS processes each adjustment separately. Some rows can succeed while others fail, so keep the successful rows out of any retry file.

## Rehearse without changing stock

The Starting Stock CSV import is a staging step. Uploading a file fills the on-screen quantities and locations but does not change inventory until you select **Save starting stock**.

Use that staging step as a rehearsal:

1. Make a copy of the migration file.
2. Include representative standard products, locations, and quantity sizes.
3. Upload the copy to Starting Stock without selecting **Save starting stock**.
4. Compare the matched count with the number of positive rows in your file.
5. Review every staged quantity and location, including products beyond the first page.
6. Leave or reload the page to discard the staged values.
7. Import tracked-stock adjustment rows into **Stock Adjustments**, review the queued rows and validation messages, then remove or leave the queue without submitting it.

There is no separate Starting Stock dry-run command. Do not select either save or submit action during the rehearsal.

## Run the operational cutover

Choose a cutover window when stock can stop moving long enough to produce and load one final balance.

1. Finish the rehearsal and resolve every product, location, tracking, and file-format issue.
2. Confirm whether commerce writeback should be enabled during the load. Change the relevant integration settings before the freeze if it should not run.
3. Freeze stock-changing work in the old process and WMS. Pause receiving, putaway, picking, packing and shipping, returns, transfers, stocktakes, and manual adjustments.
4. Complete any in-progress stock movements or return them to a known state.
5. Take the final opening-balance export or signed physical count from the old system. Record the effective date and time.
6. Update the Starting Stock and tracked-stock files from that frozen balance. Do not reuse quantities from the rehearsal.
7. Upload the standard-product file, resolve every skipped row, and review all staged locations and quantities.
8. Select **Save starting stock** once and wait for the success message.
9. Load the batch-, serial-, and multi-location adjustment rows. Review successful and failed adjustment counts before retrying anything.
10. Reconcile WMS against the frozen balance before allowing stock to move again.

## Reconcile the opening balance

1. Go to the **Inventory** dashboard and refresh the data.
2. Export the stock-on-hand report.
3. Compare WMS with the frozen source balance by SKU and location, then compare the warehouse-wide total for each SKU.
4. Spot-check batch numbers, expiry dates, and individual serial numbers for every tracked-product type used in your warehouse.
5. Review **Stock Movements**. Starting Stock movements use the reason `Stock Receipt` and reference `Opening Balance`.
6. Review **System > Process Logs** for any commerce inventory writeback failures.
7. Investigate every difference and record the correction before signing off.
8. If needed, run a manual bulk commerce sync after WMS is correct so the connected platform receives the reconciled on-hand quantity.
9. Resume warehouse operations and connected-system processing only after the opening balance is approved.

## Correct errors and rerun safely

Use the result in WMS, not the original upload message alone, to decide what to do next.

| Result | Safe next action |
| --- | --- |
| The CSV reports skipped or invalid rows before save | Correct the source file, re-import it, and review all staged values. No stock has changed yet. |
| **Save starting stock** returns an error | Check Inventory and Stock Movements for `Opening Balance` records before retrying. If none were created, correct the reported product or location problem and retry only after confirming the balance is unchanged. |
| The save result is uncertain because the browser or connection failed | Reconcile WMS first. Do not upload the full file again until you know which movements exist. |
| A row was omitted from a successful load | Add only the confirmed missing quantity. Do not include previously successful rows. |
| A quantity or location was saved incorrectly | Create a positive or negative manual adjustment, or post a verified stocktake correction. Keep `Opening Balance correction` in the reference for the audit trail. |
| A manual adjustment batch partially succeeds | Remove successful rows from the retry file and resubmit only the failed rows after correcting them. |
| The full Starting Stock file was saved twice | Do not delete movement history. Post reviewed opposite adjustments for the duplicated quantities and reconcile again. |

WMS plans and validates all rows in a Starting Stock save before applying them. Its inventory database writes then run together, so a validation or database failure does not leave part of that Starting Stock batch applied. This is not an undo or rollback feature you can invoke, and a successful save cannot be undone. Corrections create new stock movements so the original opening balance and the correction remain visible in the audit trail.

Commerce writeback is outside the opening-balance inventory transaction. A writeback failure does not reverse stock already saved in WMS. Resolve the WMS balance first, then investigate or rerun the commerce sync separately.

## Related articles

- [Products and inventory configuration](/articles/14700000000006-starshipit-wms-products-and-inventory-configuration)
- [Locations and warehouse setup](/articles/14700000000033-starshipit-wms-locations-and-warehouse-setup)
- [Inventory dashboard and stock visibility](/articles/14700000000014-inventory-dashboard-and-stock-visibility)
- [Stock integrity and adjustments](/articles/14700000000020-stock-integrity-and-adjustments)
- [Commerce inventory sync](/articles/14700000000018-shopify-inventory-sync)