{ "openapi": "3.0.1", "info": { "title": "paccurate.io", "version": "1.9.2" }, "servers": [ { "url": "/" } ], "paths": { "/": { "post": { "description": "a pure-JSON endpoint for packing requests\n", "requestBody": { "description": "complete set of items, boxes, and parameters to pack", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pack" } } }, "required": false }, "responses": { "200": { "description": "Successful pack", "content": { "application/json": { "schema": { "title": "PackResponse", "type": "object", "properties": { "boxes": { "type": "array", "description": "List of boxes, packed, with their contained items", "items": { "type": "object", "properties": { "box": { "$ref": "#/components/schemas/Box" } } } }, "title": { "type": "string", "description": "title of packing result, when applicable" }, "built": { "type": "string", "description": "build timestamp of engine" }, "startedAt": { "type": "string", "description": "start timestamp of pack" }, "version": { "type": "string", "description": "version of engine" }, "lenBoxes": { "type": "integer", "description": "cardinality of all packed boxes" }, "lenItems": { "type": "integer", "description": "total sum of quantities of all items" }, "lenUnits": { "type": "integer", "description": "cardinality of distinct units of items (count of cases, eaches, etc.)" }, "lenLeftovers": { "type": "integer", "description": "cardinality of items unable to be packed" }, "totalCost": { "type": "integer", "description": "total estimated cost of all packed boxes, when applicable, in cents" }, "totalVolume": { "type": "number", "description": "total volume of all boxes returned" }, "totalVolumeNet": { "type": "number", "description": "total net (item) volume of all packed (non-leftover) items" }, "totalVolumeUsed": { "type": "number", "description": "total net volume plus reserved volume from `reservedSpace`" }, "totalVolumeUtilization": { "type": "number", "description": "totalVolumeUsed divided by totalVolume" }, "totalWeight": { "type": "number", "description": "total gross weight of all packed boxes, including box tare weights and item weights" }, "packTime": { "type": "number", "description": "seconds spent in packing" }, "renderTime": { "type": "number", "description": "seconds spent in rendering and placement instruction creation of packing solution" }, "totalTime": { "type": "number", "description": "seconds spent generating response, total" }, "leftovers": { "type": "array", "description": "items left over that could not be packed into any available boxes", "items": { "$ref": "#/components/schemas/Item" } }, "itemSortUsed": { "type": "string", "description": "name of item sort algorithm used" }, "itemSortReverseUsed": { "type": "boolean", "description": "whether the item sort was reversed" }, "boxTypeChoiceGoalUsed": { "type": "string", "description": "name of box type choice goal used" }, "scripts": { "type": "string", "description": "additional javascripts for any image loading" }, "styles": { "type": "string", "description": "additional styles for pack images" }, "svgs": { "type": "array", "description": "all box SVG images", "items": { "type": "string" } }, "orderId": { "type": "string", "description": "a client-provided string identifier for the order this pack corresponds to" }, "requestId": { "type": "string", "description": "a client-provided string identifier for the pack request being made" }, "imageScale": { "type": "object", "description": "if `includeImages` is enabled, the returned `imageScale` is the minimum scale (defined in the original 3D space) used to determine the relative size of all images. If empty, it is the same as the default, [0,0,0], equivalent to `imageScaleStyle` set to `fill`. If the `imageScale` is _larger_ than each returned box image, the box images are each scaled identically. NB: `imageScale` is omitted from the response if zero [0,0,0]", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "imageScaleStyleUsed": { "type": "string", "description": "if `includeImages` is enabled, `imageScaleStyleUsed` returns the image scaling method used to generate the images.\n\n`override` means a non-zero `imageScale` was passed in directly to the request and any `imageScaleStyle` was overridden.", "default": "fill", "enum": [ "fill", "largest-box", "largest-box-type", "override" ] }, "images": { "type": "array", "description": "if PNG imageFormat selected, list of PNG image objects", "items": { "$ref": "#/components/schemas/Image" } }, "usedKeyStem": { "type": "string", "description": "stem (10-character prefix) of authorization key used, if any" }, "warnings": { "type": "array", "description": "any warning messages about non-critical issues arising during the pack", "items": { "type": "string" } }, "requestFingerprint": { "type": "string", "description": "a fingerprint corresponding to the request content for identification within Paccurate PCS" }, "responseFingerprint": { "type": "string", "description": "a fingerprint corresponding to the response content for identification within Paccurate PCS" }, "packUuid": { "type": "string", "description": "a unique identifier for this pack transaction, which can be used to directly retrieve the pack via Paccurate PCS" }, "properties": { "type": "object", "additionalProperties": true, "description": "Additional properties of the pack request which are all returned in the response" } } } } } }, "400": { "description": "Bad request. Malformed or some other problem occurred processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input. The request was well-formed, but the parameters were contradictory, invalid, or otherwise somehow unable to be processed. More information will be contained in the error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Without an API key, only 10 unique requests are allowed per day for testing or demonstration purposes. Note that a randomized pack repeated is only a single unique request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codegen-request-body-name": "pack" } } }, "components": { "schemas": { "Error": { "required": [ "code", "message" ], "type": "object", "properties": { "message": { "type": "string" }, "details": { "type": "string" }, "code": { "maximum": 600, "minimum": 100, "type": "integer" } } }, "Pack": { "type": "object", "properties": { "requestId": { "type": "string", "description": "a client-provided string identifier for the pack request being made\n\nThis is searchable in Paccurate PCS." }, "orderId": { "type": "string", "description": "a client-provided string identifier for the order this pack corresponds to\n\nThis is searchable in Paccurate PCS." }, "layFlat": { "type": "boolean", "description": "align all items laying flat\n\nIf possible, it may create a \"brick-laying\" pattern to increase stability.", "default": false }, "interlock": { "type": "boolean", "description": "If true, alternate layFlat orientation by layer, so as to create an interlocked placement pattern and improve item stability.", "default": false }, "corners": { "type": "boolean", "description": "only pack items at valid corner points of other items (optimal)", "default": true }, "itemSets": { "type": "array", "description": "item set definitions if not creating random items", "example": [ { "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 } ], "items": { "$ref": "#/components/schemas/ItemSet" } }, "boxTypes": { "type": "array", "description": "box type definitions for packing, will override `boxTypeSets` defined", "items": { "$ref": "#/components/schemas/BoxType" } }, "boxTypeGenerators": { "type": "array", "description": "list of dynamic `boxTypeGenerators` to use, in combination with boxTypes", "items": { "$ref": "#/components/schemas/BoxTypeGenerator" } }, "boxTypeDefaults": { "type": "object", "description": "default attributes for all `boxTypes`, to be overridden by any individual `boxType` attributes specified", "example": { "weightMax": 50, "rateTable": { "dimFactor": 166 } }, "allOf": [ { "$ref": "#/components/schemas/BoxProperties" } ] }, "boxes": { "type": "array", "description": "pre-packed boxes, including any items specified that will be packed and excess space used before any new boxes are created", "example": [], "items": { "$ref": "#/components/schemas/Box" } }, "usableSpace": { "maximum": 1, "minimum": 0, "type": "number", "description": "an 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", "example": 0.85 }, "reservedSpace": { "maximum": 1, "minimum": 0, "type": "number", "description": "space in boxes that is reserved, i.e., for packing material", "example": 0.2 }, "boxTypeSets": { "type": "array", "description": "predefined box types to be used, separated by commas", "example": [], "items": { "$ref": "#/components/schemas/BoxTypeSet" } }, "eye": { "type": "object", "description": "the x,y,z coordinates of the virtual eye looking at the package for visualization purposes\n\nDefault is isometric, \"1,1,1\". To generate a side view, one could use \"0.001,1.0,0.001\".", "example": { "x": 1, "y": 1, "z": 1 }, "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "packOrigin": { "type": "object", "description": "the x,y,z coordinates of an optional packing origin\n\nA 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.", "example": { "x": 0, "y": 0, "z": 0 }, "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "rules": { "type": "array", "description": "array of packing rules", "example": [], "items": { "$ref": "#/components/schemas/Rule" } }, "random": { "type": "boolean", "description": "create random items", "default": false }, "n": { "type": "integer", "description": "number of random items to generate and the quantity of each if `random` is set to true\n\nA value of 5 would create 5 different items with a quantity of 5 each, making the total item quantity equal to n²" }, "randomMaxDimension": { "type": "integer", "description": "maximum item dimension along a single axis for randomly generated items" }, "randomMaxWeight": { "type": "integer", "description": "maximum item weight for randomly generated items" }, "randomMaxQuantity": { "type": "integer", "description": "maximum quantity for randomly generated items" }, "seed": { "type": "boolean", "description": "If random is selected, seed the random number generator to deterministically generate random items to pack.", "example": false, "default": true }, "seedValue": { "type": "integer", "description": "If seed is set to true, it specifies a non-default seed for the random number generator." }, "seedFromOrderId": { "type": "boolean", "description": "If seed is set to true and a non-blank `orderId` is passed, the `orderId` checksum will be used as a deterministic random seed." }, "imgSize": { "type": "integer", "description": "width of rendered SVGs in pixels" }, "template": { "type": "string", "description": "template name for markup generation\n\nIf `classic`, returns style inline for generated SVGs (including box border markings).", "example": "", "enum": [ "demo.tmpl", "shipapp.tmpl", "boat.tmpl", "classic" ] }, "includeScripts": { "type": "boolean", "description": "include inline javascripts and styles for base template", "example": false, "default": false }, "includeImages": { "type": "boolean", "description": "include inline images, default is always on", "example": true, "default": true }, "imageFormat": { "type": "string", "description": "case-insensitive format to render images in, either `svg` or `png`, if `includeImages` is enabled", "default": "svg", "enum": [ "svg", "png" ] }, "imageScale": { "type": "object", "description": "If `includeImages` is enabled, `imageScale` forces the minimum scale for image (will expand if needed). Overrides `imageScaleStyle` when any non-zero values are included.", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "imageScaleStyle": { "type": "string", "description": "a methodology to automatically scale images consistently (optional)\n\n- Empty or not set is the same as `fill`, which will scale each image to fill the `imgSize` view automatically.\n- `largest-box` will scale all box images to the largest `box` actually used in the pack.\n- `largest-box-type` will scale all box images to the largest `BoxType` available in the pack (including those generated by a `BoxTypeGenerator`.)\n\n`largest-box` is useful if boxes will be visually compared within a single pack, and `largest-box-type` is more usable if pack images are going to be visually compared across boxes and packs. Any non-zero values in `imageScale` will take precedence and disable the `imageScaleStyle`.", "default": "fill", "enum": [ "fill", "largest-box", "largest-box-type" ] }, "coordOrder": { "type": "array", "description": "If `placementStyle` is set to `default`, then `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.\n\nThis 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.", "example": [ 0, 1, 2 ], "items": { "type": "integer" } }, "cohortPacking": { "type": "boolean", "description": "If selected, ensure that all like items will be packed together, in no more than `cohortMax` different groups within a single container. Not to be confused with `boxTypeChoiceLookback` constraints for reducing item spreading across containers and improving consolidation based on `sequence`.", "default": false }, "cohortMax": { "type": "integer", "description": "maximum number of contiguous cohorts for a given item type within a single container\n\nFor example, 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 available) or two (say, 25 chairs in one corner and 15 in the other) contiguous cohorts." }, "allowableOverhang": { "type": "number", "description": "amount an item can overhang lower items that it is placed upon\n\nThe units are whatever units the box and item dimensions are given in. By convention, inches." }, "placementStyle": { "type": "string", "description": "how to place items\n\n- `default` will defer to coordOrder.\n- `corner` minimizes distance to rear, bottom corner.\n- `wedge` minimizes distance to middle of bottom, back edge.\n- `mound` minimizes distance to center of carton bottom.", "default": "default", "enum": [ "default", "corner", "wedge", "mound", "orb" ] }, "itemSort": { "type": "string", "description": "method to use to sort items for placement\n\n- `default` is item volume, descending.\n- `largest-box-needed` is by the volume of the smallest box type specified that will fit the item, descending.\n- `largest-girth` is 2*(width + height), descending.\n- `longest-dimension` is by longest single item dimension, descending.\n- `shortest-dimension` is by shortest single dimension, ascending.\n- `largest-cross-section` is by largest product of the two greatest dimensions, descending.\n- `set-volume` is by total `itemSet` volume, descending. `weight` is by weight, descending.\n- `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.\n- `all` uses all available item sorts, whereas `combined` uses a recommended set of item sorts, both returning the lowest `totalCost` option.", "default": "combined", "enum": [ "default", "largest-box-needed", "largest-girth", "largest-length-plus-girth", "longest-dimension", "shortest-dimension", "largest-cross-section", "set-volume", "density", "weight", "combined", "all" ] }, "itemSortReverse": { "type": "boolean", "description": "If true, reverse the itemSort utilized.", "default": false }, "itemSortDualDirection": { "type": "boolean", "description": "If true, use both normal and reversed itemSorts.", "default": false }, "itemInitialOrientationBestForBox": { "type": "boolean", "description": "For 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.", "default": false }, "itemInitialOrientationPreferred": { "type": "boolean", "description": "If true, 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.", "default": true }, "itemOrientationSearchDepth": { "maximum": 4, "minimum": 0, "type": "integer", "description": "When `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. Requesting a depth in excess of the maximum will return a warning and allow the request the complete with the setting reduced to its maximum." }, "sequenceSort": { "type": "boolean", "description": "Whether 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.", "default": false }, "sequenceHeatMap": { "type": "boolean", "description": "Colorize 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.", "default": false }, "maxSequenceDistance": { "type": "integer", "description": "maximum distance allowable between two sequence values of items packed in a common box\n\nFor example, \"Distance\" for an item sequence composed of aisle/bin combinations of \"0401\" and \"1228\" has a sequence distance of |1228 - 401| = 827" }, "boxTypeChoiceStyle": { "type": "string", "description": "how available `boxTypes` are selected when a new box must be created to pack additional items\n\n- `estimated` style uses `usableSpace` to estimate how quickly each valid boxType will be filled by both weight and volume, and estimated cost is calculated.\n- `actual` attempts real placement of subsequent items in each available boxType and selects the one with the lowest actual cost.\n\n`actual` is much slower than `estimated`, but will often return superior cost optimizations.", "default": "actual", "enum": [ "actual", "estimated" ] }, "boxTypeChoiceLookahead": { "type": "integer", "description": "When selecting the next available `boxType`, we must consider how far to look ahead.\n\nConsider 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.\n\nIf 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.\n\nAlternatively, 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.\n\nPlease note that `boxTypeChoiceLookahead`, especially when combined with the `actual` `boxTypeChoiceStyle` can have significant performance impacts. 0 is recommended for real-time use cases." }, "boxTypeChoiceLookback": { "type": "integer", "description": "Control the ability for partially-filled boxes to allow packing of later-sorted items. When used with `sequence`, it can greatly reduce item set fragmentation across multiple containers and improve consolidation, sometimes at the expense of overall container count and volume utilization. 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." }, "boxTypeChoiceGoal": { "type": "string", "description": "objective to evaluate `boxTypeChoice`s by\n\n- `lowest-cost` minimizes price or volume cost of boxTypes selected.\n- `most-items` maximizes item count per box opened, i.e., fewest total boxes used.", "default": "lowest-cost", "enum": [ "lowest-cost", "most-items" ] }, "boxesMax": { "type": "integer", "description": "maximum number of boxes to use for packing\n\nThis can potentially result in 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`." }, "boxesPerItemSetMax": { "type": "integer", "description": "maximum number of boxes that a single `ItemSet`'s member items (i.e., all that share the same `refId`) can be spread across\n\nAny 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." }, "boxesPerSequenceMax": { "type": "integer", "description": "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.\n\nAny 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." }, "itemsPerBoxMax": { "type": "integer", "description": "maximum quantity of discrete items that a single box can contain\n\nThe default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, optionally overridden by `boxType` settings." }, "itemSetsPerBoxMax": { "type": "integer", "description": "maximum quantity of unique `item.refId` values that a single box can contain\n\nThe default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, optionally overridden by `boxType` settings." }, "itemsInlineMax": { "type": "array", "description": "maximum number of items 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\n\nA value of 0 is equivalent to no limit along that axis. Overridden by `boxType` settings.", "example": [ 1, 2, 1 ], "items": { "type": "integer" } }, "generatedBoxTypesMax": { "type": "integer", "description": "maximum number of generated box sizes to randomly sampled when generating box types\n\nDefault of 0 is unlimited, and in some cases may never return without a limit. 64 is a sensible value.", "example": 64 }, "valueTiebreaker": { "type": "string", "description": "tiebreaker to use in the event to box type choices are otherwise completely equal\n\nDefault is `volume`, alternative is `weight`.", "default": "volume", "enum": [ "volume", "weight" ] }, "properties": { "type": "object", "additionalProperties": true, "description": "additional properties of the pack request which are all returned in the response" }, "timeout": { "type": "number", "description": "optional timeout for request computation, will be reduced to endpoint maximum if in excess of published timeout", "example": 30 } } }, "BoxProperties": { "required": [ "dimensions", "weightMax" ], "type": "object", "properties": { "name": { "type": "string", "description": "name for the type of box" }, "refId": { "type": "integer", "description": "box type reference identifier passed backed from request" }, "price": { "minimum": 0, "type": "integer", "description": "fixed price of the container, in whole units of currency, default USD cents\n\nThis 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 surcharges, oversize fees, etc. This value is _added_ to any rate table rates defined for the carton." }, "weightTare": { "minimum": 0, "type": "number", "description": "weight of the container when empty or otherwise unladen, i.e., of the box itself" }, "weightMax": { "minimum": 0, "type": "number", "description": "maximum allowable gross weight for the box, i.e., all packed item weights plus the weightTare" }, "dimensions": { "type": "object", "description": "the [height,length,width] of the box", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "outer": { "type": "object", "properties": { "dimensions": { "type": "object", "description": "on return, if an outer `dimensionChange` was specified, the final dimensions of the box", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "dimensionChange": { "type": "object", "description": "Outers must be specified as the difference of each dimension from the inner dimensions. E.g., an inner `x` of 10 with an outer `dimensionChange.x` of `0.25` would result in an `outer.dimensions.x` of `10.25`. Outers are only used for informational purposes, and for `pack-sequence` rule operations when using the `boxes-to-items` `reduce` method (to add outer dimensions to inner boxes when they are packed in later steps).", "allOf": [ { "$ref": "#/components/schemas/Point" } ] } }, "description": "if required, data describing the outer dimensions of the box" }, "outerBasedCost": { "type": "boolean", "description": "If `true`, will base `dimensionalWeight` and any price component thresholds upon the outer dimensions, not the inner packable dimensions.", "default": false }, "centerOfMass": { "type": "object", "description": "the coordinates of the center of mass of the box", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "reservedSpace": { "maximum": 1, "minimum": 0, "type": "number", "description": "space in boxes that is reserved, i.e., for packing material, overriding top-level `reservedSpace`", "example": 0.2 }, "itemsPerBoxMax": { "type": "integer", "description": "maximum quantity of discrete items that a single box can contain\n\nThe default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, overriding top-level `itemsPerBoxMax`." }, "itemSetsPerBoxMax": { "type": "integer", "description": "maximum quantity of unique `item.refId` values that a single box can contain\n\nThe default setting of 0, a negative number, and null are all equivalent and indicate no maximum limit, overriding top-level `itemSetsPerBoxMax` settings." }, "itemsInlineMax": { "type": "array", "description": "maximum number of items which can share a placement on a specific line parallel to the placement axis\n\nFor example, `[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.", "example": [ 1, 2, 1 ], "items": { "type": "integer" } }, "rateTable": { "type": "object", "description": "An 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:\n\n- Provide carrier, service, and zone.
  • Provide all acceptable weights and prices to use for the carton, similar to actual carrier rate tables.\n- Provide the coefficients required for a simple linear weight-dependent pricing model.", "allOf": [ { "$ref": "#/components/schemas/RateTable" } ] }, "propertyConstraints": { "type": "array", "description": "In order to add arbitrary constraints for certain items based not upon weight or physical dimensions, a `propertyConstraint` can be added here for each additional numerical constraint desired. E.g., limiting the weight of a restricted component of an item to 5 lbs per box, while still allowing total item weight of, e.g., 50 lbs per box. All numeric properties are treated as unit amounts and summed individually (not at the `ItemSet` level).", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "the string matching the item `properties` key to search for" }, "max": { "type": "number", "description": "the maximum allowable value for the member items with this property" }, "aggregate": { "type": "string", "description": "sum is the only supported aggregate function at present", "default": "sum" }, "value": { "type": "number", "description": "the value of the constrained item property within this box. to set an initial value, include it in your `boxType` definition" } } } } } }, "BoxType": { "description": "box types to be used for packing", "allOf": [ { "$ref": "#/components/schemas/BoxProperties" } ] }, "BoxTypeSet": { "type": "string", "description": "box type sets for convenient demo defaults", "enum": [ "customer" ] }, "BoxTypeGenerator": { "type": "object", "properties": { "boxTypeDefaults": { "type": "object", "description": "default attributes for all generated `boxTypes`", "allOf": [ { "$ref": "#/components/schemas/BoxProperties" } ] }, "operation": { "type": "string", "description": "- `cartesian` requires axis list and range `options` fields in order to discover acceptable carton sizes\n- `pack-as-is` generates a box for each item (optionally selected by an itemMatch `exclude` rule to capture only items able to be shipped as is) and includes default or custom rate and pricing information on the as-is packaging to adequately weight the decision between overboxing (potentially with other items) or shipping alone. Compare with the `pack-as-is` rule, which will strictly pass through an item as an output box, and will not evaluate whether to overbox. E.g., a `price` of -1 can be set in the `boxTypeDefaults` object for a `pack-as-is` generator in order to incentivize a pack-as-is versus an overbox the smallest meaningful amount.", "enum": [ "cartesian", "pack-as-is" ] }, "options": { "type": "object", "properties": { "xList": { "type": "object", "description": "list of available x-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisList" } ] }, "xRange": { "type": "object", "description": "range of available x-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisRange" } ] }, "yList": { "type": "object", "description": "list of available y-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisList" } ] }, "yRange": { "type": "object", "description": "range of available y-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisRange" } ] }, "zList": { "type": "object", "description": "list of available z-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisList" } ] }, "zRange": { "type": "object", "description": "range of available z-axis lengths", "allOf": [ { "$ref": "#/components/schemas/GeneratorAxisRange" } ] }, "limits": { "type": "array", "description": "list of GeneratorLimit objects defining the bounds of generated box sizes", "items": { "$ref": "#/components/schemas/GeneratorLimit" } }, "priceComponents": { "type": "array", "description": "list of GeneratorPriceComponents defining the dynamic price behaviors of generated box sizes", "items": { "$ref": "#/components/schemas/GeneratorPriceComponent" } }, "noTrimToMaxExtent": { "type": "boolean", "description": "If unset or false, the generator will reduce its dimensions to the maximum of the max extent of items placed within it or the minimum specified limit along each axis containing a `GeneratorAxisRange` object; if true, the generator will not reduce its dimensions along any axis; trimming to max extent is ignored on all axes with only `GeneratorAxisList` objects, as to respect specified box footprints. By default, rounds up trimmed dimensions to the nearest tenths unit of length." } } } }, "description": "a generator of box types, specifying bounds of acceptable box types and defining dynamic cost characteristics" }, "GeneratorAxisList": { "type": "array", "description": "enumerated list of possible lengths for given axis", "items": { "type": "number" } }, "GeneratorAxisRange": { "type": "object", "properties": { "min": { "type": "number", "description": "the minimum possible axis length to generate" }, "max": { "type": "number", "description": "the maximum possible axis length to generate" }, "deriveFromItems": { "type": "boolean", "description": "If true, intelligently select possible axis lengths based upon item dimensions.", "default": false }, "fitForFirstItem": { "type": "boolean", "description": "If true, select axis length based upon first item placed in each generated box, overriding deriveFromItems and increment", "default": false }, "increment": { "type": "number", "description": "If `deriveFromItems` is not true, the desired increment for box dimension rounding. E.g., 0.25 for a box in inches would round up to the quarter inch. 10 would round to the next even 10s digit. Note that `min` and `max` are included as is, and are not rounded to the nearest `increment`. So, `min` 5, `max` 59, `increment` 10 could produce any of `[5,10,20,30,40,50,59]` for this `GeneratorAxisRange`. Also note that small `increment` values would benefit from a `generatedBoxTypesMax` set." } }, "description": "configurable range of possible lengths for given axis" }, "GeneratorLimit": { "type": "object", "properties": { "metric": { "$ref": "#/components/schemas/Metric" }, "min": { "type": "number", "description": "minimum allowable value of calculated metric" }, "max": { "type": "number", "description": "maximum allowable value of calculated metric" } }, "description": "A generator limit for a given calculated box size metric. *NB:* use a `GeneratorAxisList` when explicitly setting footprints if you want any two dimensions to be equal to each other. Using dynamic `-ratio` based limits with a `max` of 1.0 for, e.g, `longest-to-middle-ratio` will often result in no allowable boxes being generated." }, "GeneratorPriceComponent": { "type": "object", "properties": { "key": { "type": "string", "description": "key for a given price component, allowing for multiple metrics to calculate the same value, in which case the maximum price will be selected" }, "metric": { "$ref": "#/components/schemas/Metric" }, "aggregator": { "type": "string", "description": "how to aggregate `priceComponents` with common `key` values\n\n- `max` selects the largest threshold price across all `priceComponents` sharing a `key`.\n- `product` takes the last (i.e., highest) matching threshold price from each `priceComponent` sharing a `key` and multiplies them together.\n- `sum` simply sums all prices from all matching thresholds across all `priceComponents` sharing the same key.\n\n*NB* all `priceComponents` sharing a `key` must share the same `aggregator` to have predictable behavior.", "default": "max", "enum": [ "max", "product", "sum" ] }, "thresholds": { "type": "array", "description": "list of number thresholds of corresponding metric above which corresponding prices are triggered. Note that thresholds are traversed in reverse in cases where order matters (e.g., when using the `product` aggregator)", "items": { "type": "number" } }, "prices": { "type": "array", "description": "list of integer price values to assign when corresponding thresholds are exceeded", "items": { "type": "integer" } } }, "description": "a dynamic price component determining the generated box price property to set" }, "Metric": { "type": "string", "description": "A named calculation for a specific value derived from a cuboid (e.g., an item or a box)", "enum": [ "volume", "surface-area", "surface-area-rsc", "longest-dimension", "middle-dimension", "shortest-dimension", "length-plus-girth", "girth", "x-dimension", "y-dimension", "z-dimension", "longest-to-middle-ratio", "longest-to-shortest-ratio", "middle-to-shortest-ratio", "z-to-y-ratio", "z-to-x-ratio", "y-to-x-ratio" ] }, "Box": { "description": "a completed, packed box", "allOf": [ { "$ref": "#/components/schemas/BoxProperties" }, { "type": "object", "properties": { "id": { "type": "integer" }, "subspace": { "$ref": "#/components/schemas/Subspace" }, "boxType": { "$ref": "#/components/schemas/BoxType" }, "items": { "title": "items", "type": "array", "items": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" } } } }, "volumeMax": { "minimum": 0, "type": "number", "description": "total volume of the box" }, "volumeUsed": { "minimum": 0, "type": "number", "description": "utilized volume of the box, i.e., item volume plus reserved volume" }, "volumeNet": { "minimum": 0, "type": "number", "description": "volume of box utilized solely by packed items" }, "volumeRemaining": { "minimum": 0, "type": "number", "description": "remaining volume of the box" }, "volumeReserved": { "minimum": 0, "type": "number", "description": "reserved volume of the box, i.e., void fill" }, "volumeUtilization": { "maximum": 1, "minimum": 0, "type": "number", "description": "percentage of volume utilized by packed items" }, "weightUsed": { "minimum": 0, "type": "number", "description": "utilized weight of the box" }, "weightNet": { "minimum": 0, "type": "number", "description": "total weight of box's contents, not including the box's empty (tare) weight" }, "weightRemaining": { "minimum": 0, "type": "number", "description": "remaining weight of the box" }, "weightUtilization": { "maximum": 1, "minimum": 0, "type": "number", "description": "percentage of weight utilized by packed items" }, "dimensionalWeight": { "type": "number", "description": "the calculated dimensional weight of this box, if applicable" }, "dimensionalWeightUsed": { "type": "boolean", "description": "whether or not dimensional weight was used for this box" }, "lenItems": { "type": "integer", "description": "cardinality of all non-virtual items packed in this box and in any dependent subspaces it contains" }, "lenUnits": { "type": "integer", "description": "cardinality of distinct units of items (count of cases, eaches, etc.)" }, "svg": { "type": "string", "description": "raw svg of visualization" }, "centerOfMassString": { "type": "string", "description": "string representation of box center of mass" }, "depthOrder": { "type": "array", "description": "sorted list of `item.index` values representing the ordering utilized by the render, back to front\n\nThis list works in tandem with the `eye` point, and can represent a potentially feasible real-world packing order.\n\nE.g., if the `eye` is set to `{x:1, y:0, z:0}`, then the packing image will show a top-down view of the carton, and `depthOrder` will contain the order to place items so that all items on the bottom of the carton are packed first, then those in the next layer, etc., so that no item is placed beneath another already placed item.\n\nConversely, if the `eye` is set to `{x:0, y:0, z:1}`, the packing image will show an end-on view--as if from the doors of a shipping trailer, and `depthOrder` will contain the order to place items so that all items farthest from the doors are placed before items directly in front of them.", "items": { "type": "integer" } }, "depthOrderString": { "type": "string", "description": "string representation of depth ordering" } } } ] }, "ItemProperties": { "required": [ "dimensions", "weight" ], "type": "object", "properties": { "refId": { "type": "integer", "description": "item type reference identifier passed backed from request\n\nA value of -1 or null will be auto-assigned to a unique identifier by distinct item or itemSet." }, "name": { "type": "string", "description": "name or description of item for your reference" }, "color": { "type": "string", "description": "designated color name or hex code (including leading `#`) for the item in pack visualizations\n\nIf `imageFormat` is set to `PNG`, the color must be a 3-byte (i.e., 6-character) case insensitive hex code plus the leading \"#\", e.g., `#00ffff`." }, "weight": { "type": "number", "description": "weight of this single packed item" }, "sequence": { "type": "string", "description": "a sequence value for the item\n\nThis is intended for aisle-bin locations, e.g., aisle 11 bin 20 can be 1120. Combined with `maxSequenceDistance`, you can restrict cartons to only have contents from within a certain range. This is very helpful for cartonization when picking efficiency is paramount. Sequence can also be used to pre-sort items for efficient packing on any arbitrary number, such as item weight instead of the default item volume." }, "dimensions": { "type": "object", "description": "the length, width, and height of the item", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "centerOfMass": { "type": "object", "description": "the coordinates of the center of mass of the item", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "virtual": { "type": "boolean", "description": "whether or not this is a real item or a virtual, blocking space (from a subspace or loading rules)", "default": false }, "properties": { "type": "object", "additionalProperties": true, "description": "additional properties to track per unit, which are all returned in the response\n\nNumerical properties can be used in conjunction with box type `propertyConstraints` to control packing (very much akin to weight constraints). \n\nE.g., an item property on a Faberge egg of `\"priceless-egg-quantity\": 1` with a matching constraint of `\"key\": \"priceless-egg-quantity\", \"max\": 2, \"aggregate\": \"sum\"` would limit to 2 Faberge eggs per box.\n\nAnother box constraint with `\"key\": \"priceless-egg-quantity\", \"max\": 0` instead would effectively prohibit any items with that quantity from packing in it, similar to an exclude rule.\n\nConversely, each egg could have its own insurance amount, and there may be a maximum allowable amount per box, such as `\"priceless-egg-value\": 33000000` for one and `\"priceless-egg-value\": 22000000` for a second (for $55 million total) with a corresponding constraint of `\"key\": \"priceless-egg-value\", \"max\": 50000000` would prevent both eggs from being placed in one box, as $55 million exceeds the $50 million constraint on a single box (and they would be placed in their own boxes insured for $33 million and $22 million respectively)", "example": { "included-ice-lbs": 0.5, "restricted-qty": 0.1, "item-line-id": "1234-59581ABC-CAFE1909", "wms-fields": { "InternalItemID": 1398401, "SKU": 49831, "Location": "40-8012", "Kit": false, "OtherGenericProperties": "will be passed through and returned on the item" } } } }, "description": "general properties of an item" }, "Item": { "description": "a specific, packed item", "allOf": [ { "$ref": "#/components/schemas/ItemProperties" }, { "type": "object", "properties": { "index": { "type": "integer", "description": "the item index referring to this instance, used by `data-volume-index` in the returned SVG data\n\n`depthOrder`, `parentItemIndex`, etc.; may appear non-sequential as `virtual` display volumes are also given index values to permit SVG targeting." }, "globalId": { "type": "integer", "description": "the internal packer global index assigned to this instance based upon packer item instantiation order" }, "packedIndex": { "type": "integer", "description": "this item's packing index, i.e., its position within the best-performing item sort" }, "message": { "type": "string", "description": "any relevant information or warnings about the packing of the item" }, "origin": { "type": "object", "description": "the [x,y,z] placement point of the back-bottom corner of the item", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "deltaCost": { "type": "integer", "description": "the change in the estimated final cost of the box caused by adding the item" }, "uniqueId": { "type": "string", "description": "a combination of the item's refId and its packing sequence, uniquely identifying it" }, "groupPackParent": { "type": "string", "description": "if specified, the uniqueId of the group-pack parent item this item belongs to" }, "quantity": { "type": "integer", "description": "quantity of basis item, i.e., eaches, this item represents, if dimensionSets were used with variable quantity contents" }, "unitOfMeasure": { "type": "string", "description": "unit of measure, if specified. not defined or null if none" }, "dimensionSet": { "type": "object", "description": "the `dimensionSet` used for this specific item object", "allOf": [ { "$ref": "#/components/schemas/DimensionSet" } ] } } } ] }, "ItemSet": { "description": "set of items sharing a common type", "allOf": [ { "$ref": "#/components/schemas/ItemProperties" }, { "type": "object", "properties": { "quantity": { "type": "integer", "description": "quantity of items of this type in this item set" }, "dimensionSets": { "type": "array", "description": "alternate list of dimensions for automatic conversion of items into larger units of measure (optional)\n\nThe first element is assumed to be \"each\", and will use the base \"dimensions\" and \"weight\" if none is provided. Additional units of measure are preferentially selected in reverse, from the last dimensionSet to the first. If the \"quantityDivisor\" value is less than the quantity of the itemSet, then the weight and dimensions are either automatically multiplied (with \"axisMultipliers\") or explicitly set with \"dimensions\" and \"weight\". The remaining item \"quantity\" is reduced by \"quantityDivisor\" as many times as possible, with remainders being filled by subordinate units of measure, with eaches being preserved last. Units are counted towards \"lenUnits\", whereas total item quantity counts towards \"lenItems\". NB, \"alternate-dimensions\" and \"group-pack\" should not be used with \"dimensionSets\" as they may cause unexpected results.", "items": { "$ref": "#/components/schemas/DimensionSet" } } } } ] }, "DimensionSet": { "title": "DimensionSet", "type": "object", "properties": { "dimensions": { "type": "object", "description": "dimensions of the item in this configuration", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "axisMultipliers": { "type": "object", "description": "multiples in x, y, and z directions of the item in this configuration\n\nFor example, x:1, y:2, z:3 for a 3x2 6 pack of soda. If unspecified, \"quantityDivisor\" will default to the product of all 3 multiples. It it always relative to the basis dimensions of the item, i.e., each dimensions.", "allOf": [ { "$ref": "#/components/schemas/Point" } ] }, "quantityDivisor": { "type": "integer", "description": "quantity of the item contained in this configuration, i.e., in pieces or eaches" }, "weight": { "type": "number", "description": "weight of the item in this configuration. If unspecified, `weight` will default to the basis item weight times `quantityDivisor`" }, "unitOfMeasure": { "type": "string", "description": "name or label for the unit of measure\n\nThe first DimensionSet will always default to \"each\" unless otherwise specified." } }, "description": "set of dimensions for a specific item unit of measure, to be assembled in an ordered, hierarchical list of DimensionSets, each representing a whole quantity of the item\n\nUse `dimensions`, `weight`, and `quantityDivisor` properties when measurements are known (e.g., 8-count case outer `dimensions` with `weight` including the empty case weight, with 8 as the `quantityDivisor`), or `axisMultipliers` when trying to pack in known multiples of the base item dimensions (or when it is unknown), e.g., a 6-pack of soda would be `\"axisMultipliers\":{\"x\":1,\"y\":2,\"z\":3}` for a 1-high by 2-wide by 3-long arrangement. All dimension sets will be used if sufficient quantities exist without regard for available container size or rules, e.g., do not pass \"pallet\" for a small parcel shipment." }, "BoxMatch": { "title": "BoxMatch", "type": "object", "properties": { "property": { "type": "string", "description": "`boxType` property to search with the expression\n\nIf `name`, it will search the `name` property of the `boxType`, otherwise it will search `boxType` `properties` for any keys matching `property` with string values." }, "expression": { "type": "string", "description": "query string to search the specified boxType property for" }, "expressions": { "type": "array", "description": "query strings to search the specified boxType property for", "items": { "type": "string" } }, "negate": { "type": "boolean", "description": "If true, negate substring search so rule applies only to boxType properties not matching expression.", "default": false } }, "description": "Specify the boxes a rule applies to based upon a search substring of a `boxType` property. Both `expression` and `property` must be set." }, "ItemMatch": { "title": "ItemMatch", "type": "object", "properties": { "all": { "type": "boolean", "description": "If true, match this rule on all item sets specified in the request." }, "property": { "type": "string", "description": "The `itemSet` property to search with the expression. If `name` or `sequence`, it will search the `name` or `sequence` property of the `itemSet`, otherwise it will search `itemSet` `properties` for any keys matching `property` with string values." }, "expression": { "type": "string", "description": "query string to search the specified itemSet property for" }, "expressions": { "type": "array", "description": "query strings to search the specified itemSet property for", "items": { "type": "string" } }, "negate": { "type": "boolean", "description": "If true, negate substring search so rule applies only to itemSet properties not matching expression.", "default": false } }, "description": "Specify the items a rule applies to based upon a search substring of an itemSet property. Either `all` must be set to true or both `expression` and `property` must be set." }, "Rule": { "required": [ "operation" ], "type": "object", "properties": { "itemRefId": { "type": "integer", "description": "reference ID for the item the rule applies to" }, "itemSequence": { "type": "string", "description": "sequence string shared by all items for the rule to apply to" }, "itemMatch": { "type": "object", "description": "optional object defining a substring search and property to search for items the rule applies to", "allOf": [ { "$ref": "#/components/schemas/ItemMatch" } ] }, "targetItemRefIds": { "type": "array", "description": "target item reference IDs that the rule applies to", "items": { "type": "integer" } }, "targetItemSequences": { "type": "array", "description": "target item sequences that the rule applies to", "items": { "type": "string" } }, "targetItemMatch": { "type": "object", "description": "optional object defining a substring search and property to search for target items the rule applies to", "allOf": [ { "$ref": "#/components/schemas/ItemMatch" } ] }, "targetBoxMatch": { "type": "object", "description": "optional object defining a substring search and property to search for target boxes the rule applies to", "allOf": [ { "$ref": "#/components/schemas/BoxMatch" } ] }, "targetBoxRefIds": { "type": "array", "description": "target box reference IDs that the rule applies to", "items": { "type": "integer" } }, "ignoreSubspaces": { "type": "boolean", "description": "If true, `ignoreSubspaces` enforces that the relationship between a source item and any target object must be direct for the rule to apply, either between two items that are direct members of the same box, or between an item and its direct parent box. For instance, any items in an inner pack (like from `pack-sequence`) which is then packed in an outer, would not have the rule applied when `ignoreSubspaces` is true." }, "operation": { "type": "string", "description": "Rule type for this definition. Valid operation values include\n