Working with Handling Units

3 min

As outlined in our Api SchemaAPI schema, Paccurate’s key inputs are items with specific dimensions, weights, and quantities. Properly defining 3D measurements of the items that need to be packed ensures proper item placement and box selection. In practice however, shippers do not always want to use single packs. In order to support multiple handling units of the same product, Paccurate supports the concept of a dimensionSet - a collection of defined dimensions and weights that correspond to specific quantities in the order.

Using a dimensionSet, customers can tell the Paccurate API to determine which defined set (or combination of sets) is the most appropriate to fulfill the order. A common example of this would be sending a case of an item as opposed to a number of singles.

Defining a dimensionSet

A dimensionSet entry contains the following properties:

weight : Number, the weight of the defined dimensionSet

unitOfMeasure : String, the name of the defined handling unit. Examples may be “each”, “case” or “pallet”

quantityDivisor : Number, the quantity of the item contained in the dimensionSet.

dimensions : Point with x, y, and z properties that define the dimensions of the set.

axisMultipliers : Point with x, y, and z properties that are applied to the basis of the dimension set (an each).

Example Payload Using dimensionSets

Request

Response

{"itemSets": [
    {
      "refId": 5854,
      "dimensionSets": [
        {
          "dimensions": {
            "x": 6,
            "y": 3,
            "z": 3
          },
          "weight": 0.33,
          "unitOfMeasure": "bottle",
          "quantityDivisor": 1
        },
        {
          "dimensions": {
            "x": 8,
            "y": 12,
            "z": 16
          },
          "weight": 4,
          "quantityDivisor": 12,
          "unitOfMeasure": "case"
        }
      ],
      "name": "Water Bottle",
      "quantity": 15
    }
  ]}

