Guides
Start typing to search…

Packaging Planner API

Select optimal packaging with Shipium's Packaging Planner API.

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.

To use the Packaging Planner API with packaging or package set IDs, you must first configure your account. Guidance can be found in the Packaging Planner documentation.

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.

API typeAPI endpoint
POSThttps://api.shipium.com/api/v1/packaging/planner
🔐

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.

Authenticating for Curl

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.

Algorithm namePacking algorithm valueDescription
StandardstandardA cubic packer that uses an algorithm to place items in packages based on their size and how they can fit together in packaging
VolumetricvolumetricA volumetric or "liquid" packing algorithm that fits items in packaging by first making sure that no item goes into a package if the item's height, width, or length exceeds the height, width, or length of a given package and after that assumes perfect volumetric packing within the package.
⚠️

Warning: We only recommend volumetric packing for certain specific use cases such as small parts (e.g., screws) or certain clothing use cases.

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

{
  "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

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

Packaging compression block in context of the items block

{
  "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

Field

Details

items

Type: Array of item objects
Description: A list of the items to be packed into an available box

packaging

Type: Array of packaging objects
Description: Dimensions and restrictions for available boxes to pack the items into. Must contain at least one item.

packaging.linearDimensions

Type: Object (linearDimensions)
Description: The linear dimensions and unit of a box available for packing

packaging.linearDimensions.length

Type: Decimal
Description: Length of the longest side of the box to be packed. Must be a value greater than zero.

packaging.linearDimensions.width

Type: Decimal
Description: Length of the second longest side of the box to be packed. Must be a value greater than zero.

packaging.linearDimensions.height

Type: Decimal
Description: Length of the shortest side of the box to be packed. Must be a value greater than zero.

packaging.linearDimensions.linearUnit

Type: String (enumeration)
Values: in (inch), cm (centimeter)
Description: The unit of measurement in which the linear dimensions of the box are specified

packaging.maxContentWeight

Type: Object (maxContentWeight)
Description: The maximum total combined weight of the items packed into the box

packaging.maxContentWeight.weight

Type: Decimal
Description: The maximum weight of all the packed items. Must be a positive value.

packaging.maxContentWeight.weightUnit

Type: String (enumeration)
Values: lb (pound), kg (kilogram)
Description: The unit of measurement in which the maximum weight is specified

packaging.packagingWeight

Type: Object (packagingWeight)
Description: The weight of the empty box

packaging.packagingWeight.weight

Type: Decimal
Description: The weight of the empty box. Must be a positive value.

packaging.packagingWeight.weightUnit

Type: String (enumeration)
Values: lb (pound), kg (kilogram)
Description: The unit of measurement in which the empty box weight is specified

packaging.packagingMaterial

Type: String (enumeration)
Values: box, envelope, flat_pack, mailing_tube, parcel_pallet
Description: The type of packaging used to create the package for the shipment

packaging.packagingSizeName

Type: String
Example: A1, 12x12x6 box
Description: The name your organization assigned to the specified box size

Optional fields

Field

Details

includeDetails

Type: Boolean
Values: true or false
Description: A flag indicating whether to include dimensional details of the items to be packed in the API call response. Defaults to true, which results in full linear dimensions of the items being returned in the API call response.

maxItemsPerPackage

Type: Integer (int32) Description: Passing this option will prevent any package returned from containing more than this number of items. Must be a value greater than 0.

referenceIdentifier

Type: String
Description: String passed to carriers as a reference. This field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name (e.g., referenceIdentifier2) up to 5 reference identifiers.

packaging.maxItemsPerPackage

Type: Integer (int32) Description: Passing this option will prevent any package returned from containing more than this number of items, at the individual packaging level. This value overrides the top-level maxItemsPerPackage value, if one was included. Must be a value greater than 0.

packaging.unsupportedProductDetails

Type: String (enumeration)
Values: ormd (other regulated materials—domestic), lio (lithium-ion), fragile
Description: Restricted product types that cannot be packed into this box (e.g., hazmat)

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

Field

Details

packingStrategyOptions.packingAlgorithm

Type: String (enumeration)
Values: standard, volumetric
Description: Specifies which packing algorithm to use. standard is a cubic packer that places items based on their size and how they fit together. volumetric is a "liquid" packing algorithm that fits items by ensuring no item dimension exceeds the package dimension, then assumes perfect volumetric packing.

packingStrategyOptions.packingAlgorithmOptions .volumetricPackingEfficiency

Type: Decimal
Condition: Applies only when using the volumetric algorithm Description: Constrains packing to be more (less than 1) or less (greater than 1) than the raw dimensions of the packaging. For example, a value of 0.9 allows the volume of packed items to be less than or equal to 90% of the packaging volume. Does not impact height, width, or length constraints—only volume limitations.

packingStrategyOptions.packingAlgorithmOptions .pureVolumetricPacking

Type: Boolean
Values: true or false
Condition: Applies only when using the volumetric algorithm
Description: When true, does not place restrictions on product height, width, or length relative to the packaging size. Selects packaging based purely on volumetric size, choosing the smallest volume that satisfies the condition that the sum of (item volume × item quantity) for all items is less than or equal to the package volume multiplied by volumetricPackingEfficiency. Defaults to false.

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

Field

Details

items.productCompressionFactor

Type: Object (productCompressionFactor)
Description: Compression factor settings that reflect the degree to which a product can be compressed in one or more dimensions (height, width, length)

items.productCompressionFactor.compressionFactor

Type: Decimal
Description: A value less than 1 that 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 of 4, given the compression formula of 5*(1 - 0.2).

items.productCompressionFactor.compressHeight

Type: Boolean
Values: true or false
Description: Indicates whether the compression factor should apply to the height dimension

items.productCompressionFactor.compressWidth

Type: Boolean
Values: true or false
Description: Indicates whether the compression factor should apply to the width dimension

items.productCompressionFactor.compressLength

Type: Boolean
Values: true or false
Description: Indicates whether the compression factor should apply to the length dimension

Example cURL call

curl --request POST \
  --url https://api.shipium.com/api/v1/packaging/planner \
  --header 'accept: application/json' \
  --header "$AUTHSTRING" \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "packaging": [
    {
      "linearDimensions": {
        "height": 1,
        "length": 1,
        "linearUnit": "in",
        "width": 1
      },
      "maxContentWeight": {
        "weight": 50,
        "weightUnit": "lb"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "1x1x1",
      "packagingWeight": {
        "weight": 1,
        "weightUnit": "lb"
      },
      "maxItemsPerPackage": 10
    },
    {
      "linearDimensions": {
        "height": 10,
        "length": 10,
        "linearUnit": "in",
        "width": 10
      },
      "maxContentWeight": {
        "weight": 50,
        "weightUnit": "lb"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "10x10x10",
      "packagingWeight": {
        "weight": 1,
        "weightUnit": "lb"
      },
      "maxItemsPerPackage": 20
    },
    {
      "linearDimensions": {
        "height": 6,
        "length": 6,
        "linearUnit": "in",
        "width": 6
      },
      "maxContentWeight": {
        "weight": 50,
        "weightUnit": "lb"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "6x6x6",
      "packagingWeight": {
        "weight": 1,
        "weightUnit": "lb"
      },
      "maxItemsPerPackage": 15
    }
  ],
  "referenceIdentifier": "PACKAGE_A",  
  "items": [
    {
      "productLinearDimensions": {
        "width": 2,
        "length": 2,
        "height": 2,
        "linearUnit": "in"
      },
      "productId": "item1",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1
    },
    {
      "productLinearDimensions": {
        "width": 4,
        "length": 4,
        "height": 4,
        "linearUnit": "in"
      },
      "productId": "item2",
      "productWeight": {
        "weight": 1,
        "weightUnit": "oz"
      },
      "quantity": 1
    }
  ]
}

Example standard response

{
  "referenceIdentifier": "PACKAGE_A",
  "packagePlanId": "5fd53424-c47f-4acd-8d8d-b950adf641ee", 
  "packageCount": 1,
  "unpackableItems": [],
  "packages": [
    {
      "packagePlanPackageId": "d696b20e-b060-4169-89e7-75178135b7f1", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productLinearDimensions": {
            "width": 1,
            "length": 2,
            "height": 1,
            "linearUnit": "in"
          },
          "productId": "item2",
          "productWeight": {
            "weight": 2,
            "weightUnit": "oz"
          },
          "quantity": 2,
          "productDetails": []
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Example response for unpackable items

{
  "referenceIdentifier": "PACKAGE_A",
  "packagePlanId": "f5a6e6de-9df3-48f1-9171-dcce9947576a", 
  "packageCount": 1,
  "unpackableItems": [
    {
      "productLinearDimensions": {
        "width": 100,
        "length": 200,
        "height": 100,
        "linearUnit": "in"
      },
      "productId": "bigolproductthatisstillsomehow2oz",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1,
      "productDetails": []
    }
  ],
  "packages": [
    {
      "packagePlanPackageId": "27ed6590-f068-4168-8e2c-2fa0fbf73957", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productLinearDimensions": {
            "width": 1,
            "length": 2,
            "height": 1,
            "linearUnit": "in"
          },
          "productId": "item2",
          "productWeight": {
            "weight": 2,
            "weightUnit": "oz"
          },
          "quantity": 2,
          "productDetails": []
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Example response for unpackable items and request to not include product details in response

{
  "referenceIdentifier": "PACKAGE_A",
  "packagePlanId": "e56cbc7d-a630-4ed6-9da8-4e77166b23e8", 
  "packageCount": 1,
  "unpackableItems": [
    {
      "productId": "bigolproductthatisstillsomehow2oz",
      "quantity": 1
    }
  ],
  "packages": [
    {
      "packagePlanPackageId": "4353ea95-4a7c-40f4-8998-5bd17a4bf676", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productId": "item2",
          "quantity": 2
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Retrieve packaging guidance by including packaging IDs in the API call

To use the API in this way, you'll need to include a packagingId value. You can include the value Shipium generated (Packaging ID) or the one you assigned to the packaging (Packaging ID Alias) when you configured your packaging in the Shipium Console.

Obtain the packagingId value needed for the API call

To retrieve the packagingId value to pass in the API call, you'll need to access the details of your newly created packaging by selecting Detail within its card on your Packaging homepage.

The Packaging ID value to copy is located near the top left of the details screen, as shown in the following screenshot. You'll include this value as the packagingId when calling Shipium's APIs.

The following tables provide all required and optional fields for calling the Packaging Planner API with packaging ID(s). You can find additional support in the Packaging Planner API Reference.

Required fields

Field

Details

includeDetails

Type: Boolean
Values: true or false
Description: A flag indicating whether to include dimensional details of the items to be packed in the API call response. Defaults to true, which results in full linear dimensions of the items being returned in the API call response.

items

Type: Array of item objects
Description: A list of the items to be packed into an available box

packagingIds

Type: Array of strings
Description: A list of strings representing the Shipium-generated ID or the alias ID your organization provided for a packaging asset configured through the Shipium Console. The alias ID is case sensitive.

Optional fields

Field

Details

maxItemsPerPackage

Type: Integer (int32)
Description: Passing this option will prevent any package returned from containing more than this number of items. Must be a value greater than 0.

referenceIdentifier

Type: String
Description: String passed to carriers as a reference. This field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name (e.g., referenceIdentifier2) up to 5 reference identifiers.

Example cURL call

curl --request POST \
  --url https://api.shipium.com/api/v1/packaging/planner \
  --header 'accept: application/json' \
  --header "$AUTHSTRING" \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "packagingIds": ["reno-fc-package-large","5463ceca-15f4-11ee-be56-0242ac120002"],
  "referenceIdentifier": "BOX_9",  
  "items": [
    {
      "productLinearDimensions": {
        "width": 2,
        "length": 2,
        "height": 2,
        "linearUnit": "in"
      },
      "productId": "item1",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1
    },
    {
      "productLinearDimensions": {
        "width": 4,
        "length": 4,
        "height": 4,
        "linearUnit": "in"
      },
      "productId": "item2",
      "productWeight": {
        "weight": 1,
        "weightUnit": "oz"
      },
      "quantity": 1
    }
  ]
}

Example standard response

{
  "referenceIdentifier": "BOX_9",
  "packagePlanId": "01b727d9-dd1c-4b57-b51a-9b6d49b73534", 
  "packageCount": 1,
  "packages": [
    {
      "packagePlanPackageId": "467b50bc-988e-4e9a-a520-4b6a63c9ced8", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packagingTypeId": "12313123",
      "packageContents": [
        {
          "productLinearDimensions": {
            "width": 1,
            "length": 2,
            "height": 1,
            "linearUnit": "in"
          },
          "productId": "item2",
          "productWeight": {
            "weight": 2,
            "weightUnit": "oz"
          },
          "quantity": 2,
          "productDetails": []
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Example response for request to not include product details in response

{
  "referenceIdentifier": "BOX_9",
  "packagePlanId": "77db2333-ddd2-4824-be9d-b7f5c11de3cc", 
  "packageCount": 1,
  "packages": [
    {
      "packagePlanPackageId": "9077bcdd-911d-4b4c-88c7-b1a0a40f5eb0", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packagingTypeId": "12313123",
      "packageContents": [
        {
          "productId": "item2",
          "quantity": 2
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Retrieve packaging guidance by including packaging set IDs in the API call

To use the API in this way, you'll need to include a packagingSetId value. You can include the value Shipium generated (Packaging Set ID) or the one you assigned to the packaging (Packaging Set ID Alias) when you configured your packaging in the Shipium Console.

Obtain the packagingSetId value needed for the API call

To retrieve the packagingSetId value to pass in the API call, you'll need to access the details of your newly created packaging set by selecting Detail within its card on your Packaging Set homepage.

The Packaging Set ID value to copy is located near the top left of the details screen, as shown in the following screenshot. You'll include this value as the packagingSetId when calling Shipium's APIs.

The following tables provide all required and optional fields for calling the Packaging Planner API with packaging set ID(s). You can find additional support in the Packaging Planner API Reference.

Required fields

Field

Details

items

Type: Array of item objects
Description: A list of the items to be packed into an available box

items.productId

Type: String
Description: Identifier for the product being packed. Required when products cannot fit into a single box and need to be split into two boxes.

items.productLinearDimensions

Type: Object (productLinearDimensions)
Description: The linear dimensions and unit of an item to be packed

items.productLinearDimensions.length

Type: Decimal
Description: Length of the longest side of the item to be packed. Must be a value greater than zero.

items.productLinearDimensions.width

Type: Decimal
Description: Length of the second longest side of the item to be packed. Must be a value greater than zero.

items.productLinearDimensions.height

Type: Decimal
Description: Length of the shortest side of the item to be packed. Must be a value greater than zero.

items.productLinearDimensions.linearUnit

Type: String (enumeration)
Values: in (inch), cm (centimeter)
Description: The unit of measurement the size of the item to be packed is specified in

items.productWeight

Type: Object (productWeight)
Description: The weight of the item to be packed

items.productWeight.weight

Type: Decimal
Description: The weight of the item to be packed. Must be a value greater than zero.

items.productWeight.weightUnit

Type: String (enumeration)
Values: lb (pound), kg (kilogram)
Description: The unit of measurement the weight of the item to be packed is specified in

items.quantity

Type: Integer (int32)
Description: The number of items to be packed. Must be a value greater than zero.

packagingSetId

Type: String
Description: The Shipium-generated ID or the alias ID your organization provided for a packaging set asset configured through the Shipium Console. The alias ID is case sensitive.

Optional fields

Field

Details

includeDetails

Type: Boolean
Values: true or false
Description: A flag indicating whether to include dimensional details of the items to be packed in the API call response. Defaults to true, which results in full linear dimensions of the items being returned in the API call response.

maxItemsPerPackage

Type: Integer (int32)
Description: Passing this option will prevent any package returned from containing more than this number of items. Must be a value greater than 0.

referenceIdentifier

Type: String
Description: String passed to carriers as a reference. This field can be expanded to include multiple reference identifiers by adding sequential numbers to the field name (e.g., referenceIdentifier2) up to 5 reference identifiers.

items.productDetails

Type: String (enumeration)
Values: ormd (other regulated materials—domestic), lio (lithium-ion), fragile
Description: Product details that could affect the boxes available to pack the items into, due to box type restrictions for shipping these types of products

items.productReferenceIdentifier

Type: String
Description: An optional identifier value that your organization may wish to include for the product

Example cURL call

curl --request POST \
  --url https://api.shipium.com/api/v1/packaging/planner \
  --header 'accept: application/json' \
  --header "$AUTHSTRING" \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

{
  "packagingSetId": "reno-fc-packaging",
  "referenceIdentifier": "PACKAGE_B",  
  "items": [
    {
      "productLinearDimensions": {
        "width": 2,
        "length": 2,
        "height": 2,
        "linearUnit": "in"
      },
      "productId": "item1",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1
    },
    {
      "productLinearDimensions": {
        "width": 4,
        "length": 4,
        "height": 4,
        "linearUnit": "in"
      },
      "productId": "item2",
      "productReferenceIdentifier": "series8item",
      "productWeight": {
        "weight": 1,
        "weightUnit": "oz"
      },
      "quantity": 1
    }
  ]
}

Example standard response

{
  "referenceIdentifier": "PACKAGE_B",
  "packagePlanId": "98e713de-ede9-4539-8cda-bf30df660415", 
  "packageCount": 1,
  "unpackableItems": [
    {
      "productLinearDimensions": {
        "width": 100,
        "length": 200,
        "height": 100,
        "linearUnit": "in"
      },
      "productId": "bigolproductthatisstillsomehow2oz",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1,
      "productDetails": []
    }
  ],
  "packages": [
    {
      "packagePlanPackageId": "d015ac15-2d06-48ee-88c3-1da475e5d0c7", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingTypeId": "medium",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productLinearDimensions": {
            "width": 1,
            "length": 2,
            "height": 1,
            "linearUnit": "in"
          },
          "productId": "item2",
          "productReferenceIdentifier": "series8item",
          "productWeight": {
            "weight": 2,
            "weightUnit": "oz"
          },
          "quantity": 2,
          "productDetails": []
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Example response for unpackable items

{
  "referenceIdentifier": "PACKAGE_B",
  "packagePlanId": "718a2543-0c35-458b-83c0-f2446947e33c", 
  "packageCount": 1,
  "unpackableItems": [
    {
      "productLinearDimensions": {
        "width": 100,
        "length": 200,
        "height": 100,
        "linearUnit": "in"
      },
      "productId": "bigolproductthatisstillsomehow2oz",
      "productWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "quantity": 1,
      "productDetails": []
    }
  ],
  "packages": [
    {
      "packagePlanPackageId": "555dfcac-30e4-4899-8347-aad2a9571718", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingTypeId": "medium",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productLinearDimensions": {
            "width": 1,
            "length": 2,
            "height": 1,
            "linearUnit": "in"
          },
          "productId": "item2",
          "productReferenceIdentifier": "series8item",
          "productWeight": {
            "weight": 2,
            "weightUnit": "oz"
          },
          "quantity": 2,
          "productDetails": []
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

Example response for unpackable items and request to not include product details in response

{
  "referenceIdentifier": "PACKAGE_B",
  "packagePlanId": "0c6e3be0-f8da-4dd1-8ef9-9da5f8ccb469",
  "packageCount": 1,
  "unpackableItems": [
    {
      "productId": "bigolproductthatisstillsomehow2oz",
      "quantity": 1
    }
  ],
  "packages": [
    {
      "packagePlanPackageId": "0304a14a-a1e9-41b9-b545-935eaf9a392f", 
      "linearDimensions": {
        "linearUnit": "in",
        "length": 5.5,
        "height": 5,
        "width": 5
      },
      "maxContentWeight": {
        "weight": 100,
        "weightUnit": "oz"
      },
      "packagingWeight": {
        "weight": 2,
        "weightUnit": "oz"
      },
      "packagingMaterial": "box",
      "packagingTypeId": "medium",
      "packagingSizeName": "5x5x5",
      "packageEstimatedWeight": {
        "weight": 3,
        "weightUnit": "oz"
      },
      "packageContents": [
        {
          "productId": "item2",
          "quantity": 2
        }
      ]
    }
  ],
  "volumetricPackEfficiency": 46.55
}

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.

Response attributeDescription
packagePlanIdA universally unique identifier (UUID) value representing this unique package plan response
packageCountThe number of boxes that the items were packed into. This will be 1 unless the items are evaluated not to fit into the largest box available. The prioritization is the use of one box.
packagesThe boxes that were selected and the items that were packed into each box
packages.packagePlanPackageIdA UUID uniquely identifying this package as part of this unique plan
packages.linearDimensionsLinear dimensions and unit of measurement of the box available for items to be packed into
packages.linearDimensions.lengthThe numerical value of the longest side of the box
packages.linearDimensions.widthThe numerical value of the second longest side of the box
packages.linearDimensions.heightThe numerical value of the shortest side of the box
packages.linearDimensions.linearUnitUnits dimensions specified in either centimeters or inches
packages.maxContentWeightMaximum total combined weight of the items packed into the box
packages.maxContentWeight.weightMaximum weight of the packed items
packages.maxContentWeight.weightUnitThe unit of measurement the maximum weight is specified in
packages.packageContentsA list of the items packed into the box
packages.packageEstimatedWeightThe estimated weight of the packed box and all its contents
packages.packageEstimatedWeight.weightThe weight of the packed box
packages.packageEstimatedWeight.weightUnitThe unit of measurement the estimated weight is specified in
packages.packagingTypeIdThe Shipium ID value for the packaging that was selected. Note: This response attribute is only returned when calling the API with Packaging ID(s) or Packaging Set ID(s).
packages.packagingSizeNameThe name assigned to the specified box size
packages.packagingWeightThe weight of the empty packaging
packages.packagingWeight.weightThe weight of the unpacked, empty box
packages.packagingWeight.weightUnitThe unit of measurement the packaging weight is specified in
volumetricPackEfficiencyCalculation of the entire volume of packed items and the selected box's available volume
maxItemsPerPackageThe maximum number of items allowed to be packed in the package
referenceIdentifierString passed to carriers as a reference (referenceIdentifier, referenceIdentifier2, etc.)

Resources

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

Updated about 11 hours ago

What’s Next