Package Sizing Flow

Overview

Use the Shipium Package Sizing API to determine an appropriate set of packaging types and sizes for one or more items to be shipped.

Setting up packaging details

Before using the Package Sizing API, you must use the Packaging configuration screen to set up packaging sizes that are available at each Fulfillment Center (FC) in your fulfillment network. There are two steps:

  1. Configure the packaging sizes that your company uses.
  2. Associate these box sizes with FCs that can support them. Any given packaging size can be active or inactive and associated with any, all, or none of your FCs.

Packaging size configuration

The following fields configure the packaging size, describing the package type, size, and allowable contents:

Packaging Element

Data Type

Description

Packaging Name

String

A descriptive name for this package size. Common patterns for naming are "LxWxH Box" (e.g. "12x10x4 Box"), "LxW Envelope" (e.g. "12x9 envelope") and "LxW Padded Envelope" (e.g. "12x9 padded envelope").

Note: this packageSizeName should be unique within your company's packaging sizes.

Packaging Active

String Enumeration:
Active or Inactive

Whether or not this packaging type should be considered when making packaging decisions.

Packaging Type

String Enumeration:
Box, Envelope, or Soft Pack

The type of packaging. Soft Pack is for bubble mailers or padded envelopes.

Linear Dimension Unit

String Enumeration:
IN, CM

The unit that linear dimensions are provided in, either IN for inches or CM for centimeters.

Length

Decimal Number

The longest linear dimension for this packaging type (e.g. the longest side of a box or envelope).

Width

Decimal Number

The second longest linear dimension for this packaging type (e.g. the second-longest side of a box of envelope.)

Height

Decimal Number

The least long linear dimension for this packaging type (e.g. the shortest side of a box or envelope.

Note: For envelopes this height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions.

Weight
Dimension Unit

String Enumeration:
G, KG, OZ, or LB.

The unit that weight values are provided in.
G for grams
KG for kilograms
OZ for ounces
LB for pounds

Packaging Weight

Decimal Number

The weight, as measured in Weight Dimension Unit, of this type of packaging when empty.

Max Content Weight

Decimal Number

The maximum weight, as measured in Weight Dimension Unit, that can be placed in this type of packaging.

Unsupported Products

Set of boolean values

When setting up packaging, you must mark if a given packaging type is not usable for certain types of product.

The common types of unsupported product are:
ORM-D / Regulated Materials
Lithium Ion Battery-Containing
Fragile

FCs Utilizing This Packaging

Boolean values for each FC

Any given piece of packaging can be configured as being used in any particular FC.

Note: If you are unsure about packaging weight, we recommend asking your fulfillment partner to weigh your various packaging sizes. If you need some help, we can provide some guidelines on packaging weight for standard package sizes that are probably close enough.

Example package sizes:

12-Bottle Wine Box:

  • Length: 13 inches
  • Width: 12 inches
  • Height: 10 inches
  • Weight: 415 grams (~ 15 ounces)

Padded Envelope

  • Length: 12 inches
  • Width: 9 inches
  • Height: 2 inches
  • Weight: 30 grams (~1.1 ounces)

Requesting a Package Size Estimate for a set of items

As with package sizes, dimensions and weight are passed for each item to be packed, along with their length and weight dimensions as well as an ID and relevant information about each product (for example is_ORMD).

One or more appropriate package sizes is then calculated for the set of items and an array of objects representing packages and the contents of each is returned.

📘

Authentication for API calls

In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both OAuth and API Key users.

Package Size Estimate

This example shows the cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/packageselection/ \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"fulfillmentCenterId":"59cd1539-7bd9-4275-8ed1-af9db56f9205","items":[{"productLinearDimensions": {"width": 2,"length": 2,"height": 2,"linearUnit": "in"},"productId": "item1","productWeight": {"weight": 2,"weightUnit": "oz"},"quantity":1,"productDetails": []},{"productLinearDimensions": {"width": 3,"length": 4,"height": 2,"linearUnit": "in"},"productId": "item2","productWeight": {"weight": 2,"weightUnit": "oz"},"quantity":2,"productDetails": []}]}'

This example shows a multi-item request:

{
  "fulfillmentCenterId": "72e0ed11-3e33-4567-af65-3180c6df6d2a",
  "items":
  [
    {
     "productId": "9781999194864",
     "productLinearDimensions":
     {
       "linearUnit": "in",
       "length": 8.0,
       "width": 5.0,
       "height": 0.3
     },
     "productWeight":
     {
       "weightUnit": "lb",
       "weight": 0.8
     },
     "quantity": 2,
    },
    {
     "productId": "9781932078428",
     "productLinearDimensions":
     {
       "linearUnit": "in",
       "length": 9.2,
       "width": 6.5,
       "height": 0.8
     },
     "productWeight":
     {
       "weightUnit": "lb",
       "weight": 1.8
     },
     "productDetails": ["ormd"],
     "quantity": 1
    }
   ]
}

The response contains a request ID for tracking purposes, a packageCount field, and a list of packages with their contents, quantities, and details. In this example the package contains two items:

{
  "packageSizingRequestId": "82171a4f-c098-439a-aa32-a139a8e6a28e",
  "partnerId": "0bdfa438-e90c-4054-8f67-28c4fc412ad3",
  "fulfillmentCenterId": "59cd1539-7bd9-4275-8ed1-af9db56f9205",
  "packageCount": 1,
  "packages": [
    {
      "packagingTypeId": "1bdae8f6-8613-4f26-832d-ac9c92243342",
      "packageEstimatedWeight": {
        "weightUnit": "lb",
        "weight": 2.375
      },
      "packageContents": [
        {
          "productId": "9781999194864",
          "quantity": 2
        },
        {
          "productId": "9781932078428",
          "quantity": 1
        }
      ]
    }
  ]
}

Items exceeding all Packaging Size dimensions

If you pass an item that exceeds the dimensions of all of the packaging sizes that you have set up, the returned packagingTypeId will be "CUSTOM", indicating that you will need to create some kind of custom packaging for this particular product or products.

The example below uses the same contents as the previous request, but assumes a world in which no appropriate packaging has been created that would hold an additional item (productId "LARGEITEM001"). In this case, there are multiple packages with a single "CUSTOM" package containing one or more outlier items. Here we are using the same basic example as above, but assume that there is one larger item that has been added that exceeds all configured packaging sizes.

{
  "fulfillmentCenterId": "72e0ed11-3e33-4567-af65-3180c6df6d2a",
  "packageCount": 2,
  "packageSizingRequestId": "cb4a9ce1-45b0-4c42-9e8b-51f29bfa3ea6",
  "packages":
  [
    {
      "packagingTypeId": "33732DE8-3AE7-4026-9A0F-DC2D7A31B6C6",
        "packageEstimatedWeight": {
            "weight": "2.8",
        "weightUnit": "lb"
        },
     "packageContents":
     [
       {"productId": "9781999194864", "quantity": 2},
       {"productId": "9781932078428", "quantity": 1}
     ]
    },
    {
      "packagingTypeId": "CUSTOM",
      "packageEstimatedWeight": {
        "weight": 10.0,
        "weightUnit": "lb"
      },
      "packageContents":
      [
        {"productId": "LARGEITEM001", "quantity": 1}
      ]
    }
  ]
}

📘

Note

In cases where a CUSTOM packaging type is required, only the item weights are included in the package's weight. The total weight will obviously be incorrect but we cannot really guess at the weight of the packaging for the CUSTOM case so instead provide the summed item weights.

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.


Did this page help you?