Reference
CSV import
Every column the bulk importer reads, what it accepts, and the rule that rejects a bad row.
How an import runs
Nothing is written until validation passes. A rejected row never blocks the rest of the file.
| Mode | A SKU you already have |
|---|---|
CREATE_ONLY | Skipped and counted. |
UPSERT | Updated in the mapped columns only. |
Carton columns
| Column | Req | Type | Example | Notes |
|---|---|---|---|---|
| sku | yes | text | BX-120806 | Unique per organization, up to 64 characters. Letters, digits and . _ - /, starting with a letter or digit. |
| name | yes | text | Box 12 x 8 x 6 | Up to 120 characters. |
| type | no | enum | BOX | BOX, BAG, MAILER, TUBE, ENVELOPE, CUSTOM. Defaults to BOX. |
| innerLength | yes | number | 12 | Inside size, used to check fit. Greater than 0, up to 500. Interior vs exterior. |
| innerWidth | yes | number | 8 | As above. |
| innerHeight | yes | number | 6 | As above. |
| outerLength | no | number | 12.25 | Blank reuses the interior, which understates dimensional weight. |
| outerWidth | no | number | 8.25 | |
| outerHeight | no | number | 6.25 | |
| maxWeight | no | number | 40 | Contents only, tare excluded. 0 means no limit of its own; in imperial units, carrier limits still apply. |
| tareWeight | no | number | 0.42 | Empty carton mass, added to gross weight. |
| cost | no | number | 0.78 | Your currency, per empty carton. Used by MIN_COST and LOWEST_RATE. |
| padding | no | number | 0.25 | Dunnage per interior face, up to 24. Unmapped uses your organization default. Diagram. |
| active | no | boolean | true | Inactive cartons are ignored by the cartonizer. |
| flexible | no | boolean | false | Packaging that shapes to its contents, like a poly bag. How it is cartonized. |
| maxBulge | no | number | 1 | Extra height a flexible carton gains when stuffed. Up to 24. |
| fillFactor | no | number | 0.85 | 0.05 to 1. Usable fraction of a flexible carton. |
| notes | no | text | ECT-32 single wall | Up to 2,000 characters. |
Item columns
| Column | Req | Type | Example | Notes |
|---|---|---|---|---|
| sku | yes | text | SKU-1001 | Unique per organization. Same character rules as a carton SKU. |
| name | yes | text | Ceramic mug 12 oz | Up to 160 characters. |
| category | no | text | Housewares | Free-form, used for filtering. Up to 64 characters. |
| length | yes | number | 4.5 | Size as it ships, including any packaging of its own. |
| width | yes | number | 3.5 | |
| height | yes | number | 4.25 | |
| weight | yes | number | 0.95 | Per unit, in your mass unit. Up to 5000. |
| fragile | no | boolean | true | Nothing may rest on it. Most orderings pack it late. Diagram. |
| stackable | no | boolean | true | False means nothing may rest on it at all. Defaults to true. |
| maxStackWeight | no | number | 15 | Most weight that may rest on it. 0 means no set limit. |
| orientationLock | no | enum | THIS_SIDE_UP | FREE, THIS_SIDE_UP, FLAT, UPRIGHT, FIXED. Defaults to FREE. Diagram. |
| nestIncrement | no | number | 0.35 | Height each further unit adds to a nest, like stacked cups. Less than height. Blank or 0 means it does not nest. |
| maxNestQuantity | no | number | 50 | Most units in one nest, a whole number from 2 to 10,000. Needs a nestIncrement above 0. Blank means carton size and weight limit a nest. |
| groupKey | no | text | CABLE-KIT | The Grouped sets first ordering packs each group back to back. A split group gets a warning. Diagram. |
| hazmatClass | no | text | blank | Free-form. Items of different classes never share a carton. |
| keepApart | no | text | blank | Free-form. Items with different values never share a carton, such as Firearm and Ammunition. Diagram. |
| color | no | hex | #b45309 | Six digits, for the 3D plan. Blank derives one from the SKU. |
| notes | no | text | Ships in its retail box | Up to 2,000 characters. |
| active | no | boolean | true |
Validation rules
| Rule | Effect |
|---|---|
| Header matching | Case, spaces, underscores and units in parentheses are ignored. "Inner Length (in)" maps to innerLength. |
| Required column unmapped | The Check button stays disabled and names the unmatched required fields. |
| Blank required cell | That row fails. The rest of the file still imports. |
| Blank optional cell | Takes the column default, or clears the field where the column is nullable. |
| Padding vs cavity | Each inner dimension must be more than twice the padding, or the row is rejected. |
| Outer vs inner | An outer dimension below its inner counterpart is rejected. |
| Repeated SKU | The first row wins; later rows are reported as errors. |
| Same rules as the API | Rows pass the same checks as POST /api/v1/cartons and POST /api/v1/items, so an import cannot create a record the API would reject. |
Accepted values
| Type | Accepts |
|---|---|
| number | Spaces, thousands separators and currency marks are stripped: "1,250" and "$0.78" both parse. |
| boolean | true, t, yes, y, 1, x, active, on — and false, f, no, n, 0, inactive, off. Case-insensitive. |
| enum | The code, or its display label. Spaces and hyphens become underscores: "this side up" maps to THIS_SIDE_UP. |
| text | Quoted fields may contain commas and newlines; "" is a literal quote. A UTF-8 byte-order mark is stripped. |
cartons.csv
sku,name,type,innerLength,innerWidth,innerHeight,maxWeight,cost,padding,flexible,maxBulge BX-120806,"Corrugated box 12 x 8 x 6",BOX,12,8,6,40,0.78,0.25,false,0 PB-1215,"Poly bag 12 x 15",BAG,12,15,0.75,5,0.09,0,true,1
Click Download template on the import screen for every column header and two example rows.
Limits
| Limit | Value |
|---|---|
| Rows per import | 20,000. Split a larger file and run it again. |
| Rows per API bulk call | 1,000, on /cartons/bulk and /items/bulk. |
| Errors kept | The first 200 per batch, each with its row and field. |
| Plan ceiling | Each 400-row chunk is checked against your plan's limit. Chunks before the one that goes over stay imported. Existing SKUs count only if the import reactivates them. |
| Delimiters | Comma, semicolon, tab or pipe, detected from the header row. A range pasted from a spreadsheet is tab-delimited. |