{
  "boxTypeChoiceGoalUsed": "most-items",
  "boxes": [
    {
      "box": {
        "boxType": {
          "centerOfMass": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "dimensions": {
            "x": 9,
            "y": 13,
            "z": 16
          },
          "itemsInlineOverhang": {
            "x": -1,
            "y": -1,
            "z": -1
          },
          "name": "XL",
          "price": 0,
          "rateTable": {
            "basePrice": 0,
            "carrier": "",
            "dimFactor": 0,
            "priceIncreaseRate": 0,
            "rates": null,
            "service": "",
            "weights": null,
            "zone": ""
          },
          "refId": 9,
          "reservedSpace": null,
          "weightMax": 50,
          "weightTare": 0
        },
        "centerOfMass": {
          "x": 4,
          "y": 6,
          "z": 8
        },
        "centerOfMassString": "[4 6 8]",
        "depthOrder": [
          1
        ],
        "depthOrderString": "[1]",
        "dimensionalWeight": 0,
        "dimensionalWeightUsed": false,
        "dimensions": {
          "x": 9,
          "y": 13,
          "z": 16
        },
        "id": 0,
        "items": [
          {
            "item": {
              "centerOfMass": {
                "x": 4,
                "y": 6,
                "z": 8
              },
              "color": "mediumseagreen",
              "deltaCost": 1872,
              "dimensionSet": {
                "dimensions": {
                  "x": 8,
                  "y": 12,
                  "z": 16
                },
                "unitOfMeasure": "case",
                "quantityDivisor": 12,
                "weight": 4
              },
              "dimensions": {
                "x": 8,
                "y": 12,
                "z": 16
              },
              "globalId": 0,
              "index": 1,
              "message": "packed #0 in 2.382551ms at 3.032102ms in Box(name:XL dimensions:[9,13,16] weight:50 index:0)",
              "name": "Water Bottle [case]",
              "origin": {
                "x": 0,
                "y": 0,
                "z": 0
              },
              "packedIndex": 0,
              "properties": null,
              "quantity": 12,
              "refId": 5854,
              "sequence": "",
              "uniqueId": "5854-0",
              "unitOfMeasure": "case",
              "virtual": false,
              "weight": 4
            }
          }
        ],
        "lenItems": 12,
        "lenUnits": 1,
        "name": "XL",
        "origin": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "price": 1872,
        "properties": null,
        "propertyConstraints": null,
        "refId": 9,
        "subspace": null,
        "volumeMax": 1872,
        "volumeNet": 1536,
        "volumeRemaining": 336,
        "volumeReserved": 0,
        "volumeUsed": 1536,
        "volumeUtilization": 0.8205128205128205,
        "weightMax": 50,
        "weightNet": 4,
        "weightRemaining": 46,
        "weightTare": 0,
        "weightUsed": 4,
        "weightUtilization": 0.08
      }
    },
    {
      "box": {
        "boxType": {
          "centerOfMass": {
            "x": 0,
            "y": 0,
            "z": 0
          },
          "dimensions": {
            "x": 9,
            "y": 13,
            "z": 16
          },
          "itemsInlineOverhang": {
            "x": -1,
            "y": -1,
            "z": -1
          },
          "name": "XL",
          "price": 0,
          "rateTable": {
            "basePrice": 0,
            "carrier": "",
            "dimFactor": 0,
            "priceIncreaseRate": 0,
            "rates": null,
            "service": "",
            "weights": null,
            "zone": ""
          },
          "refId": 9,
          "reservedSpace": null,
          "weightMax": 50,
          "weightTare": 0
        },
        "centerOfMass": {
          "x": 3,
          "y": 1.5,
          "z": 4.5
        },
        "centerOfMassString": "[2.9999999999999996 1.4999999999999998 4.500000000000007]",
        "depthOrder": [
          3,
          4,
          5
        ],
        "depthOrderString": "[3 4 5]",
        "dimensionalWeight": 0,
        "dimensionalWeightUsed": false,
        "dimensions": {
          "x": 9,
          "y": 13,
          "z": 16
        },
        "id": 1,
        "items": [
          {
            "item": {
              "centerOfMass": {
                "x": 3,
                "y": 1.5,
                "z": 1.5
              },
              "color": "mediumseagreen",
              "deltaCost": 1872,
              "dimensionSet": {
                "dimensions": {
                  "x": 6,
                  "y": 3,
                  "z": 3
                },
                "unitOfMeasure": "bottle",
                "quantityDivisor": 1,
                "weight": 0.33
              },
              "dimensions": {
                "x": 6,
                "y": 3,
                "z": 3
              },
              "globalId": 1,
              "index": 3,
              "message": "packed #1 in 560.511µs at 3.598393ms in Box(name:XL dimensions:[9,13,16] weight:50 index:1)",
              "name": "Water Bottle [bottle]",
              "origin": {
                "x": 0,
                "y": 0,
                "z": 0
              },
              "packedIndex": 1,
              "properties": null,
              "quantity": 1,
              "refId": 5854,
              "sequence": "",
              "uniqueId": "5854-1",
              "unitOfMeasure": "bottle",
              "virtual": false,
              "weight": 0.33
            }
          },
          {
            "item": {
              "centerOfMass": {
                "x": 3,
                "y": 1.5,
                "z": 4.5
              },
              "color": "mediumseagreen",
              "deltaCost": 0,
              "dimensionSet": {
                "dimensions": {
                  "x": 6,
                  "y": 3,
                  "z": 3
                },
                "unitOfMeasure": "bottle",
                "quantityDivisor": 1,
                "weight": 0.33
              },
              "dimensions": {
                "x": 6,
                "y": 3,
                "z": 3
              },
              "globalId": 2,
              "index": 4,
              "message": "packed #2 in 4.23µs at 3.606443ms in Box(name:XL dimensions:[9,13,16] weight:50 index:1)",
              "name": "Water Bottle [bottle]",
              "origin": {
                "x": 0,
                "y": 0,
                "z": 3
              },
              "packedIndex": 2,
              "properties": null,
              "quantity": 1,
              "refId": 5854,
              "sequence": "",
              "uniqueId": "5854-2",
              "unitOfMeasure": "bottle",
              "virtual": false,
              "weight": 0.33
            }
          },
          {
            "item": {
              "centerOfMass": {
                "x": 3,
                "y": 1.5,
                "z": 7.5
              },
              "color": "mediumseagreen",
              "deltaCost": 0,
              "dimensionSet": {
                "dimensions": {
                  "x": 6,
                  "y": 3,
                  "z": 3
                },
                "unitOfMeasure": "bottle",
                "quantityDivisor": 1,
                "weight": 0.33
              },
              "dimensions": {
                "x": 6,
                "y": 3,
                "z": 3
              },
              "globalId": 3,
              "index": 5,
              "message": "packed #3 in 4.09µs at 3.611703ms in Box(name:XL dimensions:[9,13,16] weight:50 index:1)",
              "name": "Water Bottle [bottle]",
              "origin": {
                "x": 0,
                "y": 0,
                "z": 6
              },
              "packedIndex": 3,
              "properties": null,
              "quantity": 1,
              "refId": 5854,
              "sequence": "",
              "uniqueId": "5854-3",
              "unitOfMeasure": "bottle",
              "virtual": false,
              "weight": 0.33
            }
          }
        ],
        "lenItems": 3,
        "lenUnits": 3,
        "name": "XL",
        "origin": {
          "x": 0,
          "y": 0,
          "z": 0
        },
        "price": 1872,
        "properties": null,
        "propertyConstraints": null,
        "refId": 9,
        "subspace": null,
        "volumeMax": 1872,
        "volumeNet": 162,
        "volumeRemaining": 1710,
        "volumeReserved": 0,
        "volumeUsed": 162,
        "volumeUtilization": 0.08653846153846154,
        "weightMax": 50,
        "weightNet": 0.9899999999999949,
        "weightRemaining": 49.010000000000005,
        "weightTare": 0,
        "weightUsed": 0.99,
        "weightUtilization": 0.019799999999999898
      }
    }
  ],
  "built": "2025-06-01T22:49:36.861506041Z",
  "host": "api.prod.paccurate.io",
  "itemSortReverseUsed": false,
  "itemSortUsed": "none",
  "leftovers": [],
  "lenBoxes": 2,
  "lenItems": 15,
  "lenLeftovers": 0,
  "lenUnits": 4,
  "orderId": "10001",
  "packTime": 0.003616623,
  "packUuid": "b1ef2155bd714a5b80001aef755ca22d5871da93a30d422a3f16b7050a41aea20aa354eca793c9b60e735e13acbaf3c8958e8a802d030b131f1d186e9477505b",
  "renderTime": 0.00090166,
  "requestFingerprint": "bac0c33063633979b73317408d5ebb1556d359a97f0f13b85d61be139218258951cc87c505ec0c11dc912e612328fd6733a1df366e4ff253cc9fbb8c3d6d1bad",
  "responseFingerprint": "45a86bd8554bed131a3dcb56b4a6610f380ab9226301e33fc49f46d32f672e794aa967bc2ab16c40b637bf3c544e6e199ca00220990b63ddb7dc180f613ede53",
  "startedAt": "2025-06-01T23:59:05.989351215Z",
  "svgs": [
    "<figure class='box-figure' data-box-index=0><svg viewBox='-90.40485194281396,-67.35586535436917,256.32620818012344,239.84587064751952'>[<line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='24.5' y2='14.293792738403425'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='15.661165235168156' y2='29.603103630798287'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='33.338834764831844' y2='29.603103630798287'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='165.92135623730948' y2='106.1496580927726'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='-90.40485194281396' y2='90.84034720037774'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='24.5' x2='24.5' y2='-67.35586535436917'/>\n] <polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='1' data-side='[8 12 16] [1 0 0]' data-direction='0 [8 12 16] [1 0 0] [] [] [1,0,0]' data-max-depth='11.758330250063729' data-min-depth='3.6754264814089668' class='volume-line' points='59.85533905932737,85.73724356957945 165.92135623730948,24.5 24.5,-57.1496580927726 -81.56601717798212,4.087585476806854' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='1' data-side='[8 12 16] [0 1 0]' data-direction='1 [8 12 16] [0 1 0] [] [] [0,1,0]' data-max-depth='11.758330250063729' data-min-depth='4.830127019788218' class='volume-line' points='59.85533905932737,167.38690166235205 59.85533905932737,85.73724356957945 -81.56601717798212,4.087585476806854 -81.56601717798212,85.73724356957945' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='1' data-side='[8 12 16] [0 0 1]' data-direction='2 [8 12 16] [0 0 1] [] [] [0,0,1]' data-max-depth='11.758330250063729' data-min-depth='5.98482755816747' class='volume-line' points='165.92135623730948,106.1496580927726 165.92135623730948,24.5 59.85533905932737,85.73724356957945 59.85533905932737,167.38690166235205' style='fill:mediumseagreen;' />\n [<line data-volume-index='0' class='volume-line' x1='165.92135623730948' y1='106.1496580927726' x2='51.016504294495526' y2='172.49000529315035'/>\n <line data-volume-index='0' class='volume-line' x1='165.92135623730948' y1='106.1496580927726' x2='165.92135623730948' y2='14.293792738403422'/>\n <line data-volume-index='0' class='volume-line' x1='51.016504294495526' y1='172.49000529315035' x2='-90.40485194281396' y2='90.84034720037774'/>\n <line data-volume-index='0' class='volume-line' x1='51.016504294495526' y1='172.49000529315035' x2='51.016504294495526' y2='80.63413993878116'/>\n <line data-volume-index='0' class='volume-line' x1='-90.40485194281396' y1='90.84034720037774' x2='-90.40485194281396' y2='-1.0155181539914349'/>\n <line data-volume-index='0' class='volume-line' x1='-90.40485194281396' y1='-1.0155181539914349' x2='24.5' y2='-67.35586535436917'/>\n <line data-volume-index='0' class='volume-line' x1='-90.40485194281396' y1='-1.0155181539914349' x2='51.016504294495526' y2='80.63413993878116'/>\n <line data-volume-index='0' class='volume-line' x1='24.5' y1='-67.35586535436917' x2='165.92135623730948' y2='14.293792738403422'/>\n <line data-volume-index='0' class='volume-line' x1='165.92135623730948' y1='14.293792738403422' x2='51.016504294495526' y2='80.63413993878116'/>\n]</svg><figcaption></figcaption></figure>",
    "<figure class='box-figure' data-box-index=1><svg viewBox='-90.40485194281396,-67.35586535436917,256.32620818012344,239.84587064751952'>[<line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='24.5' y2='14.293792738403425'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='15.661165235168156' y2='29.603103630798287'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='33.338834764831844' y2='29.603103630798287'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='165.92135623730948' y2='106.1496580927726'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='-90.40485194281396' y2='90.84034720037774'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='24.5' x2='24.5' y2='-67.35586535436917'/>\n] <polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='3' data-side='[6 3 3] [1 0 0]' data-direction='0 [6 3 3] [1 0 0] [] [] [1,0,0]' data-max-depth='4.830127019788218' data-min-depth='3.0980762122193415' class='volume-line' points='24.5,-6.118621784789724 51.01650429449553,-21.427932677184586 24.5,-36.73724356957945 -2.0165042944955296,-21.427932677184586' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='3' data-side='[6 3 3] [0 1 0]' data-direction='1 [6 3 3] [0 1 0] [] [] [0,1,0]' data-max-depth='4.830127019788218' data-min-depth='2.2320508084349027' class='volume-line' points='24.5,55.118621784789724 24.5,-6.118621784789724 -2.0165042944955296,-21.427932677184586 -2.0165042944955296,39.80931089239486' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='3' data-side='[6 3 3] [0 0 1]' data-direction='2 [6 3 3] [0 0 1] [] [] [0,0,1]' data-max-depth='4.830127019788218' data-min-depth='2.2320508084349027' class='volume-line' points='51.01650429449553,39.80931089239486 51.01650429449553,-21.427932677184586 24.5,-6.118621784789724 24.5,55.118621784789724' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='4' data-side='[6 3 6] [1 0 0]' data-direction='3 [6 3 6] [1 0 0] [] [] [1,0,0]' data-max-depth='5.696152423572657' data-min-depth='3.96410161600378' class='volume-line' points='51.01650429449553,9.190689107605138 77.53300858899107,-6.118621784789724 51.01650429449553,-21.427932677184586 24.5,-6.118621784789724' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='4' data-side='[6 3 6] [0 1 0]' data-direction='4 [6 3 6] [0 1 0] [] [] [0,1,0]' data-max-depth='5.696152423572657' data-min-depth='3.0980762122193415' class='volume-line' points='51.01650429449553,70.42793267718457 51.01650429449553,9.190689107605138 24.5,-6.118621784789724 24.5,55.118621784789724' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='4' data-side='[6 3 6] [0 0 1]' data-direction='5 [6 3 6] [0 0 1] [] [] [0,0,1]' data-max-depth='5.696152423572657' data-min-depth='3.0980762122193415' class='volume-line' points='77.53300858899107,55.118621784789724 77.53300858899107,-6.118621784789724 51.01650429449553,9.190689107605138 51.01650429449553,70.42793267718457' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='5' data-side='[6 3 9] [1 0 0]' data-direction='6 [6 3 9] [1 0 0] [] [] [1,0,0]' data-max-depth='6.562177827357096' data-min-depth='4.830127019788218' class='volume-line' points='77.53300858899107,24.5 104.0495128834866,9.190689107605138 77.53300858899107,-6.118621784789724 51.01650429449553,9.190689107605138' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='5' data-side='[6 3 9] [0 1 0]' data-direction='7 [6 3 9] [0 1 0] [] [] [0,1,0]' data-max-depth='6.562177827357096' data-min-depth='3.96410161600378' class='volume-line' points='77.53300858899107,85.73724356957945 77.53300858899107,24.5 51.01650429449553,9.190689107605138 51.01650429449553,70.42793267718457' style='fill:mediumseagreen;' />\n<polygon vector-effect='non-scaling-stroke' data-item-ref-id='5854' data-volume-index='5' data-side='[6 3 9] [0 0 1]' data-direction='8 [6 3 9] [0 0 1] [] [] [0,0,1]' data-max-depth='6.562177827357096' data-min-depth='3.96410161600378' class='volume-line' points='104.0495128834866,70.42793267718457 104.0495128834866,9.190689107605138 77.53300858899107,24.5 77.53300858899107,85.73724356957945' style='fill:mediumseagreen;' />\n [<line data-volume-index='2' class='volume-line' x1='165.92135623730948' y1='106.1496580927726' x2='51.016504294495526' y2='172.49000529315035'/>\n <line data-volume-index='2' class='volume-line' x1='165.92135623730948' y1='106.1496580927726' x2='165.92135623730948' y2='14.293792738403422'/>\n <line data-volume-index='2' class='volume-line' x1='51.016504294495526' y1='172.49000529315035' x2='-90.40485194281396' y2='90.84034720037774'/>\n <line data-volume-index='2' class='volume-line' x1='51.016504294495526' y1='172.49000529315035' x2='51.016504294495526' y2='80.63413993878116'/>\n <line data-volume-index='2' class='volume-line' x1='-90.40485194281396' y1='90.84034720037774' x2='-90.40485194281396' y2='-1.0155181539914349'/>\n <line data-volume-index='2' class='volume-line' x1='-90.40485194281396' y1='-1.0155181539914349' x2='24.5' y2='-67.35586535436917'/>\n <line data-volume-index='2' class='volume-line' x1='-90.40485194281396' y1='-1.0155181539914349' x2='51.016504294495526' y2='80.63413993878116'/>\n <line data-volume-index='2' class='volume-line' x1='24.5' y1='-67.35586535436917' x2='165.92135623730948' y2='14.293792738403422'/>\n <line data-volume-index='2' class='volume-line' x1='165.92135623730948' y1='14.293792738403422' x2='51.016504294495526' y2='80.63413993878116'/>\n]</svg><figcaption></figcaption></figure>"
  ],
  "title": "Default",
  "totalCost": 3744,
  "totalTime": 0.004518283,
  "totalVolume": 3744,
  "totalVolumeNet": 1698,
  "totalVolumeUsed": 1698,
  "totalVolumeUtilization": 0.45352564,
  "totalWeight": 4.99,
  "usedKeyStem": "3zY4ijmj91",
  "version": "1.7.3"
}

How it works

When an API request is sent with dimensionSets , the API breaks the quantity up across dimensions. In the example above, we have a “bottle” defined as a single instance of the item (quantityDivisor:1) as one set, while the second is a “case” defined as a quantity of 12 (quantityDivisor:12). With an total item quantity of 15, the API returns one “case” unit and 3 “bottle” units. The API response includes the assigned dimensionSet as part of the items response in each box, and each item’s packed dimensions match the assigned dimensionSet.

Handling are units are selected in a reverse (bottom-up) hierarchy, with those at bottom of the list used first to break up the items.

The response includes a lenUnits value along with lenItems — in the example its 4 units (1 case, 3 bottles) which equates to 15 items.

Conclusion

While dimensionSets are certainly not required to cartonize, they do solve a frequent use case of needing one order line item having multiple potential handling units for associates to pick. Ensuring that the recommended box is in line with the desired number of handling units is extremely important to matching operational efficiencies on the warehouse floor.