Importable purchase order columns reference
This page is the complete lookup for every column the Import Purchase Orders file importer reads — the one behind the Import button on the Purchase Orders list. It's the reference companion to the task guide Import purchase orders from a spreadsheet — read that first for the step-by-step flow; come here to look up a specific column, its accepted values, or an edge case.
Everything below is read straight from the importer, so it's authoritative for what the Import Purchase Orders window accepts. For what each field means on the purchase order itself, see Purchase order fields reference.
This page covers the file importer that creates whole POs. The separate Import lines tool (on an open PO) reads a much smaller set of columns — see Line-item importer columns at the bottom of this page, and Import line items into an existing PO for its flow.
Before you begin
- Importing requires the Import purchase orders permission. Without it the Import button is hidden. See permissions.
- Every lookup column resolves a value to a record that must already exist in your account — the importer never creates suppliers, warehouses, currencies, payment terms, shipping methods, incoterms, or nominal codes for you. An unknown value is a row error. Copy names and codes verbatim from the template's Reference Data sheet.
- The products you order must already exist as standard or kit products. Any other product type (matrix, bundle, blemished, and more) is rejected the same way as a missing SKU.
How rows become purchase orders
- One row = one line item. A PO with three lines is three rows.
- Rows are grouped into a PO by
purchase_order_number+supplier_name. Every row sharing both values is merged into one PO with multiple lines. - A blank
purchase_order_numberbecomes its own separate, auto-numbered PO — SKU.io assigns the next number in your sequence when it's created. Two blank-numbered rows don't merge, even for the same supplier. - Header columns are read from the first row of each group. The values that describe the whole order (supplier, warehouse, currency, dates, notes, tags, and more) are taken from the first row of the group; put them there, and — for readability — repeat them on every row of the same order.
See the worked grouping example in the task guide.
Required columns
Five columns are required — they show with green headers in the template. Everything else is optional.
| Required column | Level | Why |
|---|---|---|
supplier_name | Header | The PO must have a supplier. |
currency_code | Header | The PO must have a currency. |
sku | Line item | Every line needs a product. |
quantity | Line item | Every line needs a quantity. |
unit_price | Line item | Every line needs a price. |
If any required value is missing or unresolvable, that PO (or line) is flagged with an error during validation and is skipped when you import — the rest still import.
The import is all-or-nothing at the save step
Validation is safe to repeat and writes nothing. But once you click Import N Purchase Orders, all the valid POs are saved together in a single database transaction. If any one PO fails while saving, the entire batch is rolled back and nothing is created — you can fix the flagged PO and re-run the whole file safely. See When the whole import rolls back.
Header columns
Header columns describe the whole order. They're read from the first row of each PO group.
| Column | Required | Type / format | Accepted values | Notes |
|---|---|---|---|---|
purchase_order_number | No | Text (≤255) | Any | The order's reference. Leave blank to auto-generate the next number in your sequence. Together with supplier_name, it's the grouping key. |
purchase_order_date | No | Date YYYY-MM-DD | The order date. Blank defaults to today. | |
supplier_name | Yes | Text | Existing supplier name | Matched by name, case-insensitive. An unknown or blank supplier errors the PO. |
destination_warehouse | No | Text | Existing non-supplier warehouse name | Matched by name. Blank falls back to the supplier's default warehouse, then your account's default PO warehouse. A warehouse that belongs to the supplier is rejected (supplier warehouses can't be a PO destination), and if nothing resolves the PO errors. |
currency_code | Yes | Text | Existing ISO currency code | Matched by code, case-insensitive (for example, USD). An unknown or blank currency errors the PO. |
estimated_delivery_date | No | Date YYYY-MM-DD | Expected delivery date (ETA) for the whole PO. | |
supplier_notes | No | Free text | Any | Notes that print on the purchase order the supplier sees. Use this for anything you want the vendor to read. Contrast with internal_notes below. |
internal_notes | No | Free text | Any | Private notes — never printed and never sent to the supplier. Use it for internal context (approver, budget code, reminders). See the dedicated section below — this column is not pre-included in the downloaded template, but the importer fully supports it. |
tracking_number | No | Free text | Any | Inbound-shipment tracking reference, if known. |
tags | No | Text | Comma-separated | Applied to the PO as tags, for example, urgent, seasonal. |
payment_term | No | Text | Existing payment-term name | Matched by name. Unknown value errors the PO. |
shipping_method | No | Text | Existing shipping-method full name | Matched by full name — the reference sheet lists these including the carrier, for example, UPS Ground. Unknown value errors the PO. |
incoterm | No | Text | Existing incoterm code | Matched by code, for example, FOB. Unknown value errors the PO. |
supplier_name, destination_warehouse, currency_code, payment_term, shipping_method, and incoterm all resolve to records that must already exist. A value that "looks right" but is spelled differently (Acme Supply vs Acme Supplies) is reported as an error during validation, not silently skipped. Copy them from the Reference Data sheet.
internal_notes vs supplier_notes
These two note columns look similar but land in very different places — get them right so private text never reaches a vendor:
supplier_notes | internal_notes | |
|---|---|---|
| Who sees it | The supplier | Only your team |
| Prints on the PO document? | Yes — it appears on the PO the supplier receives | No — never printed, never emailed to the supplier |
| In the downloaded template? | Yes (a standard column) | No — add the column yourself and map it |
| Typical use | "Please ship via express freight" | "Approved by Dana", "Q3 marketing budget" |
internal_notes is a fully working import column: the importer validates it, maps it, and writes it to the PO's private notes. Because it isn't one of the columns in the downloaded template, add an internal_notes column to your file and the mapper will pick it up — the auto-matcher recognises headers like Internal Notes, Notes, Memo, Comments, or Remarks, while supplier_notes matches Supplier Notes, Vendor Notes, or Message to Supplier. You can also set the mapping by hand on the Map Columns step. See Notes, tags, and custom fields for how the two notes behave on the order.
Line-item columns
Each row carries one line item. sku, quantity, and unit_price are required on every row; the rest are optional.
| Column | Required | Type / format | Accepted values | Notes |
|---|---|---|---|---|
sku | Yes | Text | Existing standard or kit product SKU | Matched case-insensitive. A SKU that doesn't exist, or that resolves to a non-standard/non-kit product, errors the line. |
quantity | Yes | Whole number | 1 – 9,999,999 | Must be a positive whole number. Decimals are truncated; zero or negative errors the line. |
unit_price | Yes | Number ≥ 0 | Price per unit in the PO currency. Sets the line's cost/amount. See the unit_price vs unit_cost note. | |
description | No | Text (≤255) | Any | Line description. Blank falls back to the product name. |
discount | No | Number ≥ 0 | A per-unit discount amount, in currency — not a percentage. 1.50 takes $1.50 off each unit. | |
tax_rate | No | Number (percent) | for example, 10 for 10% | Tax rate percentage for the line. Blank applies the supplier's default tax rate (if one is set). |
nominal_code | No | Text | Existing nominal-code code | Accounting code for the line, matched by code. Unknown value errors the line. |
A note on naming: unit_price vs unit_cost
The file importer on this page uses unit_price (required) for the per-unit line cost. The separate Import lines tool (on an open PO) instead uses a column called unit_cost (optional). Both set the same thing — the per-unit cost of the line — they're just named differently in the two importers. Don't be thrown by the different header: use unit_price when importing whole POs from a file, and unit_cost when adding lines to a PO you already have open.
Custom-field columns (custom_<slug>)
If your account has custom fields configured for purchase orders, each one gets its own column named custom_<slug> (for example custom_project_code). These columns are added to the downloaded template automatically — one per active PO custom field — and appear on the Map Columns step so you can map any file column onto them.
They're always optional. Validation follows the field's type:
| Custom-field type | Accepted values | Example |
|---|---|---|
| Text / Long text | Free text | A longer note |
| Number | Whole number | 42 |
| Decimal | Decimal number | 3.14 |
| Date | YYYY-MM-DD | 2026-04-21 |
| Datetime | YYYY-MM-DD HH:MM:SS | 2026-04-21 14:30:00 |
| Checkbox | true / false (also 1/0, yes/no) | true |
| Dropdown | One of the field's configured options | see below |
For dropdown custom fields, the template's Reference Data sheet lists the valid options for each one under a CUSTOM FIELD: <name> (dropdown options) section — copy an option verbatim. Custom-field values are PO-level (read from the first row of each group), like the other header columns.
The downloadable template (three sheets)
Click Download Template on the import window to get an XLSX workbook tailored to your account. It has three sheets:
| Sheet | What it holds |
|---|---|
| Import Here | The columns to fill in, with sample rows. Green headers are required (supplier_name, currency_code, sku, quantity, unit_price); gray headers are optional. Includes a custom_<slug> column for each PO custom field. |
| Field Guide | Every column with its description, whether it's required, its valid values, and an example — required rows are highlighted. |
| Reference Data | The exact valid values from your account: suppliers, warehouses (non-supplier only), currencies, payment terms, shipping methods (by full name), incoterms (code — description), tax rates (name — rate), nominal codes (code — name), and the options for each dropdown custom field. Copy these verbatim. |
You don't have to use the template — any CSV, TSV, or Excel file with a header row works, as does pasting delimited text — but the template guarantees the exact header names the auto-matcher recognises, and its Reference Data sheet holds the exact values that will resolve.
Spreadsheet apps often rewrite a long numeric SKU or barcode into scientific notation (5.06E+11) or drop a leading zero, which then fails to match your product. Keep the file in Excel (.xlsx) (also accepted) or format the SKU/barcode column as Text before typing into it.
Line-item importer (Import lines)
The Import lines tool on an open PO is a different, smaller importer — it adds lines to a PO that already exists and never creates a PO. It reads only three things from your file:
| Column | Required | Notes |
|---|---|---|
sku (or barcode) | Yes | Matches a product by SKU or barcode. Only standard/kit products. |
quantity | No | Defaults to 1 when the column is unmapped or blank. |
unit_cost | No | Blank falls back to the supplier's pricing-tier price, then the product's own cost, then 0. |
If the same SKU appears on more than one row, the rows are consolidated into a single line with their quantities summed. For the full flow, the case-pack default, and the Replace all existing lines option, see Import line items into an existing PO.
Next steps
- Import purchase orders from a spreadsheet — the full task flow, grouping, validation, and background handling.
- Exportable purchase order columns reference — the column-by-column list for exporting POs back out.
- Purchase order fields reference — what each field means on the order itself.
- The purchase orders list: columns and filters — the columns you can show, filter, and export.
- Notes, tags, and custom fields — how supplier vs internal notes and custom fields behave on a PO.