Imports

Boxture can create and update records in bulk from a spreadsheet. Every import works the same way: you download a sample file with the supported columns, fill it in, upload it, optionally check a preview, and Boxture processes the rows in the background. When it is done you get a results file that tells you, row by row, what happened.

This page explains the import process and lists every import type. The section pages describe the records themselves in more detail.

Where to find imports

Each import is started from the screen of the records it creates. The Admin › Imports menu item shows the results of earlier imports.

Import	Where to start it	Who may use it
Product	Products › Import	Admins and account owners
Sales order, Purchase order, Transfer order, Return order, Scrap order, Kit order	Orders › Import › choose the order type	Admins and account owners
Adjust Inventory	Inventory › Adjust › Import	Admins and account owners
Container (container moves)	Containers › Move	Admins
User	Admin › Users › Import	Admins and account owners
Bin-location	Admin › Warehousing › Bin locations › Import	Admins
Tote	Admin › Warehousing › Totes › Import	Admins
Packing material	Admin › Warehousing › Packing materials › Import	Admins

INFO

"Admins" are users with the Admin role, "account owners" are users with the Account owner (or Shopify account owner) role for the current account. See Users and roles. Boxture checks this when you open the import page and again when you upload, so a user who can see a menu item but lacks the role is sent back to the dashboard.

The import screen

When you open an import you see the Import card for that import type and, below it, a table with the earlier imports of the same type.

The card contains:

• A short explanation: a CSV or Excel file can be used, the first row must contain the column names, and if you supply a Record ID the matching record is updated instead of a new one being created.
• A sample template link. This prepares an Excel file with every supported column. The file is generated in the background; a notification appears when it is ready to download.
• A current data link (shown for import types that support export, which is all of them). This prepares an Excel file with the records you currently have, in the same column layout. It is a convenient starting point for bulk changes: export, edit, and upload the file again.
• A file field to choose your file.
• Two buttons: Preview and Upload.

The sample file

The sample template has one sheet with the column headers (required columns have a red header) and, for many columns, a comment with a hint such as the allowed values or the expected format. A separate explanation lists each column with its purpose, the values it accepts and an example. Use these as the reference for the exact values; the summaries further down this page give an overview.

Supported file types

You can upload .xlsx, .xls or .csv files. Boxture looks for the header row in the first 20 rows of the sheet and picks the row that best matches the known column names, so a title row above the headers does no harm. Header matching ignores case, spaces and punctuation: Customer reference number and customerreferencenumber are treated the same.

If a header is not recognised, the upload is refused with the message "The structure is invalid, these are the invalid headers: ..." Remove or rename those columns and try again. You do not need to include every column: leave out the ones you don't use.

Uploading step by step

1. Open the import from the menu of the records you want to import (see the table above).
2. Click sample template (for new records) or current data (to change existing records) and wait for the notification with the download.
3. Fill in the file. Keep the header row. Leave Record ID empty to create records; fill it in to update existing ones.
4. Choose the file with the file field.
5. Click Upload to import immediately, or Preview to check the file first.

Preview

Preview shows the content of the file as a table, with a checkbox above each column. Columns that contain data are checked; empty columns are unchecked and cannot be selected. Uncheck a column to leave it out of this import, for example to update only the weight of products while keeping the rest of the file as it is.

Click Upload on the preview to start the import with the checked columns, or Back to cancel. Cancelling removes the uploaded file and returns you to the import screen.

TIP

The preview reads Excel files (.xlsx). Use Upload directly for CSV files.

What happens after the upload

After the upload Boxture schedules the import and shows a notification: "Scheduling import of file name", followed by "Importing file name" with a counter that goes up as rows are processed. Every row is processed as a separate background job, so you can keep working while a large file is imported.

Each row is handled on its own:

• The row is built into a record (looking up related records such as locations, products or customers by ID or name), validated and saved.
• If anything goes wrong, that row is marked as failed with the error message. Other rows are not affected.
• If exactly the same row was already imported successfully in an earlier import, the row is marked as a duplicate and skipped. The Adjust Inventory import is the exception: identical rows are always processed, because adding the same quantity twice is a legitimate action. For the Product import the last of identical rows wins.

When all rows are processed, the notification changes to one of:

