Cartons
How to write a variant's shipping boxes in one spreadsheet cell, which column settings apply, and how the cartons appear on the product. Sizes, weights and counts, several boxes per cell and several columns per file.
A sofa ships in two boxes, a dining set in four. Map a column to the cartons field and FurniOps
reads every box a variant ships in, with its size, its weight and how many of it there are. Those
boxes reach the product as the variant's cartons.
In short: cartons split on the column's separator (|), each size; weight; count in any order, e.g. 49 x 18 x 7 in; 60 lb; 2 boxes.
Writing a cell
A cell lists the variant's cartons. Cartons are separated by the column's
separator, a vertical bar (|) unless you set another. One carton's parts are
separated by a semicolon (;) and can come in any order:
| Part | Write it as | Rules |
|---|---|---|
| Size | 49 x 18 x 7 in, W49 x D18 x H7 in, W46 x H12 in | Width, depth and height, in that order or labelled. A side can be left out. With no unit in the cell, the column's unit applies. |
| Weight | 60 lb, 27.2 kg, 850 g, 12 oz | A number with its unit. A weight always names its own unit. |
| Count | 2 boxes, 1 carton, 3 ctns, x2 | How many of this box ship, from 1 to 100. One when left out. |
A carton needs at least one part. A box has a width, a depth and a height and nothing else, so a
size that names a seat height or an arm height is not a carton. Empty parts and placeholders
(N/A, TBD, -) say nothing, and a weight of zero counts as not known.
Examples
| Cell | Column settings | Reads as |
|---|---|---|
49 x 18 x 7 in; 60 lb; 2 boxes | 30 x 30 x 4 in; 22 lb | None | Three boxes of two kinds: two of 49 × 18 × 7 in at 60 lb, and one of 30 × 30 × 4 in at 22 lb. |
22 lb; x1; W30 x D30 x H4 in | None | One box of 30 × 30 × 4 in at 22 lb: the order of the parts does not matter. |
W46 x H12 in; 90.32 lb; 1 box | None | One box 46 in wide and 12 in high, its depth not given, at 90.32 lb. |
120 x 45 x 20; 27,5 kg | unit: cm, style: comma | One box of 120 × 45 × 20 cm at 27.5 kg. The size takes the column's unit. |
3 cartons / 40 lb | separator: / | Three boxes with no size or weight given, and one box at 40 lb. |
Column settings
A cartons column takes these settings:
| Setting | For cartons |
|---|---|
unit | A length unit (mm, cm, m, in or ft) for sizes written without one. A weight unit is refused, since every weight names its own. |
style | The decimal separator of the cell's numbers: dot (90.32) or comma (90,32). |
separator | What separates cartons in one cell: one to three characters, | when unset. It cannot contain ;, which separates one carton's parts. |
currency, axis and html do not apply to cartons. Confirming a mapping with a setting that does
not fit answers 422 and confirms nothing; each problem is in errors[], for example
"Box 1" (cartons): unit lb does not fit a cartons field.
{
"column": "Cartons (cm)",
"field": "cartons",
"settings": { "unit": "cm", "style": "comma" }
}Several columns
cartons takes several columns, so a file with Box 1, Box 2 and Box 3 maps each of them to
cartons. A row's cartons from all of them are one list, in column order. Each column keeps its own
settings.
On the product
The cartons are a variant's, under data.cartons of each variant in a product read
(GET /v1/products/{id}), at most 50 per variant. Each
carton has its count, and the width, depth, height and weight the cell gave. A length
holds hundredths_in and a weight hundredths_lb, so every carton compares in one unit, and both
keep what the source wrote in given.
The first example above reads as:
{
"cartons": [
{
"width": { "hundredths_in": 4900, "given": { "value": 49, "unit": "in" } },
"depth": { "hundredths_in": 1800, "given": { "value": 18, "unit": "in" } },
"height": { "hundredths_in": 700, "given": { "value": 7, "unit": "in" } },
"weight": { "hundredths_lb": 6000, "given": { "value": 60, "unit": "lb" } },
"count": 2
},
{
"width": { "hundredths_in": 3000, "given": { "value": 30, "unit": "in" } },
"depth": { "hundredths_in": 3000, "given": { "value": 30, "unit": "in" } },
"height": { "hundredths_in": 400, "given": { "value": 4, "unit": "in" } },
"weight": { "hundredths_lb": 2200, "given": { "value": 22, "unit": "lb" } },
"count": 1
}
]
}A change to a variant's cartons is announced as
variant.updated, with cartons among the
changed fields.
When a cell cannot be read
A cartons cell is read whole or not at all, because some of an item's boxes would look like all of them. The run records a problem for the cell, and the rest of the row is imported:
| Cell | problem |
|---|---|
A carton gives its size, weight or count twice (60 lb; 70 lb) | ambiguous |
A size has no unit, and the column has no unit (49 x 18 x 7) | ambiguous |
A part is neither a size, a weight nor a count (blue) | unparseable |
A size names something a box does not have (seat height 18 in) | unparseable |
| A count outside 1 to 100, a size past what can be stored, or more than 50 cartons | implausible |
When one of several cartons columns cannot be read, the row gives no cartons at all, for the same reason.
Mappings
How a file's columns become product, variant and offer fields. FurniOps proposes a mapping for every new set of headers, a person confirms it once, and every later file with those headers imports on its own. Fields, settings, tiers and confirming through the API.
Categories
The FurniOps taxonomy, and how each source's own category paths are filed into it with rules. Suggestions, inheritance, the most specific rule winning, and saving rules through the API.