Data import order: what to load first, and why

Last updated: August 22, 2026

A note on how this guide is written. This guide covers the order and the tools for bringing bulk data into a Cloudby organisation, whichever entity you are importing. It does not repeat the finance-specific technique for opening balances, or the inventory-specific technique for cost and location, each has its own guide and is linked from here at the right point. Data Porting sits in the same power admin territory as Document Overrider and Configurator, covered in the sysadmin guide, reached by whoever set the organisation up or a senior finance/ops lead, not by everyday staff.
Who this is for: whoever is bringing a meaningful amount of data into Cloudby in one go, a new implementation, a migration from another system, or a large one-off correction.
Scope: what order entities need to go in, the real import mechanic (Upload, Review, Import), how to verify a batch, what Bulk Edit actually does, and how to handle very large volumes.
What this guide is not: a guide to opening balances or to inventory cost and location, each has its own guide, linked from the relevant section below rather than repeated here.
What you will have by the end. A clear map of what needs to exist before what, so an import does not fail on a missing reference partway through. Confidence in the validate-before-commit safety net, and a realistic understanding of its limit: there is no undo once something is committed, so a batch strategy matters more than it might first seem.

1. Why order matters

Data Porting imports by matching codes, a Customer row references a Customer Category by code, a Sales Invoice references a Customer by code, and so on. If the thing being referenced does not exist yet, the import does not guess or create it for you, it fails that row with a clear reason. Importing in the right order the first time avoids a frustrating cycle of failed rows, fixes, and re-uploads, and for anything that posts to the ledger, getting the order right also means your Chart of Accounts is ready to receive it.

Further reading. How to: Import and export your data. Reference: Data Porting.

2. The dependency map

Five practical waves, each depending only on what came before it. Within a wave, order does not matter, entities in the same wave do not reference each other.

WaveImportWhy it goes here
1Chart of Accounts, Units of Measurement, Locations, Currency, Inventory Class/Group, Sale Product Category, Sale Term, Payroll ItemNo dependency on anything else. Chart of Accounts and Sale Product Category are self-referential trees, parent and child rows can be in any order within the same import.
2Cash and Bank Accounts, Directors, Inventory Categories, Tax Groups, Vendors, Customer Categories, Stock SKUs, EmployeesEach needs a Chart of Accounts ledger already in place, a Bank Account needs its ledger, a Vendor needs its Payable ledger, a Tax Group needs Sale and Purchase ledgers for every tax item.
3Sale Products, Customers, Bills of Materials, Stock AttributesA Sale Product needs its Category and Unit of Measurement, a Stock Attribute needs the Stock SKU row to already exist, it never creates one.
4Customer Pricelists, Employee to Payroll Item assignments, Employee Reimbursement Forms, Journal Entries, Purchase QuotationsA Pricelist line needs the Sale Product it prices, a Payroll Item assignment is a pure lookup, both Employee and Payroll Item must already exist, neither gets created here.
5Orders, Invoices, Bills, Deliveries, Goods Receives, PaymentsThe full document chain. One hard rule worth knowing by name: a Purchase Goods Receive requires an existing Purchase Order, it cannot be imported on its own. A Payment references the Invoice or Bill it settles, so that document should already exist.
Note. Most reference columns are optional, if you leave a Vendor’s Payable Ledger blank the import still succeeds, it just falls back to your organisation default (covered in the finance data guide). A smaller number are required and will fail the row outright if left blank or unmatched, most notably UOM on a Stock SKU, and Location on a Purchase Quotation, Sale Delivery, or Sale Invoice charged by amount. When a row fails, the reason names exactly which reference could not be matched.

3. The import mechanic

Go to Menu > Settings > Administrative > Data Porting. Every entity follows the same real, on-screen stepper: Upload, Review, Import. Pick what you are importing from the entity list, and each entity’s screen offers a Template tab to download a spreadsheet with the right column headers already in place.

The Data Porting entity list, one row per importable entity
Menu > Settings > Administrative > Data Porting, one row per entity you can import
An entity's Template tab, offering a downloadable spreadsheet with the correct column headers
The Template tab: a real spreadsheet with the right headers, so you are never guessing at the format