Notification	Meaning
Completed import of file name	All rows were imported.
Problems with import of file name	Some rows were imported, some failed.
Failed import of file name	No row was imported successfully.

The results file is attached to the notification.

The results file

The results file is your original sheet with four extra columns:

Column	Content
import_state	success, failure or duplicate
import_created_id	The ID of the record that was created or updated
import_message	The error message for failed rows, or the date of the earlier import for duplicates
import_errors	The validation errors of the record, if any

Failed rows are coloured red and duplicates yellow, and the sheet has filters so you can quickly show only the failed rows. To retry, fix the failed rows, delete the successful ones and upload the file again. Because the extra import_... columns are recognised, you can upload the results file itself.

Import states

An import moves through these states, which you see in the State column of the imports table:

concept → confirmed → scheduled → importing → completed

• concept: the file was uploaded for a preview but not yet started.
• confirmed / scheduled: the import was started and is waiting to be processed.
• importing: rows are being processed.
• completed: every row has a result.
• failed: the import could not be processed at all, for example because the file could not be read. The Result column shows the reason.

Import results

Admin › Imports shows the latest 50 imports, newest first, with:

• Created at and User: when and by whom the import was started.
• Kind: the import type.
• Original: a download link for the uploaded file.
• State: see above.
• Result: the result message, for example "Successfully imported 98 of 100 rows", linked to the results file.

Admins see the imports of all users they administer; other users see only their own imports. The same table, filtered to one import type, is shown on each import screen.

Imports are meant to be deleted after a number of months, see Purging › Importo imports. Automatic purging is currently switched off, so for now nothing is removed.

Imports that print

Papers that are generated while an import runs, such as labels for orders created by an order import, are collected and sent to your printer as one consolidated print job when the import has finished, instead of one print job per row. See Papers.

Import types

All imports accept a Record ID column. When it contains the ID of an existing record, that record is updated; otherwise a new record is created. Most lookup columns accept either the ID or the name (or number) of the related record.

Product

Creates and updates products. Details: Creating products and Product details.

