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:

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.