> For the complete documentation index, see [llms.txt](https://docs.pakk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pakk.io/data-and-integrations/data-import-and-export/import.md). # Import The CSV import framework obviously observes the above conventions, but there's a little bit more you need to know. * **Start with an export.** As I said earlier - there's no need to download a data template or example file, and you shouldn't guess at field names from the labels you see in the admin panel. Just go to the entity you are looking to import, hit the export button, and use that as your template. If you just want a starting point with only required fields, choose the 'Only Required Fields' option on the export dialogue, but bare in mind this won't give you all the fields for lines (if you are importing a transaction). * **Column order is not important.** Only the column **name** is important to getting the import right, not the order. * **You must include the `exportLineType` field for every line in your import**. Remember, for top-level records it will be `MAIN`; for other types of lines, you'll need to include the correct line type (which you can reference from an export). * **Include the ID to update. Omit the ID to create new**. CSV import can be used for creating new records as well as bulk editing existing records. If you include the internal`_id` field (which, technically, is a MongoDB unique identifier, if you must know, but more importantly is always the first field in an export), that record will be an update/edit. If you omit the `_id` field, that line will be a new record creation. * **Include an `exportLineNumberPath` to edit an existing line, omit to create a new line**. Remember that lines 'belong' to the `MAIN` line above it - so if you want to edit transaction lines, you need to include the `MAIN` line for that transaction, even if you don't need to make any edits to the actual transaction. So, if you want to edit Order Line 5 of an existing order, you will need a `MAIN` line for the actual order, then another import line with `exportLineNumberPath` set to 5 with the actual line edits. * **You can mix new creation and updates in a single import**. Leaving the `_id` column in, but only including IDs for some lines will result in a mixed import where some lines will cause new records to be created, and others will cause updates to existing records. Likewise you can mix line edits and new line creations. * **Updates are "patches" not complete overwrites**. That means that when updating records, only the fields present in your import will be applied to the existing record - it won't overwrite the whole thing. * **Not all columns need to be present.** Disregarding required fields on new record creation for a moment, you don't need to include all the columns in your imports. If you are using a CSV import for a bulk update, you can keep your sheet clean and only include the columns you need to update. Again, only those fields will be updated - everything else will be left alone. * **Blank fields are not updated**. One way of excluding a field from being updated is just not including the column at all (see above), but another option is to just leave it blank. * **Deletion is explicit**. It follows from the above that if you want to explicitly delete a field, leaving it blank won't work. For that we have a special tag: ``. Setting the field value to that tag, written exactly in that way, will delete the field contents. What if you want to actually set a customer's name to ``? Sorry, you can't! * **Respect required fields**. There are less required fields in Pakk than other systems because the system uses 'sane' defaults (see below), but some fields really are required, and their field label is marked with a `*`. Without those fields, that import line will fail. * **Sane Defaults**. For new record creation, you can optionally omit quite a lot of fields (see 'Not all columns need to be present') and the system will fill them in with somewhat sane default values: 'blank' for text fields, 0 for number fields, `FALSE` for checkbox fields, 'empty' for lists, and so on. > > If you get a `Line type (field name 'exportLineType') is required` error and you are 100% sure have a line type for every line of your CSV file, the problem is almost certainly that you have 'phantom' empty lines at the bottom of your CSV file. This is very common when editing in Excel and deleting rows. Open your CSV file **in a text editor** and look for rows of commas at the bottom of the file. If you see any, delete them right up until the very end of the last data row (even delete the final carriage return/newline). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pakk.io/data-and-integrations/data-import-and-export/import.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.