On the Upload tab, attach your filled-in spreadsheet, nothing has happened to your data yet, then a button labelled Validate checks every row and produces a report right there. If any row is clean and you are ready to proceed, the same tab’s final action button, labelled Create, is what actually commits the data. Review is where you read that report before deciding to proceed, there is no separate button confirming a commit, Create at the Upload stage is the real point of no return.

The Upload tab with a spreadsheet attached, showing the Validate button
Upload: attach your spreadsheet, nothing is saved until you commit

Further reading. How to: Import and export your data.

4. Verifying a batch

Validate reads every row and reports, row by row, which are fine and which have a problem, naming the exact reason for each. In one real test, a Stock SKU sheet with a unit of measurement that did not exist reported back precisely: “Invalid Unit mapping with value: Bag-NotReal-UOM”, exactly as specific as it sounds. Nothing is saved from this report on its own, you either fix the source spreadsheet and re-upload, or once every row is clean, use Create to commit.

A validation report showing clean rows alongside one row with a specific, named error
Review: every row checked before anything commits, each problem named specifically, not just flagged
Use with real caution: there is no undo once you commit. Validate catches malformed data, a missing reference, a blank required field, but it cannot catch data that is well formed and simply wrong or premature. Once a batch commits, the records it created are permanent. Deleting the import’s own tracking record afterward removes only that audit trail, not the data it created. And no self-service backup or restore point exists for a real tenant to fall back on if a large committed batch turns out to be wrong, that capability is not available to an organisation admin. The practical answer is a batch strategy, not a safety net: import one entity at a time, in the order set out above, check the result looks right before moving to the next, rather than queuing up an entire migration and validating and committing it all in one pass.

Further reading. How to: Import and export your data.

5. Bulk edit: what it actually does

Bulk Edit is a separate, deliberately narrow tool, not a way to re-upload a spreadsheet and change any field on existing records. Working from a worksheet tab named “Bulk Edit,” it supports exactly three operations per row, matched by the entity’s code: rename the code itself, a status change where the entity supports one, and delete, done by typing the word DELETE in a Delete column. Everything else about a record, its name, description, any business field, is untouched by Bulk Edit, the ordinary Data-sheet import is what handles that.

Note. Bulk Edit is only available for a handful of entities today, Stock (through the extended Stock import only, not the plain one), Customer, and Employee. Employee supports rename only, status and delete were deliberately left off for that entity.

6. Handling large volumes

There is no row-count or file-size limit written into Data Porting itself, a large sheet is read a document at a time rather than loaded whole into memory. The real constraint is a fixed 30 second server-side execution window on every import request. A sheet with simple, flat rows, Stock SKUs with no nested lines, handles far more rows in that time than one with many child lines per document, a Bill of Materials with a long component list, for example. If an import does not finish in time, the request fails outright with no partial progress kept, since the whole batch runs inside one transaction.

Good to know. For a very large migration, split the data into several smaller files rather than one giant one. It costs a few extra upload cycles and buys real headroom against the time limit, which is worth far more than the convenience of one big file, especially given section 4 above.

What’s next

A few notes as you plan the rest of your data migration:

  • Opening balances, the correct technique for entering them, and what goes wrong if you skip it, are covered in their own guide, not repeated here.
  • Inventory cost and location, including a real technique for correcting stock counts progressively rather than all at once, are covered in their own guide too.
  • This guide describes Porting as it stands today. Tax code validation on invoice and bill line items happens downstream of the import layer itself and was not traced in full for this guide, treat any tax-related import warning on those documents as worth double checking manually.

Scenarios and troubleshooting

My import failed on a row that references something I am sure I already imported.

Check the wave table in section 2, the reference likely needs a code match, not just a name that looks similar, and a small typo or trailing space in either sheet is enough to break the match. Re-check the exact code in both places.

I need to bulk-import stock levels or bulk-fix product descriptions.

Bulk Edit will not do this, see section 5, it only renames, changes status, or deletes. Quantity and cost are set through Inventory Entries instead, covered in the inventory guide, and a description change goes through the ordinary Stock import.

A large import keeps failing partway through with no clear error.

This is very likely the 30 second execution window in section 6, not a data problem. Split the file into smaller batches and re-try.

I committed a batch and now realise part of it is wrong.

There is no built-in undo, see the caution in section 4. Correct the affected records directly through their own screens, or through a fresh, deliberately scoped import, rather than looking for a rollback option that does not exist.

Related