PackNet DIM Cartonize Endpoint
Returns a cubing result based on the dimensional data of items within an order. This endpoint does not create a carton request. To complete the packaging lifecycle, a subsequent carton request to PackNet Core Import Data Directly Endpoint is required, using the results from the cubing operation. This endpoint is useful for testing and validation of cubing logic and configurations.
[POST] https://api.prod1.packnet.app/Dim/v1/Cartonize/
Status Codes
200 OK: Command received and processed.
400 Bad request: The request cannot be processed due to apparent client error.
403 Forbidden: The user is not allowed to make the request.
500 Internal server error: The server does not know how to process the request.
{
"orderId": "ORDER-12345",
"brand": "1",
"cartonDesign": "",
"productionGroup": "",
"machineGroup": "",
"x-value": "1",
"aCustomValue": "Brown",
"itemsToPack": [
{
"productId": "514",
"quantity": 2,
"dimensions": {
"length": 12,
"width": 10,
"height": 8
},
"description": "Keep all your bread in this kitchen basket",
"name": "Bread Basket",
"orientationLocked": true,
"weight": 0.58,
"CanContain": true,
"voidFill": {
"length": 11,
"width": 9,
"height": 7
},
"canNest": true,
"nesting": {
"nestGrowthDimension1": 0,
"nestGrowthDimension2": 0,
"nestGrowthDimension3": 1,
"nestMax": 10
},
"RequiresPadding": false,
"useDefaultPadding": false,
"padding": 2,
"isSingleLayer": true
}
]
}Returns a list of Cartonize Response objects containing packing results:
{
"timeoutReached": false,
"orderId": "ORDER-12345",
"isCompletePack": true,
"unpackedItems": [],
"containers": [
{
"id": 6,
"dimensionX": 10,
"dimensionY": 12,
"dimensionZ": 9,
"packedItemsWeight": 1.16,
"packedItemsCount": 2,
"percentContainerVolumePacked": 100.0,
"packedItems": [
{
"coordinateX": 0.0,
"coordinateY": 0.0,
"coordinateZ": 0.0,
"packedDimensionX": 10.0,
"packedDimensionY": 12.0,
"packedDimensionZ": 9.0,
"nestedQuantity": 2,
"containedItems": null,
"uniqueIdentifier": "514",
"weight": 1.16
}
]
}
],
"passthroughValues": {
"x-value": "1",
"aCustomValue": "Brown"
},
"messages": []
}PackNet DIM Cartonize Field Descriptions
Cartonize Request Parameters
Main Request Object
Field | Data Type | Required | Description |
|---|---|---|---|
orderId | String | Yes | Unique identifier for the order |
brand | String | No | Brand name for the carton |
cartonDesign | String | No | Carton design specification |
productionGroup | String | No | Production group identifier |
machineGroup | String | No | Machine group identifier |
xValues | Object | No | Dictionary of custom X values (key-value pairs) |
aCustomValue | String | No | Custom attribute applied to the order, often used for color or material |
itemsToPack | ItemToPack | Yes | List of items to pack in the carton |
itemsToPack Objects
Field | Data Type | Required | Description |
|---|---|---|---|
productId | String | Yes | Product identifier (must exist in the system or dimensions must be provided) |
quantity | Integer | Yes | Number of items (must be greater than 0) |
dimensions | Object | No | Product dimensions (required when product doesn't exist in the system) |
description | String | No | Detailed description of the product |
name | String | Yes | Product name or label |
orientationLocked | Boolean | No | Indicates if product orientation must remain fixed during packing |
weight | Float | No | Product weight in kilograms or pounds (depending on system) |
canContain | Boolean | No | Specifies if the product can contain other items inside it |
voidFill | Object | No | Defines void-fill space dimensions around the product |
canNest | Boolean | No | Indicates whether the product can be nested inside another of the same type to save space; the nesting behavior is defined in the nesting object |
nesting | Object | No | Specifies nesting behavior if product can stack inside another |
requiresPadding | Boolean | No | Whether the product requires padding during packaging |
useDefaultPadding | Boolean | No | If true, applies default padding values from system configuration |
padding | Integer | No | Manual padding amount (in chosen unit) |
isSingleLayer | Boolean | No | Determines if the product must be packed in a single layer |
dimensions Object
Field | Data Type | Required | Description |
|---|---|---|---|
length | Float | Yes | Length of the product |
width | Float | Yes | Width of the product |
height | Float | Yes | Height of the product |
voidFill Object
Field | Data Type | Required | Description |
|---|---|---|---|
length | Integer | No | Void-fill length dimension |
width | Integer | No | Void-fill width dimension |
height | Integer | No | Void-fill height dimension |
nesting Object
Field | Data Type | Required | Description |
|---|---|---|---|
nestGrowthDimension1 | Integer | No | Growth factor for first nesting dimension |
nestGrowthDimension2 | Integer | No | Growth factor for second nesting dimension |
nestGrowthDimension3 | Integer | No | Growth factor for third nesting dimension |
nestMax | Integer | No | Maximum number of items that can be nested |
Note
When product attributes, including dimensions, are provided in an API request, those values are used for carton creation regardless of if the product is stored in the DIM database. When dimensions are not provided, the system will look up the product in the DIM database and use the stored dimensions.
Cartonize Response Parameters
Main Response
Field | Data Type | Description |
|---|---|---|
timeoutReached | Boolean | Indicates when the packing algorithm timed out |
orderId | String | Order identifier from the request |
isCompletePack | Boolean | True when all items were successfully packed |
unpackedItems | Array | List of items identifiers that could not be packed |
containers | ContainerResult | List of container results with packing details |
passthroughValues | Object | Custom X values passed through |
messages | Array | Any messages or warning from the packing process |
Container Result
Field | Data Type | Description |
|---|---|---|
id | Integer | Container identifier |
dimensionX | Double | Container length |
dimensionY | Double | Container width |
dimensionZ | Double | Container height |
packedItemsWeight | Decimal | Total weight of packed items |
packedItemsCount | Integer | Number of items packed in container |
percentContainerVolumePacked | Decimal | Percentage of container volume utilized |
packedItems | PackedItem | List of packed items with positions |
Packed Item
Field | Data Type | Description |
|---|---|---|
coordinateX | Decimal | X position in container |
coordinateY | Decimal | Y position in container |
coordinateZ | Decimal | Z position in container |
packedDimensionX | Decimal | Packed item length |
packedDimensionY | Decimal | Packed item width |
packedDimensionZ | Decimal | Packed item height |
nestedQuantity | Integer | Quantity of nested items |
containsAnother | Array | List of nested item identifiers |
uniqueIdentifier | String | Product identifier |
Weight | Decimal | Item weight |
Notes and Best Practices
Preview before create: Use the Cartonize endpoint to validate carton configurations before creating actual cartons.
Carton Options: Define appropriate minimum and maximum dimensions based on the available carton sizes and shipping constraints.
Optimization: The orderBy parameter in packaging options determines how cartons are optimized:
percent-filled: Maximizes space utilization
volume: Minimizes total volume
weight: Distributes weight evenly
Multiple Cartons: Set maxCartons to control how many cartons can be created for a single order. Set to 1 for single-carton orders.
Weight Limits: Always specify maximumWeight in carton options to comply with shipping weight restrictions.
Unit Consistency: Make sure all products in a request use the same unit of measure for dimensions and weight.
Integration with Cube: The Carton Create endpoint integrates with Packsize's cubing algorithm for optimal packing. Make sure is cubing properly configured in the UI in the PackNet Cube section.
Error Handling: When carton creation fails, check:
Products fit within specified carton constraints.
Weight limits are not exceeded.
License tier is sufficient.
All required fields are provided.
Performance: For large orders with many products, the carton calculation may take several seconds. Consider using appropriate timeout values.
Common Error Scenarios
403 Forbidden - Insufficient License
{
"error": "Forbidden",
"message": "professional or enterprise license required for carton operations",
"statusCode": 403
}Solution: Upgrade tenant license to Professional or Enterprise tier.
400 Bad Request - Invalid Dimensions
{
"error": "Bad Request",
"message": "Products cannot fit within specified carton constraints",
"statusCode": 400,
"details": {
"productId": "PROD-12345",
"productDimensions": "15x12x10",
"maxCartonDimensions": "12x10x8"
}
}Solution: Adjust carton options to accommodate larger products or reduce product dimensions.
400 Bad Request - Weight Exceeded
{
"error": "Bad Request",
"message": "Total weight exceeds maximum carton weight",
"statusCode": 400,
"details": {
"totalWeight": 55.0,
"maximumWeight": 50.0,
"weightUom": "lb"
}
}Solution: Increase maximum weight limit or split order into multiple cartons.