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:
- Configure the packaging sizes that your company uses.
- 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.
Updated about 1 year ago