Reference
CSV import
Every column the bulk importer reads, what it accepts, and the rule that rejects a bad row.
How an import runs
| Mode | A SKU you already have |
|---|---|
CREATE_ONLY | Skipped and counted. Nothing is overwritten. |
UPSERT | Updated — but only the columns the file actually maps. |
Carton columns
| Column | Req | Type | Example | Notes |
|---|---|---|---|---|
| sku | yes | text | BX-120806 | Unique per organization, 64 characters. Letters, digits and . _ - /, starting with a letter or digit. |
| name | yes | text | Box 12 x 8 x 6 | 120 characters. |
| type | no | enum | BOX | BOX, BAG, MAILER, TUBE, ENVELOPE, CUSTOM. Defaults to BOX. |
| innerLength | yes | number | 12 | Interior cavity — what decides fit. Greater than 0, up to 500. Why it matters. |
| 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 cap. |
| 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. |
| padding | no | number | 0.25 | Dunnage per interior face, up to 24. Unmapped uses your organization default. Diagram. |
| quantityOnHand | no | integer | 240 | Respected by the solver unless you turn that off. |
| reorderPoint | no | integer | 60 | Drives the low-stock view and the reorder report. |
| active | no | boolean | true | Inactive cartons are ignored by the solver. |
| flexible | no | boolean | false | Conformable packaging. How it is solved. |
| 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 | 2000 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 | 160 characters. |
| category | no | text | Housewares | Free-form, used for filtering. 64 characters. |
| length | yes | number | 4.5 | Shipping footprint, not the bare product if they differ. |
| 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 | Never carries load; placed last. Diagram. |
| stackable | no | boolean | true | False means nothing may rest on it at all. Defaults to true. |
| maxStackWeight | no | number | 15 | Cap on the top face. 0 means no explicit cap. |
| orientationLock | no | enum | THIS_SIDE_UP | FREE, THIS_SIDE_UP, FLAT, UPRIGHT, FIXED. Defaults to FREE. Diagram. |
| groupKey | no | text | CABLE-KIT | Lines sharing a key are kept in one carton where possible. |
| hazmatClass | no | text | blank | Free-form. Conflicting classes are not co-packed. |
| color | no | hex | #b45309 | Six digits, for the 3D plan. Blank derives one from the SKU. |
| notes | no | text | Ships in its retail box | 2000 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 | Every row fails with "No source column is mapped." |
| 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 | Twice the padding must leave space on every axis, 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 run through the schema POST /api/v1/cartons uses, 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. |
| integer | "240.0" is accepted as 240; "240.5" is rejected. |
| 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,quantityOnHand BX-120806,"Corrugated box 12 x 8 x 6",BOX,12,8,6,40,0.78,0.25,240 PB-1215,"Poly bag 12 x 15",BAG,12,15,0.75,5,0.09,0,1500
The import screen offers a template with every column and two filled example rows, which is the fastest way to get the header spelling right.
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, addressed by row and field. |
| Plan ceiling | Applied to the total the import would leave behind, so re-importing existing SKUs costs nothing. |
| Delimiters | Comma-delimited CSV, or a tab-delimited range pasted straight from a spreadsheet. |