Get started

The Packaging Planner API typically is called with three different kinds of data, depending on the use case: full linear dimensions, packaging IDs, or package set IDs. To call the API using full linear dimensions, you can begin with the instructions in this document.

Retrieve packaging guidance from the Packaging Planner API

The Shipium Packaging Planner API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Packaging Planner API calls is included in the table below.

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 API Key and OAuth users.

Shipium assumptions for the Packaging Planner API

Package and content properties

All items being packed and all packages being packed into are three-dimensional, solid, rectangular objects or can be represented as such.

Packing strategies

When retrieving packaging guidance, you can specify different options that affect which packing algorithm is used. You also can include a compression factor to be applied to your packing strategy.

Packing algorithms

The packing algorithms currently supported are listed in the following table.

Volumetric packing algorithm options

When using the volumetric algorithm, you can specify a packingAlgorithmOptions.volumetricPackingEfficiency that will allow your packing to be constrained more (less than 1) or less (greater than 1) than the raw dimensions of the packaging. For instance, if you set volumetricPackingEfficiency to a value of 0.9, then the algorithm will only allow the volume of items packed to be less than or equal to 90% of the calculated volume of the packaging. (This does not impact any of the height, width, or length constraints – only volume limitations.)

Another optional specification within packingAlgorithmOptions is pureVolumetricPacking. This option does not place restrictions on product height, width, or length relative to the size of the packaging. Instead, it enables selection of packaging based purely on volumetric size. This means that it selects the packaging option with the smallest volume that satisfies the condition that the sum of the item volume times the item quantity for all items passed must be less than or equal to the volume of the package, multiplied by the passed volumetricPackingEfficiency. The pureVolumetricPacking field is boolean and defaults to a value of "false".

Packing algorithm block example

JSON

{
  "packingStrategyOptions": {
    "packingAlgorithm": "volumetric",
    "packingAlgorithmOptions": {
      "pureVolumetricPacking": true,
      "volumetricPackingEfficiency": 1.0
    }
  }
}

Packing compression

You can opt to include a compression factor in your packing strategy, whether standard or volumetric, that reflects the degree to which a product can be compressed in one or more dimensions (i.e., height, width, length). You'll specify values for the productCompressionFactor property within the items array. When specifying compression, you'll express a compressionFactor value, which is less than 1 and represents the degree to which any given dimension should be compressed. For example, a compressionFactor of 0.2 applied to a dimension with a value of 5 would result in a new value being used in packing equal to 4, given the compression formula of 5*(1 - 0.2). To determine the dimension(s) to which the compression factor should apply, you'll provide a boolean value of true or false for the compressionHeight, compressionWidth, and compressionLength.

Packing compression block example

JSON

{
  "productCompressionFactor": {
    "compressionFactor": 0.2,
    "compressHeight": true,
    "compressWidth": false,
    "compressLength": false
  }
}

Packaging compression block in context of the items block

JSON

{
  "items": [
    {
      "productId": "item1",
      "productLinearDimensions": {
        "width": 1,
        "length": 1,
        "height": 1,
        "linearUnit": "in"
      },
      "productWeight": { "weight": 1, "weightUnit": "oz" },
      "quantity": 5,
      "productCompressionFactor": {
        "compressionFactor": 0.1,
        "compressDepth": true,
        "compressWidth": true,
        "compressHeight": true
      }
    }
  ]
}

Retrieve packaging guidance by including full linear dimensions in the API call (primary use case)

The following tables provide all required and optional fields for calling the Packaging Planner API with full linear dimensions of your package contents. You can find additional support in the Packaging Planner API Reference.

Required fields

Optional fields

Packing strategy options (applies to all use cases)

The following optional fields can be included with any of the above use cases to specify packing algorithm behavior.

Optional fields

Packing compression options (applies to all use cases)

The following optional fields can be included within the items array for any use case to specify compression behavior.

Optional fields

Response attributes for the Packaging Planner API

The Packaging Planner response attributes for passing full linear dimensions, packaging IDs, and packaging set IDs in the API call are defined in the following table.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions
• Troubleshooting Guide
• Contact Shipium Support

Updated 6 months ago

What’s Next

• Packaging Planner