Private
apiPrivate
apiFinds the optimal way to pack a shipment.
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.
Paccurate API key.