• Product (record ID or product number) to update an existing product; Number is required for new products.
• Product Account: the account the product belongs to (name or ID). If an account name exists more than once you must use the ID.
• Identification: Number, EAN or UPC, Name, Description, Product category (created when it doesn't exist), Vendor, Images (comma-separated URLs).
• Behaviour: Scannable, Setup Complete, Lot Tracked, Lot Pattern, Expirable, Insert, Serialized, Serialization Mode, Serial Number Pattern, Inventoriable.
• Price: Price, Price Currency, Price Country (a price per country).
• Physical: Weight, Weight Unit, Width, Height, Length, Dimensions Unit.
• Customs and compliance: HS Code, ECCN, Origin Country, Customs value, Customs value Currency, Customs Description, UN Number.
• Units of measure: UOM, Quantity Inner Pack, Inner Pack Type, Quantity Inner Packs Per Case, Quantity Case, Case Type, Quantity Cases Per Layer, Quantity Pallet, Pallet Type, Quantity Layers Per Pallet.
• Aliases: Alias Channel, Alias Number, Alias EAN or UPC, Alias Metadata.
• Kits: Kitting Component Product and Kitting Component Quantity. Use one row per component, repeating the kit's Number; the kit is created by the first row and the next rows add components. See Kits.
• Product packaging: Product Packaging Location and Product Packaging Packing Material.
• Metadata and Event (state event, for example to activate the product).

Order imports

The six order imports share the same principle: one row is one order line, and the order-level columns are repeated on every row of the order.

• Rows with the same Customer reference number within one file are combined into one order with several lines. A row without a customer reference number, or with a unique one, becomes a single-line order.
• Line Nr sets the position of the line, starting at 1. Without line numbers the order of the lines is not guaranteed; duplicate line numbers update the same line.
• Event: enter confirm to confirm the order after import, or leave it empty to keep the order in concept. Confirming moves the order on to pending, allocated or backordered, see Order lifecycle. Rows with confirm are processed slightly later than the other rows so that all lines are in place first; enter it only once per order.
• Lines can only be added or changed while the order's lines are still editable; otherwise the row fails with "Cannot edit order lines".

See Creating orders and the page of each order type for what the fields mean.

Import	Order-level columns	Line columns
Sales order	Delivery terms, Business model (b2c/b2b/b2g/bopis), Channel, Related order, Customer reference number, Other reference number, Purchase order number, Shipping method, Customer, Ship earliest on, Delivery contact fields (Company name, First name, Last name, Address lines, Postal code, City, Country, State or Province Code, Phone number, Fax number, email)	Line origin location, Product, Quantity, Currency, Price, Discount, Tax, Customs value, Serial number, Lot number, Expires on, Status
Purchase order	Destination location, Customer reference number, Purchase order number, Other reference number, Inbound tracking number, Forwarder, Shipping container, Shipping container number	Product, Quantity, Serial number
Transfer order	Destination location, Customer reference number, Other reference number, Purchase order number	Line origin location, Product, Quantity, Serial number, Status
Return order	Destination location, Delivery terms, Customer reference number, Other reference number, Shipping method, Related order id, Customer, Pickup contact fields (same fields as the delivery contact above)	Product, Quantity, Serial number, Status
Scrap order	Vendor, Customer reference number, Other reference number, Shipping method	Line origin location, Product, Quantity, Serial number, Status
Kit order	Destination location, Customer Reference Number, Other Reference Number	Kit Product, Quantity

Notes:

• In the sales order import, Price defaults to the product price times the quantity and Customs value to the product customs value times the quantity when you leave them empty. Serial number, Lot number and Expires on are only used when the order and product support them.
• Status is the inventory status to take or receive: new or defective.
• Delivery and pickup address lines can be split with commas.

Related pages: Sales orders, Purchase orders, Transfer orders, Return orders, Scrap orders, Kit orders.

Adjust Inventory

Adds or removes inventory, one row per adjustment. Every row creates an inventory adjustment order, just as an adjustment made on screen. Details: Adjusting inventory.

• Location (name or ID) and Bin Location (name or ID, required).
• Product (product number, EAN, UPC or ID) and, when the same number exists in several accounts, Product Account.
• Quantity: positive to add, negative to remove.
• Container (container number or ID) to adjust inventory in an existing container, or Packing Material (number or ID) to create a new container for it.
• Status (new or defective, default new), Serial Number (several separated by commas), Lot Number, Expires On.
• Notes: added to the generated order.

Identical rows are not treated as duplicates in this import: every row is executed.

Container

Moves containers to another bin location, one row per container. Started from Containers › Move. Details: Containers and Moving inventory.

• Container: the container number (first eight characters of the container ID) or the full ID.
• Location: the location (name or ID) to move to.
• Bin Location: the target bin location (name or ID).

User

Creates and updates users. Details: Users and roles.

• First Name, Last Name, Email, Password, Company Name, Avatar (image URL), Available (TRUE/FALSE).
• Location and Default Packing Bin Location (ID or name; the bin location must belong to the user's location).
• Time Zone (for example Amsterdam) and Week Start (a day name such as Monday).
• Roles: one or more role names as shown in the role list, separated by commas. For: the account names for those roles, in the same order, separated by commas; leave a position empty for a role without account, for example Account1,,Account2. Roles are added; existing roles are kept.
• Accessible Locations: location IDs or names separated by commas.
• State Event: activate, disable, or empty to leave a new user in concept.

Bin-location

Creates and updates bin locations. Details: Bin locations.

• Location ID (record ID of the location) and Name (required, unique within the location).
• Purpose (required): one of problem, receiving, picking, packing, shipping, replenishment, defective, returns.
• Zone, Walkway, Aisle, Rack, Shelf, Section, Bin: optional numbers that describe the position and the walking route.

Tote

Creates and updates totes. Details: Totes.

• Location ID, Name, Weight, Weight Unit.
• Event: activate or disable.

Packing material

Creates and updates packing materials. Details: Packing materials.

• Number, Name, Description, Level, Pickable.
• Physical packaging (used on waybills): bag, barrel, basket, box, bucket, bundle, carton, case, container, crate, cylinder, drum, envelope, hamper, other, pail, pallet, piece, reel, roll, skid, tank or tube.
• Weight, Weight Unit, Width, Height, Length, Dimensions Unit.
• Event: publish, expire or republish.