Packaging How-to¶

What is “packaging”? A box consists of “line items” put inside some “packaging” – the packaging is the outside of the package, the hull. Like packaging could be “a shoe box” and the shoes would be the line items.

When we talk about the “physical size of a box”, it’s really about the size of the packaging. So let’s say our shoebox is 30 x 20 x 20 cm. In this case the packaging “length” is 30 cm.

To help make it easier to specify standard sized boxes we also have the “packaging” presets. For example, maybe you have a packaging preset called “SHOEBOX1” and it’s 30x20x20 cm. What this means is that if there is no specific size given to the box, but it does use the “SHOEBOX1” packaging preset, then it will be 30 cm wide.

Remember that implicit values are “soft” values that can change as external factors change. So if we later change the packaging preset “SHOEBOX1” to be 40 cm wide, then the effective packaging length of every box using this preset will also change to 40 cm.

But on the other hand, if we take 1 particular box with the packaging preset “SHOEBOX1” and we change the length property of that box to 29 cm, then only this box gets a length of 29 cm.

About weights¶

Packaging weights are different from packaging dimensions in one important aspect: they add to the implicit weight of the box. While a box can only have one length, height and width, weight compounds. So in our example above the SHOEBOX1 packaging was 40 cm while the box length was 29 cm and in the end the 29 cm length “won”.

When you put something inside of a box that’s 30x20x20 cm, the size of the box is 30x20x20 regardless of how big the item you put inside was, since the packaging entirely “surrounds” the contents.

But this is not true for weights. If you put 500 g inside of a shoebox which by itself weighs 20 g, the total weight of the box is 520 g.

The box weight, if given explicitly, still trumps both the packaging weight and the item weight. More on this later.

Some examples¶

Here’s our shoe box:

"packaging": {
    "url": "/api/v2/orgs/1/packaging/1/",
    "name": "SHOEBOX1",
    "type": "Flat",
    "weight": "25 g",
    "length": "0.3 m",
    "width": "0.2 m",
    "height": "0.2 m"
}

It’s 30 cm long and weighs 25 grams.

Now let’s use it to describe the packaging of a box (some fields omitted):

{
    "url": "/api/v2/orgs/1/orders/1/boxes/1/",
    "package_type": null,
    "length": null,
    "width": null,
    "height": null,
    "weight": "800 g",
    "packaging": null
}

This box weighs 800 grams and we don’t know its size. Let’s define its size using SHOEBOX1:

PATCH /api/v2/orgs/1/orders/1/boxes/1/
{"packaging": {"url": "/api/v2/orgs/1/packaging/1/"}}

If this packaging didn’t exist, this PATCH would fail.

But it does exist so now the box looks like this:

{
    "url": "/api/v2/orgs/1/orders/1/boxes/1/",
    "package_type": null,
    "length": null,
    "width": null,
    "height": null,
    "weight": "800 g",
    "packaging": {
        "url": "/api/v2/orgs/1/packaging/1/",
        "name": "SHOEBOX1",
        "type": "Flat",
        "weight": "25 g",
        "length": "0.3 m",
        "width": "0.2 m",
        "height": "0.2 m"
    }
}

Now the size of this box is 30 x 20 x 20 cm.

Let’s override it:

PATCH /api/v2/orgs/1/orders/1/boxes/1/
{"length": "40 cm"}

Now we have:

{
    "url": "/api/v2/orgs/1/orders/1/boxes/1/",
    "package_type": null,
    "length": "0.4 m",
    "width": null,
    "height": null,
    "weight": "800 g",
    "packaging": {
        "url": "/api/v2/orgs/1/packaging/1/",
        "name": "SHOEBOX1",
        "type": "Flat",
        "weight": "25 g",
        "length": "0.3 m",
        "width": "0.2 m",
        "height": "0.2 m"
    }
}

On weight¶

The weight field sets the weight for the whole box explicitly. Since it’s currently set, the box weighs 800 grams. Let’s clear it:

PATCH /api/v2/orgs/1/orders/1/boxes/1/
{"weight": null}

What’s the effective weight of the box now?

It depends on the total weight of the line items. We didn’t define any items in the example, but let’s say there are 2 items and they weight 10 and 30 g each. Then:

box.effective_weight = 1 x 10g + 1 x 30g + 25g

The 25g is the weight of the packaging itself. The shoebox is made out of paper and it actually weighs something so when calculating the total effective box weight we consider the items and the packaging together.