Packing configuration.
Optional allowableThe amount an item can overhang lower items that it is placed upon. The units are whatever units the box and item dimensions are given in. By convention, inches.
-1
Optional boxThe objective to evaluate boxTypeChoices by. 'lowest-cost' minimizes price or volume cost of boxTypes selected, 'most-items' maximizes item count per box opened, i.e., fewest total boxes used.
lowest-cost
@enum {string}
Optional boxWhen selecting the next available boxType, we must consider how far to look ahead.
Consider we have 8 items of identical dimensions, and two flat rate boxTypes. It is found that Box A can fit 6 items, and costs $12. Box B can fit 4 items, and costs $10.
If we consider only the next box, i.e., 'boxTypeChoiceLookahead' set to 0, we would select Box A. It costs $2 per item, whereas Box B is $2.50 per item. Box A is opened, 6 items are placed inside, and now 2 remain. To pack the last 2, Box B would be selected, as 2 items for $10 is $5 per item, and Box A's $12 is $6 per item.
Alternatively, if 'boxTypeChoiceLookahead' is set to 1, the boxType that provides the lowest cost per item including the lookahead boxType(s) would be selected. In this case, we find we need 2 of Box B, for $20 total, to fit all 8 items, or $2.50 per item, and would need 1 of Box A and 1 of Box B if Box A is selected first, for $22 total or $2.75 per item. Box B would be used.
Please note that 'boxTypeChoiceLookahead', especially when combined with the 'actual' 'boxTypeChoiceStyle' can have significant performance impacts. 0 is recommended for real-time use cases.
0
Optional boxControl the ability for partially-filled boxes to allow packing of later-sorted items. A value of null or -1 means unlimited lookback is permitted, i.e., every box can be used to pack any allowable item that fits regardless of its pack sequence, and all boxes will remain "opened" or available for packing until the last item in the pack sequence is attempted. A value of 0 means lookback is not allowed, and as soon as the next item in the pack sequence does not fit into a partially filled box, that box is "closed" or locked and will not permit any additional items (i.e., out-of-sequence items) to be packed in it.
-1
Optional boxDefines how available boxTypes are selected when a new box must be created to pack additional items. The 'estimated' style uses 'usableSpace' to estimate how quickly each valid boxType will be filled by both weight and volume, and estimated cost is calculated. 'actual' attempts real placement of subsequent items in each available boxType and selects the one with the lowest actual cost. 'actual' is much slower than 'estimated', but will often return superior cost optimizations.
actual
@enum {string}
Optional boxdefault attributes for all "boxTypes", to be overridden by any individual "boxType" attributes specified.
{
* "weightMax": 50,
* "rateTable": {
* "dimFactor": 166
* }
* }
Optional centerthe coordinates of the center of mass of the box.
Optional x?: numberx coordinate, used as height.
0
Optional y?: numbery coordinate, used as width.
0
Optional z?: numberz coordinate, used as length.
0
the [height,length,width] of the box.
Optional x?: numberx coordinate, used as height.
0
Optional y?: numbery coordinate, used as width.
0
Optional z?: numberz coordinate, used as length.
0
Optional itemThe maximum quantity of unique 'item.refId' values that a single box can contain. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, overriding top-level 'itemSetsPerBoxMax' settings.
0
Optional itemsLimit the item count that can share a placement on a specific line parallel to the placement axis, e.g., '[1,2,1]' means items can be placed 1 high, 2 wide, and 1 deep within the box. A value of '0' is equivalent to no limit along that axis.
[
1,
2,
1
]
Optional itemsThe maximum quantity of discrete items that a single box can contain. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, overriding top-level 'itemsPerBoxMax'.
0
Optional name?: stringname for the type of box.
Optional price?: numberFixed price of the container, in whole units of currency, default USD cents. This can represent the cost of a flat rate carton, the cost of the actual carton materials, or it can include any other flat fees that may need to be added on a per-carton basis, such as handling, accessorial surchages, oversize fees, etc. This value is added to any rate table rates defined for the carton.
Optional rateAn optional rate table definition for improved carton selection and pricing optimization. Defaults are included using retail rates for FedEx and UPS if carrier and service is provided, but optimization can be improved with more data passed in a carton's specific rate table. Methods are
Optional baseThe basePrice can be found by estimating the lowest weight-based rate available for a given service, in the example above, solving for basePrice for a $10, 1lb package with the already-solved priceIncreaseRate yields
$10 = $5/lb * 1lb + basePrice
$10 = $5 + basePrice
basePrice = $5
Optional carrier?: stringcarrier name for rate table to use
Optional dimThis is the Dimensional Weight divisor. It is given in units of volume per unit weight, e.g., the standard of "139" represents 139 cubic inches per pound, and is used to convert the total volume of a carton into a functional minimum weight to be used when rating the carton. E.g., a carton with dimensions 10" x 10" x 13.9" would yield a volume of 1390 cubic inches. This yields
cartonEffectiveMinimumWeight = 1390in³ / 139in³/lb. To disable when using a preset carrier and zone, set to -1 or a very big number.
cartonEffectiveMinimumWeight = 10lbs
Optional priceInstead of providing the full rate table, you can list a carton "basePrice" and a carton "priceIncreaseRate". These two values will be used in a simple linear model to guess carton price, i.e.,
cartonPrice = priceIncreaseRate * cartonWeight + basePriceOftentimes, this will be enough to get accurate carton selections without needing to send complete customer-based rates. It's worth considering, as the prices are only estimates to be used in carton selection, with final rating of cartons happening outside of paccurate. This is the predicted rate of increase for a weight-based pricing model. The simplest way to find a serviceable value is to take
priceIncreaseRate = (maximumPrice - minimumPrice)/(maximumWeight - minimumWeight)In the example above, this would yield
priceIncreaseRate = ($20-$10)/(3lbs-1lb)
priceIncreaseRate = $10/2lbs
priceIncreaseRate = $5/lb
Optional rates?: number[]list of prices to use for the weight that corresponds to its index, e.g., [10, 15, 20] would be $10 for 1lb, $15 for 2lbs, $20 for 3lbs.
Optional service?: stringservice name for rate table to use
Optional weights?: number[]list of weights to use for the rate that corresponds to its index, e.g., [1, 2, 3] would mean 1lb for the minimum rate ($10), 2lbs for the second rate ($15), and 3lbs for the highest rate ($20). Note that if the highest value from this list is less than the weightMax of the carton, all carton weights exceeding the maximum from this list up to the carton weightMax will not pro-rate but will be estimated at the maximum value in the rate table.
Optional zone?: stringzone of rate table to use
Optional refbox type reference identifier passed backed from request.
Optional reservedspace in boxes that is reserved, i.e., for packing material, overriding top-level 'reservedSpace'.
0
0.2
maximum allowable gross weight for the box, i.e., all packed item weights plus the weightTare.
Optional weightweight of the container when empty or otherwise unladen, i.e., of the box itself.
0
Optional boxlist of dynamic boxTypeGenerators to use, in combination with boxTypes
Optional boxpredefined box types to be used, separated by commas. Will be overridden by boxTypes. Acceptable values are
[]
Optional boxbox type definitions for packing, will override boxTypeSets defined.
Optional boxes?: ({ pre-packed boxes, including any items specified that will be packed and excess space used before any new boxes are created.
[]
Optional boxesThe maximum number of boxes to be used to pack the items in the request, potentially leaving items in 'leftovers' if there is insufficient space, determined by item 'sequence' or selected 'itemSort'. If existing 'boxes' are passed to the pack request, they count towards this total, but will not be excluded, allowing for situations where 'lenBoxes' may be greater than 'boxesMax'. However, no 'boxTypes' will be used to create additional boxes unless doing so would not exceed 'boxesMax'.
0
Optional boxesThe maximum number of boxes that a single ItemSet's member items (i.e., all that share the same refId) can be spread across. Any items that do not fit within this number of boxes will be precluded from packing and returned in the leftovers array. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit.
0
Optional boxesThe maximum number of boxes that a single non-empty sequence's member items (i.e., all that share the same non-empty sequence) can be spread across. Any items that do not fit within this number of boxes will be precluded from packing and returned in the leftovers array. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit.
0
Optional cohortthe maximum number of contiguous cohorts for a given item type within a single container. E.g., if you pack 40 chairs in a single container, a cohortMax of 2 could yield one (all 40 chairs in a single block if space is availabe) or two (say, 25 chairs in one corner and 15 in the other) contiguous cohorts.
2
Optional cohortif selected, will ensure that all like items will be packed together, in no more than [cohortMax] different groups within a single container.
false
Optional coordIf placementStyle is set to "default", coordOrder sets the placement priority of axes ascendingly. "0,1,2" would search for placement points along the Z(length,"2"), then Y(width,"1"), and finally X(height"0"). Keep in mind that in the default rendering the "up" direction is X and the other axes follow the right-hand rule. This is useful for different packing methods. E.g., Utilizing "2,0,1" would pack a shipping container first in the Y(width) direction, then in the X(height) direction, and finally in the Z(length) direction, replication a floor-to-ceiling, front-to-back loading method.
[
0,
1,
2
]
Optional corners?: booleanonly pack items at valid corner points of other items (optimal)
true
Optional eye?: { The x,y,z coordinates of the virtual eye looking at the package for visualization purposes. Default is isometric, "1,1,1". To generate a side view, one could use "0.001,1.0,0.001".
{
* "x": 1,
* "y": 1,
* "z": 1
* }
Optional x?: numberx coordinate, used as height.
0
Optional y?: numbery coordinate, used as width.
0
Optional z?: numberz coordinate, used as length.
0
Optional generatedThe maximum number of generated box sizes to randomly sampled when generating box types. Default of 0 is unlimited, and in some cases may never return without a limit.
0
Optional imagecase-insensitive format to render images in, either 'SVG' or 'PNG', if includeImages is enabled.
svg
@enum {string}
Optional imgwidth of rendered SVGs in pixels.
400
Optional includeinclude inline images, default is always on
true
true
Optional includeinclude inline javascripts and styles for base template
false
false
Optional interlock?: booleanalternates layFlat orientation by layer, so as to create an interlocked placement pattern and improve item stability.
false
Optional itemFor all items where orientation flipping is used, the orientation producing the highest multiple of items fit per remaining dimension is used as the first orientation. This option should be enabled when packing high quantities of single item types, but may produce inconsistent results in other cases. Defers to item orientation locking and itemOrientationSearchDepth > 0 if a superior result is found.
false
Optional itemWhether to attempt packing by either greedily placing items or placing all allowable combinations of initial item orientations and selecting the most performant. When true, items will be placed immediately using the orientation reflected by their dimensions definition and will only be flipped if a placement cannot be found and the item rules allow orientation changes. When false, all allowable initial orientation combinations will be attempted for each item in each box.
true
Optional itemWhen itemInitialOrientationPreferred is set to false, the itemOrientationSearchDepth is the number of unique, sorted, groups of Items sharing the same ItemSet definition that will be have every combination of initial orientation attempted. A value of 1 signifies that only the first item (and others still unpacked from its ItemSet) will have every orientation attempted and the engine subsequently selecting the most performant. A value of 2 signifies that the first groups of unpacked items, each sharing an ItemSet, will have every combination of orientation attempted. Increasing this value from 1 can very rapidly result in excessive complexity and a timeout error instead of a result, so discretion is advised.
1
Optional itemitem set definitions if not creating random items.
[
{
"refId": 0,
"color": "tomato",
"dimensions": {
"x": 4.2,
"y": 7,
"z": 8
},
"weight": 4.5,
"quantity": 10
},
{
"refId": 1,
"color": "cornflowerblue",
"dimensions": {
"x": 3,
"y": 3,
"z": 5
},
"weight": 2,
"quantity": 13
}
]
Optional itemThe maximum quantity of unique 'item.refId' values that a single box can contain. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, optionally overridden by 'boxType' settings.
0
Optional itemMethod to use to sort items for placement. Default is item volume descending. 'largest-box-needed' is by the volume of the smallest box type specified that will fit the item, descending, 'largest-girth' is 2*(width + height), descending, 'longest-dimension' is by longest single item dimension, descending, 'shortest-dimension' is by shortest single dimension, ascending, 'largest-cross-section' is by largest product of the two greatest dimensions, descending, 'set-volume' is by total 'itemSet' volume, descending. 'weight' is by weight, descending. 'density' is by item weight per unit volume, descending. It can often be worth attempting packs with competing itemSorts and picking the lowest cost option. 'all' uses all available item sorts, whereas 'combined' uses a recommended set of item sorts, both returning the lowest 'totalCost' option.
combined
@enum {string}
Optional itemWhether or not to use both normal and reversed itemSorts.
false
Optional itemWhether or not to reverse the itemSort utilized.
false
Optional itemsLimit the item count that can share a placement on a specific line parallel to the placement axis, e.g., '[1,2,1]' means items can be placed 1 high, 2 wide, and 1 deep within the box. A value of '0' is equivalent to no limit along that axis. Overridden by 'boxType' settings.
[
1,
2,
1
]
Optional itemsThe maximum quantity of discrete items that a single box can contain. The default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, optionally overridden by 'boxType' settings.
0
Optional key?: stringissued API key.
Optional layaligns all items laying flat. If possible, it may create a "brick-laying" pattern to increase stability.
false
Optional maxThis is the maximum distance allowable between two sequence values of items packed in a common box. E.g., "Distance" for an item sequence composed of aisle/bin combinations of "0401" and "1228" has a sequence distance of |1228 - 401| = 827
Optional n?: numbernumber of random items to generate and the quantity of each if "random" is set to true. a value of 5 would create 5 different items with a quantity of 5 each, making the total item quantity equal to n²
5
Optional ordera client-provided string identifier for the order this pack corresponds to.
Optional packthe x,y,z coordinates of an optional packing origin. A packing origin is used to create more balanced packing for situations where load needs to be considered. E.g., for a 40"x48" pallet, a packOrigin representing the middle of the pallet, "0,20,24", would cause placement to minimize the distance of the packed items from the center of the pallet.
{
* "x": 0,
* "y": 0,
* "z": 0
* }
Optional x?: numberx coordinate, used as height.
0
Optional y?: numbery coordinate, used as width.
0
Optional z?: numberz coordinate, used as length.
0
Optional placementHow to place items. 'default' will defer to coordOrder, 'corner' minimizes distance to rear, bottom corner, 'wedge' minimizes distance to middle of bottom, back edge, 'mound' minimizes distance to center of carton bottom.
default
@enum {string}
Optional random?: booleancreate random items
false
Optional randommaximum item dimension along a single axis for randomly generated items.
10
Optional randommaximum quantity for randomly generated items.
Optional randommaximum item weight for randomly generated items.
10
Optional requesta client-provided string identifier for the pack request being made.
Optional reservedspace in boxes that is reserved, i.e., for packing material.
0
0.2
Optional rules?: { Array of packing rules.
[]
Optional seed?: booleanif random is selected, seed the random number generator to deterministically generate random items to pack.
true
false
Optional seedif seed is set to true, specifies a non-default seed for the random number generator.
1
Optional sequenceColorize items solely by their sequence value, light when sequence is high, dark when it is low. Useful for indicating item bin location, weight, or other sequence property that may not be apparent from the default visualization.
false
Optional sequenceWhether or not the items should be initially sorted by their sequence value instead of by the specified itemSort. This is not always useful, as the default "biggest-first" volume sort is very effective for items, and constraining by maxSequenceDistance is applied regardless of this field. That said, for doing custom pre-sorts such as weight-based instead of volume based, this value should be set to true.
false
Optional template?: "demo.tmpl" | "shipapp.tmpl" | "boat.tmpl"template name for markup generation.
@enum {string}
Optional timeout?: numberOptional timeout for request computation, will be reduced to endpoint maximum if in excess of published timeout.
30
Optional usablean estimate of typical box utilization for the quick "estimated" boxTypeChoiceStyle, which will be used to ensure "estimated" box type choices are not overly optimistic regarding potential volume utilization.
0.85
0.85
Optional valueThe tiebreaker to use in the event to box type choices are otherwise completely equal. Default is "volume", alternative is "weight".
volume
@enum {string}
Optional zone?: number[deprecated] the shipping zone in order to use basic zone-based price optimization.
null
Paccurate API endpoint.
Finds the optimal way to pack a shipment.