CubeMaster API V2 Developer Guide

Integrate the CubeMaster Load Planning Engine directly into your workflow. This document details the full JSON schema parameters for precision load building.

Base URL: https://api.cubemaster.net

Authentication

CubeMaster requires a specific header for all requests. Obtain yours from your CubeMaster account under Settings > Integration.

HEADER TokenID: {YOUR_API_KEY}

Note: Do not use 'Authorization: Bearer'. Use 'TokenID'.

Load Object

The top-level request body for POST /loads, defining the entire load calculation input.

Basic Parameters

Field Type Description
title string Required. Unique name for the load. Used for saving and retrieval.
description string Optional text description of the load.

Core Components

Field Type Description
cargoes array of Cargo Required. List of cargo items to load. Each is a Cargo object.
emptyContainers array of EmptyContainer Required. Available containers to fill. Each is an EmptyContainer object.
rules Rules object Optional. Calculation rules and constraints.
Sample Load JSON 
{
  "title": "Sample Load",
  "description": "Test mix load",
  "cargoes": [
    {
      "style": "Shipcase",
      "name": "Box1",
      "length": 10,
      "width": 5,
      "height": 3,
      "weight": 20,
      "qty": 50
    }
  ],
  "emptyContainers": [
    {
      "containerType": "Truck",
      "name": "Standard Truck",
      "length": 20,
      "width": 8,
      "height": 8,
      "maxWeight": 1000
    }
  ],
  "rules": {
    "calculationType": "MixLoad",
    "algorithmType": "Optimization"
  }
}

Cargo Object

The Cargo object defines an item or product (SKU) to be placed in a container. It includes metadata, dimensions, weight, stacking rules, and palletization details.

Basic

Parameter Type Description
style string The general physical type of cargo. Required. [See StyleEnum]
name string Unique identifier for the cargo, e.g., SKU or part number. Required.
description string Descriptive text for the cargo, max 50 characters.
length integer Length of the cargo in the unit specified by UOM (e.g., mm or inches). Required if not loaded from database.
width integer Width of the cargo. Required if not loaded from database.
height integer Height of the cargo. Required if not loaded from database.
weight float Weight of the cargo in the unit specified by UOM (e.g., kg or lbs).
qty integer Quantity of the cargo to ship. For pre-pack unitloads, represents number of unitloads. Required.
pieceInside integer Number of pieces inside each cargo unit (e.g., smaller boxes in a shipping box). Used to calculate total pieces as qty * pieceInside.

Orientations

Parameter Type Description
orientationsAllowed string String specifying permitted 3D rotations for the cargo. For example, "Orientations12" allows the cargo to sit upright lengthwise (#1) and turned horizontally (#2). Values can combine numbers 1 through 6, representing all possible orthogonal rotations (e.g., "Orientations123456" opens all 6 permutations). [See OrientationEnum]
turnAllowedOnFloor boolean Boolean flag determining if the cargo can be placed in orientations 3 (side), 4 (side turned), 5 (end), or 6 (end turned) directly on the container floor or pallet deck. (Note: These orientations must first be permitted by the `orientationsAllowed` parameter).
Practical Case: A tall refrigerator must stand upright on the floor to maintain its structural integrity and avoid taking up excessive base footprint. However, if vertical space permits, it can safely be laid flat horizontally only if it is resting on top of other upright refrigerators. In this case, you would set `orientationsAllowed` to include the side orientations (e.g., "Orientations1234") and set `turnAllowedOnFloor=false`. This forces the engine to always place the very bottom layer of refrigerators upright (1 or 2) on the floor, while permitting subsequent stacked units to be laid on their side (3 or 4).
orientationPriority null/string Priority for orientations (null if not set).
maxLayersOnOrientation1 to maxLayersOnOrientation6 integer Max layers for each orientation. 0 means no limit.
Definition: This field sets the maximum number of layers that can be placed on each orientation of the cargo.

How it works:
  • The maxLayersOnOrientation is a hard constraint. If the calculated number of layers exceeds this value, it will be excluded from the results.
Example:
  • If you set maxLayersOnOrientation1 to 2, the cargo will be placed in at most 2 layers when it is placed on its 1st orientation.

Unitload

Parameter Type Description
isPalletized boolean If true, cargo is palletized before loading.
Practical Case: If you receive an order of 200 loose cartons but your warehouse ships them on standard US pallets, set `isPalletized=true` and provide the pallet details. The engine will first build optimal pallets, then load those structured pallets into the target truck instead of loose boxes.
palletizing object Pallet configuration details.
palletizing.pallet object Pallet details: containerType ("Pallet"), palletType (e.g., "Wood2WaysDoube"), dimensions, etc.
palletizing.flatPalletTop boolean If true, keeps top of partial unitload flat.
palletizing.partialPalletsAllowed boolean If true, allows partial pallet loads.
palletizing.remainQtyToMixPallet boolean If true, remaining qty placed on mixed pallets.
palletizing.remainQtyToVehicle boolean If true, remaining qty placed directly on vehicle floor.
palletizing.fixedCargoCountOnPallet integer Fixed number of cargo per pallet (0 for no fixed).
unitloadTopPattern string Arrangement pattern of the top layers of the unitload. [See PatternEnum]
unitloadBottomPattern string Arrangement pattern of the bottom layers of the unitload. [See PatternEnum]
unitloadLayersQtyRotated integer Number of layers to rotate in unitload for stability.

Extended

Parameter Type Description
orderPieces integer Number of pieces ordered (often 0 if not used).
setRatio integer Ratio for set loads (e.g., 1:2:1 for components). Used in "Set Load" or "Multiple Set Load" types to maintain proportions.
price integer Price of the cargo in US$. Used if load price limited rule is active.
alias string Alias or alternative identifier for the cargo.
alias2 string Second alias.
groupName string Group name for keeping cargoes together or separating by stops/destinations.
property1 to property10 string Custom properties for additional metadata (max 50 characters each). For display in reports.
sequence integer Loading sequence. Lower values load first if "Small sequences placed earlier" rule is on.
diameter integer Diameter for cylindrical cargo (rolls). Set to 0 for non-cylindrical.
color integer Numeric color code for visualization (e.g., 65535).
Definition: This field sets the numeric color code for the cargo visualization.

How it works:
  • The color is a 16-bit integer that represents the color of the cargo.
  • The color is used to visualize the cargo in the 3D visualization of the container loading layout.
Example:
  • If you set color to 65535, the cargo will be displayed in red color.
colorHexaCode string Hex color code for visualization (e.g., "FF0000").
Definition: This field sets the hexadecimal color code for the cargo visualization.

How it works:
  • The colorHexaCode is a 6-digit hexadecimal color code that represents the color of the cargo.
  • The color is used to visualize the cargo in the 3D visualization of the container loading layout.
Example:
  • If you set colorHexaCode to FF0000, the cargo will be displayed in red color.
colorKnownName string Human-readable color name (empty if not specified).
Definition: This field sets the human-readable color name for the cargo visualization.

How it works:
  • The colorKnownName is a string that represents the color of the cargo.
  • The color is used to visualize the cargo in the 3D visualization of the cargo.
Example:
  • If you set colorKnownName to Red, the cargo will be displayed in red color.

Advanced

Parameter Type Description
maxLayersAllowedOverDifferentCargoes boolean If true, allows stacking over different cargoes.
stackValue integer Stack value for stacking rules. This integer defines stacking relations among different cargoes. A cargo is typically allowed to be placed on others with a greater or equal stack value, depending on the chosen StackingRuleEnum.
Practical Case: You have fragile cargo (value 1) and sturdy cargo (value 5). By setting the stacking rule to "A cargo is allowed to place on others with greater stack value", the engine will only place the fragile cargo on top of the sturdy one, never the other way around.
stackCode string Code for stacking compatibility.
maxSupportingWeight integer Maximum weight that can be safely placed on top of this cargo. This determines how many layers high the engine can safely stack other cargoes on top of this one.
Practical Case: A cardboard carton can only support 50 kg of overhead weight before crushing. By setting maxSupportingWeight to 50, you ensure the engine won't stack heavy items on top of it, protecting the fragile contents.
floorStackType string Floor stacking rule: "Best Fit", "Bottom Only", "No Bottom".
floorStackSupportsOthers boolean If true, this cargo supports others on top in floor stacking.
overhangAllowed boolean If true, overhang allowed.
overhangLength integer Max overhang length.
overhangWidth integer Max overhang width.
isOptional boolean If true, cargo is optional for filling space in balancing.
bulgeSize object Bulge dimensions (length, width, height) for expansion/compression.
emptyContainersFavorite array Preferred containers for this cargo.
faceOpen string Open face: "NeitherSide", etc.
Sample Cargo JSON 
{
  "style": "Shipcase",
  "name": "Cargo1",
  "length": 10,
  "width": 5,
  "height": 3,
  "weight": 20,
  "qty": 50
}

EmptyContainer Object

The EmptyContainer object defines the properties and constraints of an empty shipping container for logistics planning.

Basic

Parameter Type Description
containerType string The structural category of the container. Required. [See ContainerTypeEnum]
name string Identifier, e.g., "53FT-Intermodal".
length integer Length in UOM units.
width integer Width.
height integer Height.
emptyWeight integer Weight of the empty container in UOM units.
maxWeight integer Maximum load weight allowed in the container that includes the emptyWeight, commonly derived from over-the-road or crane weight limits. If greater than 0, the total weight of cargoes loaded will not exceed this value.
Practical Case: Even if a 40FT trailer has plenty of physical volume left, local highway regulations might cap the total gross transport weight. By setting maxWeight, you force the algorithm to stop loading heavy dense items (like metal ingots) once it hits the legal road limit, leaving empty space but ensuring legal transport compliance.

Drop Deck

Parameter Type Description
vehicleDropDeckRearSize null/object Rear drop deck size for trucks: {length, width, height}.
vehicleDropDeckFrontSize null/object Front drop deck size: {length, width, height}.

Extended

Parameter Type Description
description string Optional description (often empty).
qty integer This field defines the available quantity of this container type.
Note: The number of containers to be used for loading. This value is only used when Rules.bestFitContainersSelectionType is BestfitDisabled.

Practical Case: You might have 100 empty 20FT containers in your database (this field would be 100), but your rules might dictate that you only need 3 for this specific shipment. In this case, the algorithm would only use 3 of your 100 available containers.
priority integer Priority for container selection (e.g., 0).
Definition: A unique numerical value (integer) assigned to each empty container in your database. This value determines the order in which the algorithm attempts to fill the container. This value is only used when Rules.bestFitContainersSelectionType is BestfitDisabled.

How it works:
  • Lower numbers = Higher priority.
  • If you have two containers, Container A (priority 0) and Container B (priority 1), the system will try to fit as much cargo as possible into Container A first.
  • Only when Container A is full (or cannot fit any more items based on size, stability, or other constraints) will the system move on to Container B.
  • This allows you to economically prioritize your most expensive or specialized containers (like refrigerated containers or those with special access doors) to be used first.
maxLength integer Maximum cargo length (0 if unrestricted).
maxWidth integer Maximum cargo width (0 if unrestricted).
maxHeight integer Maximum cargo height (e.g., 111).
maxVolPercent integer Maximum volume utilization percentage (0 if unrestricted).
Definition: This field sets the upper limit on how much of a container's total volume can be filled with cargo.

How it works:
  • If maxVolPercent is set to 0 (or is null/absent), there is no limit.
  • If set to 80, the algorithm will not allow the total volume of the placed cargo to exceed 80% of the container's total volume.
  • If set to 100, it allows full utilization.
Practical Use Cases:
  • Product Damage Prevention: For fragile goods like electronics or glassware, you might set this to 70 or 80. This ensures there is always plenty of empty space (cushion) around the cargo to absorb shocks during transit, preventing breakage.
  • Refrigerated Containers: For "reefers," you might set it to 85 or 90. While you want to fill them efficiently, you need that empty space for the cold air to circulate freely around the cargo. If packed too tightly (100%), the cargo at the edges might freeze or warm up, while the center stays cold.
  • Incomplete Shipments: If you are shipping a partial load and want to ensure the container isn't overstuffed to save costs for the next shipment, you might set a lower limit.
maxCargoTypes integer Maximum number of cargo types (0 if unrestricted).
Definition: This field restricts the number of different SKUs (Stock Keeping Units) or cargo types that can be loaded into a single container.

How it works:
  • If maxCargoTypes is set to 0 (or is null/absent), there is no limit. You can mix as many different types of cargo as possible.
  • If set to 1, only one type of cargo is allowed in the container. The algorithm will fill the container with as much of that single cargo type as possible, even if there is still physical volume remaining.
  • If set to 3, the container can hold up to three different types of cargo.
Practical Use Cases:
  • Shipping Single-SKU Shipments: If you are sending a bulk order of a single product, setting this to 1 ensures the container is optimized for that specific item, preventing the algorithm from wasting space by trying to fit a small amount of a different product type.
  • Avoiding Mixing Incompatible Goods: If you have different categories of products (e.g., electronics and food) that should never be mixed in the same container (due to contamination risk, fragility, or regulatory requirements), you would set a separate container profile for each category with maxCargoTypes set to 1.
  • Logistical Simplicity: Sometimes, it's easier for warehouse staff to unload a container that contains only one type of product. Setting this limit simplifies the unpacking process.
price integer Container cost (e.g., 0).
Definition: This field sets the base cost associated with using this specific container type.

How it works:
  • The price is typically a fixed cost, often set to 0 if you are only looking to optimize the physical fit of the cargo (volume/weight efficiency) and are not concerned with the monetary cost of the container itself.
  • If you are using the API for a complete logistics cost calculation, you might set this to the actual market price of hiring or using this container. For example, a standard 20ft dry container might cost $1,500 to hire.
  • This value is used in conjunction with maxPrice to filter out options that exceed a certain budget.
Practical Use Cases:
  • Cost-Agnostic Optimization: In many cases, the primary goal is to fit as much product as possible into the available containers, regardless of the container's cost. In this scenario, setting the price to 0 ensures that the optimization algorithm focuses purely on volumetric efficiency.
  • Budgetary Constraints: If you have a strict budget for your shipping costs, you can set this value to reflect the actual cost of the container. The system will then help you find the most efficient way to pack that specific container within your budget.
  • Comparing Container Types: If you are evaluating different types of containers (e.g., standard vs. refrigerated vs. high-cube), you can use this field to compare the cost effectiveness of each type. For instance, a reefer container is more expensive than a standard one, so its price would be set higher in the system.
  • Cost-breakdown of filled container : If you are set this to the value of cost for a filled container (e.g., 1500 for a standard 20ft dry container), the system will calculate the cost per unit of cargo based on the volume and weight of the cargo.
maxPrice integer Maximum allowable cost (e.g., 0).
Definition: This field sets the maximum allowable cost for using this specific container type.

How it works:
  • The maxPrice is a hard constraint. If the calculated cost of using this container exceeds this value, it will be excluded from the results.
  • The cost is calculated based on the volume and weight of the cargo, and the price per unit of cargo.
  • This value is used in conjunction with price to filter out options that exceed a certain budget.
Example:
  • If you set price to 0 and maxPrice to 0, the system will calculate the cost of using the container based on the volume and weight of the cargo, and the price per unit of cargo.

Advanced

Parameter Type Description
vehicleType string Vehicle transportation category. [See VehicleTypeEnum]
palletType string Pallet physical construction layout. [See PalletTypeEnum]
cartonType string Carton packaging closure specification. [See CartonTypeEnum]
palletThickness integer Pallet thickness in cm (e.g., 0).
color integer Numeric color code for visualization (e.g., 65535).
Definition: This field sets the numeric color code for the empty container visualization.

How it works:
  • The color is a 16-bit integer that represents the color of the empty container.
  • The color is used to visualize the empty container in the 3D visualization of the container loading layout.
Example:
  • If you set color to 65535, the empty container will be displayed in red color.
colorHexaCode string Hex color code for visualization (e.g., "FF0000").
Definition: This field sets the hexadecimal color code for the empty container visualization.

How it works:
  • The colorHexaCode is a 6-digit hexadecimal color code that represents the color of the empty container.
  • The color is used to visualize the empty container in the 3D visualization of the container loading layout.
Example:
  • If you set colorHexaCode to FF0000, the empty container will be displayed in red color.
colorKnownName string Human-readable color name (empty if not specified).
Definition: This field sets the human-readable color name for the pallet visualization.

How it works:
  • The colorKnownName is a string that represents the color of the pallet.
  • The color is used to visualize the pallet in the 3D visualization of the pallet.
Example:
  • If you set colorKnownName to Red, the pallet will be displayed in red color.
palletOverhang boolean Whether pallet overhang is allowed (e.g., false).
Definition: This field sets whether pallet overhang is allowed.

How it works:
  • The palletOverhang is a boolean value that represents whether pallet overhang is allowed.
  • If palletOverhang is set to true, the pallet will be displayed with overhang.
  • If palletOverhang is set to false, the pallet will be displayed without overhang.
Example:
  • If you set palletOverhang to true, the pallet will be displayed with overhang.
palletOverhangLength integer Overhang length in cm (e.g., 0).
Definition: This field sets the overhang length of the pallet.

How it works:
  • The palletOverhangLength is an integer that represents the overhang length of the pallet in cm.
  • The overhang length is used to visualize the pallet in the 3D visualization of the pallet.
Example:
  • If you set palletOverhangLength to 10, the pallet will be filled with overhang length of 10 cm.
palletOverhangWidth integer Overhang width in cm (e.g., 0).
Definition: This field sets the overhang width of the pallet.

How it works:
  • The palletOverhangWidth is an integer that represents the overhang width of the pallet in cm.
  • The overhang width is used to visualize the pallet in the 3D visualization of the pallet.
Example:
  • If you set palletOverhangWidth to 10, the pallet will be filled with overhang width of 10 cm.
palletUnderhang boolean Whether pallet underhang is allowed (e.g., false).
Definition: This field sets whether pallet underhang is allowed.

How it works:
  • The palletUnderhang is a boolean value that represents whether pallet underhang is allowed.
  • If palletUnderhang is set to true, the pallet will be filled with underhang.
  • If palletUnderhang is set to false, the pallet will be filled without underhang.
Example:
  • If you set palletUnderhang to true, the pallet will be filled with underhang.
palletUnderhangLength integer Underhang length in cm (e.g., 0).
Definition: This field sets the underhang length of the pallet.

How it works:
  • The palletUnderhangLength is an integer that represents the underhang length of the pallet in cm.
  • The underhang length is used to visualize the pallet in the 3D visualization of the pallet.
Example:
  • If you set palletUnderhangLength to 10, the pallet will be filled with underhang length of 10 cm.
palletUnderhangWidth integer Underhang width in cm (e.g., 0).
Definition: This field sets the underhang width of the pallet.

How it works:
  • The palletUnderhangWidth is an integer that represents the underhang width of the pallet in cm.
  • The underhang width is used to visualize the pallet in the 3D visualization of the pallet.
Example:
  • If you set palletUnderhangWidth to 10, the pallet will be filled with underhang width of 10 cm.
zones null/array Zoning information (null if not used). Array of zone objects with position, size, maxWeight.
Sample EmptyContainer JSON 

{
  "containerType": "Truck",
  "name": "Standard Truck",
  "length": 20,
  "width": 8,
  "height": 8,
  "maxWeight": 1000
}

Rules Object

The Rules object specifies calculation rules for load building, controlling how the engine optimizes and constrains the load.

Basic

Parameter Type Description
calculationType string Sets or gets the calculation type (e.g., "MixLoad", "UnitLoad", "SetLoad","MultipleSetLoad") to be applied to build the load. The default setting is MixLoad. . Required.

Practical Case: If you are shipping an air-conditioner system comprising 1 Indoor Unit and 1 Outdoor Unit as a 'set', use "SetLoad" or "MultipleSetLoad". The engine will maximize the number of complete sets in the container while strictly maintaining the required 1:1 set ratio of components. [See CalculationTypeEnum]
algorithmType string The underlying optimizer strategy. "Basic" (Max Volume First) is recommended if the load should be quickly generated. "Optimization" algorithm allows deeper search levels.

Practical Case: If you are loading large pallet loads into a shipping container, use "Optimization" with optimizationLevel=5 to utilize space most effectively, as level 5 is specifically tuned for large cargo types. [See AlgorithmTypeEnum]
fillDirection string Engine placement flow trajectory within the container space. Indicates which direction is used while loading.

Practical Case: When filling a pallet, 'Bottom to top' is highly recommended. It places cargoes flat on the ground and then builds upwards in a spiral shape, ensuring a more stable unitload than building a vertical wall front-to-back. [See FillDirectionEnum]
optimizationLevel integer Level of optimization effort: 1 (fast) to 4 (thorough).
isWeightLimited boolean Enforce container weight limits. When true, the engine fills available space as much as possible without the total weight exceeding the `maxWeight` of the empty container (including the empty container tare weight).
isPriceLimited boolean Enforce price limits if used.
isSpreadIdenticalCargoAllowed boolean Same cargoes allowed to be separated. When this rule is activated, CubeMaster will divide the identical cargoes in different spaces for higher space utilization.

Practical Case: The combination of not using this option and not using "Use sequence for loading order" can be interpreted as "identical cargoes are not separated while being placed together in a certain loading order," allowing CubeMaster to automatically decide the best sequences of placements for better volume utilization.
isEmptySpaceMerged boolean Merge empty spaces in visualization.
isSequenceUsed boolean Use sequence for loading order.
Definition: This field sets whether the loading sequence is used.

How it works:
  • The isSequenceUsed is a boolean value that represents whether the loading sequence is used.
  • If isSequenceUsed is set to true, the engine will use the loading sequence to load the cargoes.
  • If isSequenceUsed is set to false, the engine will not use the loading sequence to load the cargoes.
isUnitloadFirst boolean Unit loads filled as many as possible. When this rule is activated, CubeMaster generates containers or pallets filled with single types of cargoes as much as possible, and then the remaining quantities are placed together in the next containers or pallets. This rule utilizes the Unitload parameters of each individual cargo component.
Definition: This field sets whether the unit loads are filled first.

How it works:
  • The isUnitloadFirst is a boolean value that represents whether the unit loads are filled first.
  • If isUnitloadFirst is set to true, the engine will fill the unit loads first.
  • If isUnitloadFirst is set to false, the engine will not fill the unit loads first.
isUnitloadsPartialAllowedWhenUnitloadsFirst boolean If true, allows partial unitloads when unitload first.
Definition: This field sets whether the unit loads are partially allowed when unitload first.

How it works:
  • The isUnitloadsPartialAllowedWhenUnitloadsFirst is a boolean value that represents whether the unit loads are partially allowed when unitload first.
  • If isUnitloadsPartialAllowedWhenUnitloadsFirst is set to true, the engine will allow partial unitloads when unitload first.
  • If isUnitloadsPartialAllowedWhenUnitloadsFirst is set to false, the engine will not allow partial unitloads when unitload first.
isUnitloadFilledWithDifferentCargoes boolean If true, allows different cargoes on unitload. Read-only.
bestFitContainersSelectionType string Container selection strategy for optimizing MixLoads across multiple containers.

Practical Case: When "Quantities and Sequences are limited" (`BestfitDisabled`) is chosen, the engine strictly follows the sequence of your available trucks, filling Truck #1 fully before attempting to place anything in Truck #2. If "Empty spaces are minimized" (`BestfitMaxEmptySizeFirst`) is chosen, the engine ignores truck sequence and instead shifts loads between all available trucks to use the fewest possible vehicles overall. [See BestfitContainersSelectionEnum]
bestFitContainersSelectionMaxVolUtilThreshold number Max volume util threshold for best fit.
bestFitContainersSelectionMaxWeightUtilThreshold number Max weight util threshold for best fit.

Stacking

Parameter Type Description
isSafeStackingUsed boolean If true, enforces safe stacking rules like support rate.
Definition: This field sets whether the safe stacking rules are used.

How it works:
  • If isSafeStackingUsed is set to true, the engine will enforce safe stacking rules like support rate.
  • If isSafeStackingUsed is set to false, the engine will not enforce safe stacking rules like support rate.

Practical Case:
  • If you are loading fragile boxes that sag when overhanging a pallet gap, setting isSafeStackingUsed to true and minSupportRate to 0.9 will enforce that 90% of the box's footprint must rest on solid surfaces below.
minSupportRate number Minimum support rate for safe stacking. Specifies what percentage of a cargo's base must be physically supported by the items beneath it.

Practical Case: If loading fragile boxes that sag when overhanging a pallet gap, setting minSupportRate=0.9 enforces that 90% of the box's footprint must rest on solid surfaces below.
maxDepthToSupportForSafeStacking number Max depth to consider for support in safe stacking.
Definition: This field sets the maximum depth to consider for support in safe stacking.

How it works:
  • If maxDepthToSupportForSafeStacking is set to n, the engine will consider the bottom n mm of a cargo for support calculations.
Practical Case:
  • If you are loading boxes that sag when overhanging a pallet gap, setting maxDepthToSupportForSafeStacking to 100 will enforce that the bottom 100 mm of the box must be supported.
minWeightDifferencePercentageForStackingTwoCargoes number Min weight difference % for stacking two different cargoes.
Definition: This field sets the minimum weight difference percentage for stacking two different cargoes.

How it works:
  • If minWeightDifferencePercentageForStackingTwoCargoes is set to n, the engine will only allow stacking two different cargoes if their weights differ by at least n percent.
stackingRule string Vertical placement and structural stacking constraints. [See StackingRuleEnum]
groupsStackingRule string Vertical placement constraints resolving separate cargo groups. Unlike individual cargo rules, this has limited specific values: AlwaysNotAllowed (101) or BestFit (100).
stackingMatrix array Matrix for custom stacking rules between cargoes.
maxStackingHeight object Controls maximum stacking height dynamically using specific proportional rules.
Properties:
  • isUsed (boolean): If true, enables the dynamic max stacking height rule.
  • algorithm (string): The algorithm used to determine max height. Values: ProportionalToGroundPlacementWidth, ProportionalToGroundPlacementLength, ProportionalToGroundPlacementHeight.
  • groundPlacementSizeToTriggerLimit (number): The minimum ground placement dimension required to trigger this limitation.
  • proportionalRateToSetMaxStackingHeight (number): The multiplier applied to the chosen algorithm's dimension to calculate the maximum allowable stacking height.

Grouping

Parameter Type Description
isGroupUsed boolean If true, respects `groupName` for keeping items together.
Practical Case: When shipping a multi-part system
(e.g., Cabinets, Sink, Countertop), assign them all `groupName = 'Kitchen123'` and set `isGroupUsed=true`. The engine will physically cluster these items near each other in the truck for easier matching during unloading.
isGroupSequenceUsed boolean If true, respects the sequence of the groups. The smaller sequence number will be loaded first.
Definition: This field sets whether the sequence of the groups is used.

How it works:
  • If isGroupSequenceUsed is set to true, the engine will load the cargoes in the order of the group sequence.
  • If isGroupSequenceUsed is set to false, the engine will not use the sequence of the groups to load the cargoes.
isSameGroupAllowedInDifferentContainers boolean If true, allows splitting groups across containers.
isGroupsToPrefContainers boolean If true, assigns groups to preferred containers.
isSameAlias1TogetherInSameGroup boolean If true, keeps same alias1 in same group.
isSameAlias2TogetherInSameAlias1AndGroup boolean If true, keeps same alias2 within alias1 and group.
isDifferentGroupAllowedOnMultiSetLoad boolean If true, allows different groups in multi-set loads.
Practical Case: Set this to `false` if you are shipping orders for two different retail stores in the same truck and you want a strict physical separator between Store A's products and Store B's products to avoid delivery mix-ups.
isSameGroupDividedToDifferentContainersWhenNotKeptTogether boolean If true, divides groups when not kept together.

Advanced

Parameter Type Description
isCargoSizeConsolidated boolean Consolidate identical sizes. If this is set true, the cargoes of the same dimensions are treated as a single type of cargo, which makes the calculation faster for a shipment with small quantity for large number of cargo types.
Practical Case: If this is set true, the cargoes of the same dimensions are treated as a single type of cargo, which makes the calculation faster for a shipment with small quantity for large number of cargo types. For example, if there are 100 types of cargoes and each type has 10 cargoes, the total number of cargoes is 1000. If isCargoSizeConsolidated is set to true, the calculation will be faster than if isCargoSizeConsolidated is set to false.
isTuned boolean If true, uses tuned parameters for optimization.
maxSearchVolPerncentage number Max search volume percentage for tuning.
maxSearchDepth integer Max search depth for algorithm.
maxRunTimeSeconds integer Max runtime in seconds for calculation.
isMultiContainerTypesEnabled boolean If true, uses multiple container types.
Definition: This field sets whether the algorithm should consider using multiple container types for a single shipment.

How it works:
  • If isMultiContainerTypesEnabled is set to true, the algorithm will attempt to use different types of containers (e.g., a mix of 20ft and 40ft containers) to optimize space utilization and cost.
  • If isMultiContainerTypesEnabled is set to false, the algorithm will use only the first container type specified in the request.
Practical Case: If you are shipping a mixed load of heavy machinery and lighter goods, using multiple container types might be more efficient. For instance, the heavy machinery could be loaded into 20ft containers, while the lighter goods could be loaded into 40ft containers, potentially reducing overall shipping costs. Conversely, if all your cargo fits comfortably in a single container type, setting this to false can simplify the logistics.

Note: This setting is only applicable when there are multiple container types available in the `containers` array.
maxFillQtyPerContainer integer Max fill quantity per container.
Definition: This field sets the maximum number of cargoes to be placed in a single container.

How it works:
  • If maxFillQtyPerContainer is set to a positive integer (e.g., 5), the algorithm will attempt to place at most 5 cargoes in each container.
  • If maxFillQtyPerContainer is set to 0, there is no limit on the number of cargoes per container (the algorithm will fill containers as much as possible based on other constraints).
Practical Case: If you are shipping delicate electronic equipment, you might want to limit the number of items per container to prevent damage from shifting or excessive weight. Setting maxFillQtyPerContainer to a lower value ensures that each container is not overloaded and provides extra cushioning space. Conversely, for robust, stackable items like canned goods, you might set this to 0 to maximize container space utilization.

isCargoCostComputedFromShipCost boolean If true, computes cargo cost from shipping cost. Read-only.
Definition: This field determines whether the cost of each cargo is calculated based on the cost of the filled container in which it is placed.

How it works:
  • If isCargoCostComputedFromShipCost is set to true, the cost of each cargo will be computed based on the cost of the filled container in which it is placed.
  • If isCargoCostComputedFromShipCost is set to false, the cost of each cargo will be computed based on the cost of the cargo itself (if provided).
Practical Case: If you are shipping a mixed load of heavy machinery and lighter goods, using multiple container types might be more efficient. For instance, the heavy machinery could be loaded into 20ft containers, while the lighter goods could be loaded into 40ft containers, potentially reducing overall shipping costs. Conversely, if all your cargo fits comfortably in a single container type, setting this to false can simplify the logistics.

isIdenticalCargoStayInOneContainerWhenNotSpread boolean If true, keeps identical cargo in one container when not spread. Read-only.
Definition: This field determines whether identical cargoes should be kept together in the same container when not explicitly spread across multiple containers.

How it works:
  • If isIdenticalCargoStayInOneContainerWhenNotSpread is set to true, the algorithm will attempt to place all identical cargoes in the same container, unless they are explicitly spread across multiple containers.
  • If isIdenticalCargoStayInOneContainerWhenNotSpread is set to false, the algorithm may spread identical cargoes across multiple containers, even if they could fit in a single container.
Example: If you are shipping 100 units of Product A and 50 units of Product B, and you set isIdenticalCargoStayInOneContainerWhenNotSpread to true, the algorithm will attempt to place all 100 units of Product A in the same container, and all 50 units of Product B in another container. If you set this to false, the algorithm may split the 100 units of Product A across multiple containers, even if they could all fit in a single container.
isSideSpaceOfCargoFilledWithSameCargo boolean If true, fills side spaces with same cargo. Read-only.
Definition: This field determines whether side spaces in containers should be filled with the same type of cargo.

How it works:
  • If isSideSpaceOfCargoFilledWithSameCargo is set to true, the algorithm will attempt to fill side spaces in containers with the same type of cargo that is already placed in the container.
  • If isSideSpaceOfCargoFilledWithSameCargo is set to false, the algorithm may fill side spaces with different types of cargoes, even if the same type of cargo is available.
Practical Case: If you are shipping a mixed load of heavy machinery and lighter goods, using multiple container types might be more efficient. For instance, the heavy machinery could be loaded into 20ft containers, while the lighter goods could be loaded into 40ft containers, potentially reducing overall shipping costs. Conversely, if all your cargo fits comfortably in a single container type, setting this to false can simplify the logistics.

isCargoSequenceUsedInOppositeOrder boolean If true, uses sequence in opposite order. Read-only.
isBottomOrientationRespected boolean If true, respects bottom orientation. Read-only.
isEasyLoadUsed boolean If true, uses easy load mode. Read-only.
maxCargoTypesPerContainer integer Max cargo types per container. Read-only.
Definition: This field sets the maximum number of cargo types to be placed in a single container.

How it works:
  • If maxCargoTypesPerContainer is set to a positive integer (e.g., 5), the algorithm will attempt to place at most 5 different types of cargoes in each container.
  • If maxCargoTypesPerContainer is set to 0, there is no limit on the number of cargo types per container (the algorithm will fill containers as much as possible based on other constraints).
Practical Case: If you are shipping a mixed load of heavy machinery and lighter goods, using multiple container types might be more efficient. For instance, the heavy machinery could be loaded into 20ft containers, while the lighter goods could be loaded into 40ft containers, potentially reducing overall shipping costs. Conversely, if all your cargo fits comfortably in a single container type, setting this to false can simplify the logistics.

maxPlacementSize number Max size of cargoes that can be placed at the same time in a filled container that is in UOM units. This value is set to 0 by default. It is max reachable size of loading devices or humans to place items into a filled container. User can override this value to set a custom max reachable size for loading devices or humans to place items into a filled container. For example, if the user knows that the max reachable size of loading devices or humans to place items into a filled container is 100 mm, then the user can set this value to 100.
isCustomRuleUsedForSolutionsNames boolean If true, uses custom naming for solutions. Read-only.
prefixOfSolutionsNames string Prefix for solution names. Nullable, read-only.
suffixOfSolutionsNames string Suffix for solution names. Nullable, read-only.
sequenceStartingNumberOfSolutionsNames number Starting number for sequence in names. Nullable, read-only.
sequenceLengthOfSolutionsNames number Length of sequence in names. Nullable, read-only.

Palletizing

Parameter Type Description
isPalletized boolean If true, palletizes cargo.
Practical Case: If you receive an order of 200 loose cartons but your warehouse ships them on standard US pallets, set `isPalletized=true` and provide the pallet details. The engine will first build optimal pallets, then load those structured pallets into the target truck instead of loose boxes.
palletizing object Palletizing rules for multiple cargoes {...}.
palletizing.isUsed boolean If true, palletizes cargo.
palletizing.isDifferentGroupsAllowedInSamePallet boolean If true, allows different groups on a pallet.
palletizing.minHeightOfPallets number The height the pallets need to be taller than.
palletizing.palletizingAlgorithm string Algorithm to use for building pallets - "UnitloadsDevelopedInAdvance", "UnitloadsDevelopedDinamically".
MixPallet object Empty container for mixed pallets {...}.

Balancing

Parameter Type Description
isBalanceAppliedToAllSolutions boolean If true, balancing mainly increases the overall load efficiency across all containers by filling less-loaded containers more fully or cancelling poorly utilized containers.
isBalanceAppliedToLastSolution boolean If true, applies balance only to last solution.
isBalanceReplacedWithSmallerSizes boolean If true, replaces with smaller sizes for balance.
isBalancePoorUtlizationUnloaded boolean If true, unloads poor utilization for balance.
maxUtilizationForBalanceUnload number Max utilization threshold for unload in balance.
isBalanceSpreadLoadBottom boolean If true, spreads load at bottom for balance.
isBalanceFillWithOptionalCargoes boolean If true, fills with optional cargoes for balance.
optionalCargoesFillingAction string Filling behavior for optional cargo elements during mass balancing. [See OptionalCargoesFillingActionEnum]
isBalanceFillWithAdditionalAmountofExstingCargoes boolean If true, fills with additional existing cargoes for balance.
Sample Rules JSON 
{
  "calculationType": "MixLoad",
  "algorithmType": "Optimization",
  "isWeightLimited": true
}

Response Object

The Response object is the top-level structure returned by the POST /loads endpoint when status is "succeed". It includes overall status, aggregates, and detailed filled containers. If validation or calculation fails, calculationError will contain details instead of filledContainers.

Basic

Parameter Type Description
status string Transaction state indicating success or failure reasons. [See StatusEnum]
message string Additional message, e.g., "OK".
calculationError integer/string If failed, returns the specific error code or name. Null/NoErrors on success. [See CalculationErrorEnum]

Load Summary

Parameter Type Description
loadSummary object Aggregate totals for the entire job across all containers.
loadSummary.cargoesLoaded integer Total cargo units loaded across all containers.
loadSummary.piecesLoaded integer Total pieces loaded.
loadSummary.cargoesLeft integer Cargo units not loaded.
loadSummary.piecesLeft integer Pieces not loaded.
loadSummary.unitloadsLoaded integer Total unitloads loaded.
loadSummary.weightAdded number Total weight added across all containers.
loadSummary.volumeUtilization number Average volume utilization %.
loadSummary.weightUtilization number Average weight utilization %.

Filled Containers

Parameter Type Description
filledContainers array The core results: array of FilledContainer objects, each representing one loaded truck, sea container, or pallet.

Document

Parameter Type Description
document object Metadata about the saved load (if loadSaved=true).
document.title string The load title.
document.isShared boolean If the load is shared company-wide.
document.isAutoSaved boolean If auto-saved.
document.calculationTimeInSeconds integer Time taken for calculation.
document.processId string Process ID for async tracking.
document.createdBy string User email who created it.
document.createdAt string Creation timestamp (ISO).
document.updatedAt string Update timestamp (ISO).
document.containerType string Type of containers used.
document.calculationType string The calculationType from rules.
Sample Response JSON (Success) 

    {
    "status": "succeed",
    "message": "Engine created. 2 cargoes. 1 empty containers. Calculation started. Calculation ended. The load built successfully. The load saved to the cloud database.",
    "calculationError": "NoErrors",
    "document": {
    "title": "New Truck Load With Palletized",
    "description": "Hello Web API",
    "isShared": true,
    "isAutoSaved": true,
    "isPending": false,
    "calculationTimeInSeconds": 0.2532878,
    "processId": "xotZHq5whdu",
    "batchId": "",
    "createdBy": "CHANG@LOGEN.CO.KR",
    "createdAt": "2026-03-07T02:33:25.0989188+09:00",
    "updatedAt": "0001-01-01T00:00:00",
    "containerType": "SeaVan",
    "calculationType": "MixLoad"
    },
    "loadSummary": {
    "cargoesLoaded": 41,
    "piecesLoaded": 330,
    "cargoesLeft": 0,
    "piecesLeft": 0,
    "unitloadsLoaded": 11,
    "volumeLoaded": 4182162.7125,
    "weightLoaded": 17278.500000000004,
    "priceLoaded": 0,
    "containersLoaded": 1,
    "containersLeft": 0
    },
    "filledContainers": [
    {
    "name": "#1 53FT-Intermodal",
    "sequence": 1,
    "loadSummary": {
    "cargoesLoaded": 41,
    "piecesLoaded": 330,
    "unitloadsLoaded": 11,
    "volumeLoaded": 4182162.7125,
    "volumeUtilization": 63.90405768102389,
    "vollumeUtilizationToLoadHeight": 65.14550984986086,
    "floorLoaded": 50030.625,
    "floorUtilization": 81.03437803692906,
    "weightLoaded": 17278.500000000004,
    "weightTotal": 17278.500000000004,
    "weightUtilization": 0,
    "dimWeight": 39424.33734939759,
    "priceLoaded": 0,
    "pricetUtilization": 0,
    "cargoesPerLayer": 1,
    "layersPerUnitload": 0
    },
    "actualSize": {
    "length": 630,
    "width": 98,
    "height": 106
    },
    "loadSize": {
    "length": 554.68,
    "width": 96,
    "height": 103.98
    },
    "cog": {
    "length": 0,
    "width": 0,
    "height": 0
    },
    "emptyContainer": {
    "containerType": "SeaVan",
    "vehicleType": "Dry",
    "palletType": "Wood2WaysDoube",
    "cartonType": "Tuck",
    "qty": 0,
    "length": 630,
    "width": 98,
    "height": 106,
    "emptyWeight": 0,
    "maxLength": 0,
    "maxWidth": 0,
    "maxHeight": 106,
    "maxWeight": 0,
    "palletThickness": 0,
    "maxVolPercent": 0,
    "name": "53FT-Intermodal",
    "description": "",
    "priority": 0,
    "maxCargoTypes": 0,
    "color": 8651384,
    "colorHexaCode": "",
    "colorKnownName": "",
    "palletOverhang": false,
    "palletOverhangLength": 0,
    "palletOverhangWidth": 0,
    "palletUnderhang": false,
    "palletUnderhangLength": 0,
    "palletUnderhangWidth": 0,
    "price": 0,
    "maxPrice": 0,
    "zones": null,
    "vehicleDropDeckRearSize": null,
    "vehicleDropDeckFrontSize": null
    },
    "graphics": {
    "images": {
    "path3DDiagram": "https://api.cubemaster.net/Pictures/529551e5_76c6_4281_85c4_627d846a958b.PNG",
    "path2DBottom": "https://api.cubemaster.net/Pictures/5821e62b_e522_45d5_be26_7e318f8e7c94.PNG",
    "path2DTop": "https://api.cubemaster.net/Pictures/f75f0a0b_d90d_43b9_9a5f_74e8df21bd91.PNG",
    "path2DLeft": "https://api.cubemaster.net/Pictures/888d9664_41ee_418a_a5dd_d589d56f5928.PNG",
    "path2DRight": "https://api.cubemaster.net/Pictures/18eb9886_b65a_4566_9d9a_8f368e751c34.PNG",
    "path2DRear": "https://api.cubemaster.net/Pictures/8b9b201c_dca5_4503_87d6_b697bf9ecd5b.PNG",
    "path2DFront": "https://api.cubemaster.net/Pictures/9d501d85_a65b_40b9_95f4_f41c51b5972a.PNG",
    "pathComposite": "https://api.cubemaster.net/Pictures/03a2c13c_9038_496c_9459_74411dda5e85.PNG",
    "path3DDiagramMeasured": "https://api.cubemaster.net/Pictures/db6018c8_2671_4c23_b6a6_9f8ca49afad9.PNG",
    "path3DDiagramWeight": "https://api.cubemaster.net/Pictures/bdc1ffb6_b013_4f99_8980_22ce370b0432.PNG"
    }
    },
    "spaces": [],
    "manifest": [
    {
    "sequence": 1,
    "cargo": {
    "style": "Shipcase",
    "name": "ITEM003",
    "description": "",
    "length": 17.31,
    "width": 19.5,
    "diameter": 0,
    "height": 15.67,
    "weight": 5.45,
    "qty": 300,
    "pieceInside": 0,
    "orderPieces": 0,
    "setRatio": 0,
    "sequence": 0,
    "price": 0,
    "alias": "",
    "alias2": "",
    "groupName": "",
    "property1": "",
    "property2": "",
    "property3": "",
    "property4": "",
    "property5": "",
    "property6": "",
    "property7": "",
    "property8": "",
    "property9": "",
    "property10": "",
    "unitloadTopPattern": "BestFit",
    "unitloadBottomPattern": "BestFit",
    "unitloadLayersQtyRotated": 0,
    "unitloadTopFlat": false,
    "overhangAllowed": false,
    "overhangLength": 0,
    "overhangWidth": 0,
    "orientationsAllowed": "OrientationsAll",
    "isPalletized": true,
    "palletizing": {
    "pallet": {
    "containerType": "Pallet",
    "vehicleType": "Dry",
    "palletType": "Wood2WaysDoube",
    "cartonType": "Tuck",
    "qty": 0,
    "length": 48,
    "width": 40,
    "height": 0,
    "emptyWeight": 0,
    "maxLength": 0,
    "maxWidth": 0,
    "maxHeight": 89,
    "maxWeight": 0,
    "palletThickness": 3,
    "maxVolPercent": 0,
    "name": "GMA",
    "description": "",
    "priority": 0,
    "maxCargoTypes": 0,
    "color": 3731808,
    "colorHexaCode": "",
    "colorKnownName": "",
    "palletOverhang": false,
    "palletOverhangLength": 0,
    "palletOverhangWidth": 0,
    "palletUnderhang": false,
    "palletUnderhangLength": 0,
    "palletUnderhangWidth": 0,
    "price": 0,
    "maxPrice": 0,
    "zones": null,
    "vehicleDropDeckRearSize": null,
    "vehicleDropDeckFrontSize": null
    },
    "flatPalletTop": false,
    "partialPalletsAllowed": true,
    "remainQtyToMixPallet": false,
    "remainQtyToVehicle": false,
    "fixedCargoCountOnPallet": 0,
    "orientationsOnVehicle": "Orientations12",
    "patternOnVehicle": "BestFit",
    "maxLayersOnVehicle": 0,
    "floorStackType": "BestFit",
    "floorStackSupportsOthers": true
    },
    "maxLayersOnOrientation1": 0,
    "maxLayersOnOrientation2": 0,
    "maxLayersOnOrientation3": 0,
    "maxLayersOnOrientation4": 0,
    "maxLayersOnOrientation5": 0,
    "maxLayersOnOrientation6": 0,
    "turnAllowedOnFloor": true,
    "orientationPriority": null,
    "maxLayersAllowedOverDifferentCargoes": false,
    "stackValue": 0,
    "stackCode": "",
    "maxSupportingWeight": 0,
    "floorStackType": "BestFit",
    "floorStackSupportsOthers": true,
    "color": 55295,
    "colorHexaCode": "#FFD700",
    "colorKnownName": "Gold",
    "isOptional": false,
    "unitload": null,
    "palletizedUnitloadsQty": 0,
    "bulgeSize": {
    "length": 0,
    "width": 0,
    "height": 0
    },
    "emptyContainersFavorite": [],
    "faceOpen": "NeitherSide",
    "departureTime": "",
    "sharingCode": ""
    },
    "cargoesLoaded": 300,
    "piecesLoaded": 300,
    "unitloadsLoaded": 11,
    "volumeUtilization": 0.37942068591861366,
    "weightUtilization": 0.09462626964146191,
    "priceUtilization": 0
    },
    {
    "sequence": 2,
    "cargo": {
    "style": "Shipcase",
    "name": "ITEM002",
    "description": "",
    "length": 27.31,
    "width": 37.5,
    "diameter": 0,
    "height": 76.67,
    "weight": 521.45,
    "qty": 30,
    "pieceInside": 0,
    "orderPieces": 0,
    "setRatio": 0,
    "sequence": 0,
    "price": 0,
    "alias": "",
    "alias2": "",
    "groupName": "",
    "property1": "",
    "property2": "",
    "property3": "",
    "property4": "",
    "property5": "",
    "property6": "",
    "property7": "",
    "property8": "",
    "property9": "",
    "property10": "",
    "unitloadTopPattern": "BestFit",
    "unitloadBottomPattern": "BestFit",
    "unitloadLayersQtyRotated": 0,
    "unitloadTopFlat": false,
    "overhangAllowed": false,
    "overhangLength": 0,
    "overhangWidth": 0,
    "orientationsAllowed": "OrientationsAll",
    "isPalletized": false,
    "palletizing": {
    "pallet": {
    "containerType": "Pallet",
    "vehicleType": "Dry",
    "palletType": "Wood2WaysDoube",
    "cartonType": "Tuck",
    "qty": 1,
    "length": 0,
    "width": 0,
    "height": 0,
    "emptyWeight": 0,
    "maxLength": 0,
    "maxWidth": 0,
    "maxHeight": 0,
    "maxWeight": 0,
    "palletThickness": 0,
    "maxVolPercent": 0,
    "name": "",
    "description": "",
    "priority": 1,
    "maxCargoTypes": 0,
    "color": 7850472,
    "colorHexaCode": "",
    "colorKnownName": "",
    "palletOverhang": false,
    "palletOverhangLength": 0,
    "palletOverhangWidth": 0,
    "palletUnderhang": false,
    "palletUnderhangLength": 0,
    "palletUnderhangWidth": 0,
    "price": 0,
    "maxPrice": 0,
    "zones": null,
    "vehicleDropDeckRearSize": null,
    "vehicleDropDeckFrontSize": null
    },
    "flatPalletTop": true,
    "partialPalletsAllowed": true,
    "remainQtyToMixPallet": true,
    "remainQtyToVehicle": true,
    "fixedCargoCountOnPallet": 0,
    "orientationsOnVehicle": "Orientations12",
    "patternOnVehicle": "BestFit",
    "maxLayersOnVehicle": 0,
    "floorStackType": "BestFit",
    "floorStackSupportsOthers": true
    },
    "maxLayersOnOrientation1": 0,
    "maxLayersOnOrientation2": 0,
    "maxLayersOnOrientation3": 0,
    "maxLayersOnOrientation4": 0,
    "maxLayersOnOrientation5": 0,
    "maxLayersOnOrientation6": 0,
    "turnAllowedOnFloor": true,
    "orientationPriority": null,
    "maxLayersAllowedOverDifferentCargoes": false,
    "stackValue": 0,
    "stackCode": "",
    "maxSupportingWeight": 0,
    "floorStackType": "BestFit",
    "floorStackSupportsOthers": true,
    "color": 65408,
    "colorHexaCode": "#80FF00",
    "colorKnownName": "#80FF00",
    "isOptional": false,
    "unitload": null,
    "palletizedUnitloadsQty": 0,
    "bulgeSize": {
    "length": 0,
    "width": 0,
    "height": 0
    },
    "emptyContainersFavorite": [],
    "faceOpen": "NeitherSide",
    "departureTime": "",
    "sharingCode": ""
    },
    "cargoesLoaded": 30,
    "piecesLoaded": 30,
    "unitloadsLoaded": 0,
    "volumeUtilization": 0.5632468352939533,
    "weightUtilization": 0.905373730358538,
    "priceUtilization": 0
    }
    ],
    "cargoGroups": null,
    "reportLinks": {
    "overview": "https://cubemaster.net/source/report/openlink.asp?id=3a494d3d-3f86-4aec-85d7-8c0485c4f0d6"
    },
    "uom": "UnitEnglish"
    }
    ],
    "reportLinks": {
    "pdfLinks": {
    "loadSummary": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=0&",
    "solutions": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=1&",
    "loadingInstruction": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=2&",
    "loadingDiagram": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=3&",
    "loadingRequest": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=4&",
    "placements": "https://cubemaster.net/source/report/openlink.asp?id=140ee8ff-712d-4056-9e29-bf7496fef61a&to=PDF&r=5&"
    },
    "loadSummary": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=0&",
    "solutions": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=1&",
    "loadingInstruction": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=2&",
    "loadingDiagram": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=3&",
    "loadingRequest": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=4&",
    "placements": "https://cubemaster.net/source/report/openlink.asp?id=2c93cdd2-ffca-4bf1-9185-b0c36599006b&r=5&"
    },
    "shipping": null
    }

FilledContainer Object

Represents a container filled with cargo after load calculation. This schema is part of the API response, providing summary, utilization metrics, graphical representations, and precise placement details. It mirrors the "Results" section in the CubeMaster user interface, where results are displayed in various views like Tree View, List View, Tile View, and Report View for analysis.

Basic

Parameter Type Description
name string Identifier for the filled container, often including group or date information (e.g., "002(2025-02-05)"). Corresponds to solution names in the results list.
sequence integer Order or priority of the container in the load results (e.g., 2).
actualSize object Physical dimensions of the container {length, width, height} in UOM units.
loadSize object Dimensions of the loaded cargo footprint {length, width, height}.
emptyContainer object The original empty container details used for this filled container.
uom string Unit of measure used for dimensions and weights (e.g., "UnitMetric"). [See UOMEnum]

Load Summary

Parameter Type Description
loadSummary object Overall metrics summarizing the load efficiency and contents. This corresponds to the summary at the top of the Results section in the user interface.
loadSummary.cargoesLoaded integer Total number of cargo units loaded into this container.
loadSummary.piecesLoaded integer Total number of individual pieces loaded (qty * pieceInside across all cargoes).
loadSummary.unitloadsLoaded integer Number of unitloads (pallets) loaded.
loadSummary.volumeLoaded number Total volume occupied by loaded cargo in cubic units.
loadSummary.volumeUtilization number Percentage of container volume utilized (e.g., 81.44).
loadSummary.floorUtilization number Percentage of floor space utilized (e.g., 84.11).
loadSummary.weightLoaded number Total weight of loaded cargo.
loadSummary.weightUtilization number Percentage of max weight utilized.
loadSummary.dimWeight number Dimensional weight calculation for shipping rates.
loadSummary.dimWeightFactor number Factor used for dim weight (e.g., 194 for air freight).
loadSummary.priceLoaded number Total price of loaded cargo.
loadSummary.priceUtilization number Percentage of max price utilized.
loadSummary.cargoesPerLayer integer Average number of cargoes per layer.
loadSummary.layersLoaded integer Total number of layers stacked.

Graphics

Parameter Type Description
graphics object Visual representations of the load, corresponding to the graphics engine output in the user interface (e.g., 3D and 2D views in Results). This may not be available in certain pricing model.
graphics.images object URLs to various diagram views.
graphics.images.path3DDiagram string URL to 3D diagram of the load.
graphics.images.path2DTop string URL to 2D top view.
graphics.images.path2DSide string URL to 2D side view.
graphics.images.path2DFront string URL to 2D front view.

Spaces

Parameter Type Description
spaces array Array of space objects representing placement zones or build steps within the container, included if spacesCreated=true. This details how cargo is arranged, similar to the detailed breakdown in the Report View.
spaces[].sequence integer Order of the space in the loading sequence.
spaces[].isEmpty boolean If true, this space is unused/empty.
spaces[].cargoesLoaded integer Number of cargo units in this space.
spaces[].piecesLoaded integer Number of individual pieces in this space.
spaces[].cargo object The Cargo object details for items in this space.
spaces[].arrangement object Layout counts {length: int, width: int, height: int} - how many along each dimension.
spaces[].pos object Position coordinates {length, width, height} of the space start.
Coordinate System: CubeMaster uses a right-handed Cartesian system.
• length: X-axis (Depth of container)
• width: Y-axis (Across the container)
• height: Z-axis (Vertical)
Placements originate from the back-left-floor corner (0,0,0).
spaces[].size object Dimensions of the space {length, width, height}.
spaces[].graphics object Thumbnail images for this space, if thumbnailsCreated=true. This may not be available in certain pricing model.
spaces[].graphics.images.pathThumbnail string URL to thumbnail of the space. This may not be available in certain pricing model.

Placements (Sub of Spaces)

Parameter Type Description
spaces[].placements array Detailed individual cargo placements within the space, included if placementsCreated=true. This provides precise positioning for each item.
spaces[].placements[].sequence integer Order of this placement.
spaces[].placements[].fillDirection integer Orientation used (e.g., 2 which means the cargo was placed in direction #2).
spaces[].placements[].pos object Position {length, width, height} of this placement.
Coordinate System: CubeMaster uses a right-handed Cartesian system.
• length: X-axis (Depth of container)
• width: Y-axis (Across the container)
• height: Z-axis (Vertical)
Placements originate from the back-left-floor corner (0,0,0).
spaces[].placements[].size object Size {length, width, height} of this placement.

Manifest

Parameter Type Description
manifest array Summary per cargo type loaded, similar to the Cargoes section in the Report View, showing loaded quantities and utilizations.
manifest[].sequence integer Order of this cargo in the manifest.
manifest[].cargo object The Cargo object details.
manifest[].cargoesLoaded integer Number of this cargo loaded.
manifest[].piecesLoaded integer Number of pieces of this cargo.
manifest[].unitloadsLoaded integer Number of unitloads for this cargo.
manifest[].volumeUtilization number Volume % for this cargo.
manifest[].weightUtilization number Weight % for this cargo.
manifest[].priceUtilization number Price % for this cargo.

Advanced

Parameter Type Description
cog object Center of gravity {length, width, height}, used for balance checks.
cargoGroups null/array Grouped cargoes if grouping rules were applied.
reportLinks object Links to detailed reports, corresponding to the Report View in the user interface. This may not be available in certain pricing model.
reportLinks.overview string URL to the full load report. This may not be available in certain pricing model.
Sample FilledContainer JSON 

    {
        "name": "Container1",
        "sequence": 1,
        "loadQty": 10,
        "loadVolume": 30.0,
        "netWeight": 500.0,
        "grossWeight": 1500.0,
        "volumeUtilization": 80.0,
        "weightUtilization": 90.0,
        "graphics": {
            "images": [
                "https://api.cubemaster.net/graphics/container1.png"
            ]
        }
    }

Practical Use Cases

Manufacturing Industry

In manufacturing, use the API to optimize loading of auto parts into trucks. For example, load crossmembers and assemblies into intermodal containers to maximize space and minimize damage. Set isPalletized=true for palletizing parts, and use maxSupportingWeight to ensure heavy items are at the bottom.

Logistics and Shipping

For logistics companies, calculate mix loads for sea containers or trucks. Use calculationType="MixLoad" to mix different SKUs, and balanceConfiguration to ensure weight distribution for safe transport. Integrate with TMS systems to automate route planning.

E-Commerce

In e-commerce, optimize carton packing for orders. Use containerType="Carton" and algorithmType="Basic" for fast calculations during checkout. This reduces shipping costs by minimizing package size and number.

Retail and Distribution

For retail, plan pallet loads for warehouse storage. Set palletizing.fixedCargoCountOnPallet to standard quantities, and use maxStackingHeight to comply with safety regulations.

Aerospace and Defense

Optimize ULD loads for air freight. Use containerType="ULD" and isWeightLimited=true to stay under aircraft weight limits. Include zones for fragile items.

Food and Beverage

For perishable goods, use vehicleType="Refrigerated" and allowMix=false to separate items. Use groupName for temperature zones.

Pharmaceuticals

Ensure secure loading with isSafeStackingUsed=true and minSupportRate=0.95 for fragile vials. Use stackingMatrix to define compatibility between items.

Integration Examples for Platforms and Technologies

The API supports integration with various platforms like web, mobile, ERP, cloud, IoT, and technologies including Python, JavaScript, Java, C#, PHP, Ruby, Go.

cURL (Command Line)

cURL Example 
curl -X POST "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish" \
-H "TokenID: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Sample", "cargoes": [{"style": "Shipcase", "name": "Box1", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50}], "emptyContainers": [{"containerType": "Truck", "name": "Truck1", "length": 20, "width": 8, "height": 8, "maxWeight": 1000}], "rules": {"calculationType": "MixLoad"}}'

Python (Requests)

Python Example 
import requests

url = "https://api.cubemaster.net/loads"
params = {"graphicsCreated": True, "UOM": "UnitEnglish"}
headers = {"TokenID": "YOUR_API_KEY", "Content-Type": "application/json"}
data = {
    "title": "Sample",
    "cargoes": [{"style": "Shipcase", "name": "Box1", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck1", "length": 20, "width": 8, "height": 8, "maxWeight": 1000}],
    "rules": {"calculationType": "MixLoad"}
}

response = requests.post(url, params=params, headers=headers, json=data)
print(response.json())

JavaScript (Axios)

JavaScript Example 
const axios = require('axios');

axios.post('https://api.cubemaster.net/loads', {
    title: 'Sample',
    cargoes: [{style: 'Shipcase', name: 'Box1', length: 10, width: 5, height: 3, weight: 20, qty: 50}],
    emptyContainers: [{containerType: 'Truck', name: 'Truck1', length: 20, width: 8, height: 8, maxWeight: 1000}],
    rules: {calculationType: 'MixLoad'}
}, {
    params: {graphicsCreated: true, UOM: 'UnitEnglish'},
    headers: {'TokenID': 'YOUR_API_KEY', 'Content-Type': 'application/json'}
}).then(res => console.log(res.data));

Java (Spring Boot)

Java Example 
import org.springframework.web.client.RestTemplate;

RestTemplate restTemplate = new RestTemplate();
String url = "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish";

Map data = Map.of(
    "title", "Sample",
    "cargoes", List.of(Map.of("style", "Shipcase", "name", "Box1", "length", 10, "width", 5, "height", 3, "weight", 20, "qty", 50)),
    "emptyContainers", List.of(Map.of("containerType", "Truck", "name", "Truck1", "length", 20, "width", 8, "height", 8, "maxWeight", 1000)),
    "rules", Map.of("calculationType", "MixLoad")
);

HttpHeaders headers = new HttpHeaders();
headers.set("TokenID", "YOUR_API_KEY");
headers.setContentType(MediaType.APPLICATION_JSON);

HttpEntity> request = new HttpEntity<>(data, headers);

ResponseEntity response = restTemplate.postForEntity(url, request, String.class);
System.out.println(response.getBody());

C# (.NET)

C# Example 
using System.Net.Http;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("TokenID", "YOUR_API_KEY");

var url = "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish";

var content = new StringContent(@"{
  ""title"": ""Sample"",
  ""cargoes"": [{""style"": ""Shipcase"", ""name"": ""Box1"", ""length"": 10, ""width"": 5, ""height"": 3, ""weight"": 20, ""qty"": 50}],
  ""emptyContainers"": [{""containerType"": ""Truck"", ""name"": ""Truck1"", ""length"": 20, ""width"": 8, ""height"": 8, ""maxWeight"": 1000}],
  ""rules"": {""calculationType"": ""MixLoad""}
}", Encoding.UTF8, "application/json");

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

PHP

PHP Example 
 'Sample',
    'cargoes' => [[
        'style' => 'Shipcase',
        'name' => 'Box1',
        'length' => 10,
        'width' => 5,
        'height' => 3,
        'weight' => 20,
        'qty' => 50
    ]],
    'emptyContainers' => [[
        'containerType' => 'Truck',
        'name' => 'Truck1',
        'length' => 20,
        'width' => 8,
        'height' => 8,
        'maxWeight' => 1000
    ]],
    'rules' => ['calculationType' => 'MixLoad']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'TokenID: YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Ruby

Ruby Example 
require 'net/http'
require 'json'

uri = URI('https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish')

req = Net::HTTP::Post.new(uri)
req['TokenID'] = 'YOUR_API_KEY'
req['Content-Type'] = 'application/json'

data = {
  title: 'Sample',
  cargoes: [{
    style: 'Shipcase',
    name: 'Box1',
    length: 10,
    width: 5,
    height: 3,
    weight: 20,
    qty: 50
  }],
  emptyContainers: [{
    containerType: 'Truck',
    name: 'Truck1',
    length: 20,
    width: 8,
    height: 8,
    maxWeight: 1000
  }],
  rules: {
    calculationType: 'MixLoad'
  }
}

req.body = data.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

puts res.body

Go

Go Example 
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish"

    data := map[string]interface{}{
        "title": "Sample",
        "cargoes": []map[string]interface{}{{
            "style": "Shipcase",
            "name": "Box1",
            "length": 10,
            "width": 5,
            "height": 3,
            "weight": 20,
            "qty": 50,
        }},
        "emptyContainers": []map[string]interface{}{{
            "containerType": "Truck",
            "name": "Truck1",
            "length": 20,
            "width": 8,
            "height": 8,
            "maxWeight": 1000,
        }},
        "rules": map[string]interface{}{
            "calculationType": "MixLoad",
        },
    }

    jsonData, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("TokenID", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

JavaScript (Fetch API)

Fetch API Example 
const url = 'https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish';

const data = {
    title: 'Sample',
    cargoes: [{style: 'Shipcase', name: 'Box1', length: 10, width: 5, height: 3, weight: 20, qty: 50}],
    emptyContainers: [{containerType: 'Truck', name: 'Truck1', length: 20, width: 8, height: 8, maxWeight: 1000}],
    rules: {calculationType: 'MixLoad'}
};

fetch(url, {
    method: 'POST',
    headers: {
        'TokenID': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Swift

Swift Example 
import Foundation

let url = URL(string: "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.addValue("YOUR_API_KEY", forHTTPHeaderField: "TokenID")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

let parameters: [String: Any] = [
    "title": "Sample",
    "cargoes": [
        ["style": "Shipcase", "name": "Box1", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50]
    ],
    "emptyContainers": [
        ["containerType": "Truck", "name": "Truck1", "length": 20, "width": 8, "height": 8, "maxWeight": 1000]
    ],
    "rules": ["calculationType": "MixLoad"]
]

request.httpBody = try? JSONSerialization.data(withJSONObject: parameters, options: [])

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    guard let data = data, error == nil else {
        print(error?.localizedDescription ?? "No data")
        return
    }
    print(String(data: data, encoding: .utf8) ?? "Invalid response data")
}
task.resume()

Kotlin (OkHttp)

Kotlin Example 
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

fun main() {
    val client = OkHttpClient()
    val url = "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish"
    val mediaType = "application/json".toMediaType()
    val json = """{
        "title": "Sample",
        "cargoes": [{"style": "Shipcase", "name": "Box1", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50}],
        "emptyContainers": [{"containerType": "Truck", "name": "Truck1", "length": 20, "width": 8, "height": 8, "maxWeight": 1000}],
        "rules": {"calculationType": "MixLoad"}
    }"""
    
    val body = json.toRequestBody(mediaType)
    val request = Request.Builder()
        .url(url)
        .post(body)
        .addHeader("TokenID", "YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        println(response.body?.string())
    }
}

Rust (reqwest)

Rust Example 
use reqwest::header::{HeaderMap, HeaderValue, CONTENT_TYPE};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://api.cubemaster.net/loads?graphicsCreated=true&UOM=UnitEnglish";
    
    let mut headers = HeaderMap::new();
    headers.insert("TokenID", HeaderValue::from_static("YOUR_API_KEY"));
    headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));

    let data = json!({
        "title": "Sample",
        "cargoes": [{
            "style": "Shipcase", "name": "Box1", 
            "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50
        }],
        "emptyContainers": [{
            "containerType": "Truck", "name": "Truck1", 
            "length": 20, "width": 8, "height": 8, "maxWeight": 1000
        }],
        "rules": { "calculationType": "MixLoad" }
    });

    let client = reqwest::Client::new();
    let res = client.post(url)
        .headers(headers)
        .json(&data)
        .send()
        .await?;

    println!("{}", res.text().await?);
    Ok(())
}

Endpoints: Calculation

POST /loads

Builds a new load and saves it to the loads database. Overwrites a load with the same title.

Query Parameters

Name Type Description Default Required
multiProcessed boolean Set true for asynchronous processing with webhook result delivery. False for immediate results. false false
cargoDetailLoadedFromDatabase boolean If true, cargo details are loaded from the database by name. false false
containerDetailLoadedFromDatabase boolean If true, container details are loaded from the database by name. false false
loadSaved boolean If true, the load is saved to the database. true false
loadShared boolean If true, the load is shared company-wide. true false
userId string Email of the user under whom the load is saved. API credential email false
webhookListenerURLToNewLoad string Webhook URL for asynchronous load results. none false
graphicsCreated boolean If true, generates container graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Width of graphics in pixels. 200 false
graphicsImageDepth integer Depth of graphics in pixels. 200 false
graphicsShowScale boolean If true, includes measurements in graphics. false false
graphicsBackgroundColorRGB integer RGB color for graphics background. 0 false
thumbnailsCreated boolean If true, generates space thumbnails. false false
thumbnailsImageWidth integer Width of thumbnails in pixels. 200 false
thumbnailsImageDepth integer Depth of thumbnails in pixels. 200 false
thumbnailsCreatedInBlackWhite boolean If true, thumbnails are in black and white. false false
spacesCreated boolean If true, includes space details in response. false false
placementsCreated boolean If true, includes placement details in spaces. false false
UOM string Unit of measure: "UnitEnglish", "UnitMetric", "UnitHighMetric". [See UOMEnum] UnitEnglish false
reportLanguage string Language for reports: "ENG", "GER", "SPN", "FRN", "BRZ", "CHN", "JPN", "KOR". ENG false
reportToolbarShown boolean If true, shows report toolbar. false false
Important: Query Parameters vs. JSON Payload
Query parameters must be appended directly to the URL string and must NOT be included inside the JSON request body. The API will ignore query parameters placed in the payload.

✅ Correct (URL Parameters):
POST /loads?UOM=UnitMetric&graphicsCreated=true&placementsCreated=true

❌ Incorrect (Inside JSON Payload):
{ "title": "My Load", "UOM": "UnitMetric", "cargoes": [...] }

Request Body: Load object (see Load Schema).

Response: Response object (see Response Schema).

Endpoints: Database/Master Data

GET /Database/Cargoes/{name}

Retrieves a cargo by name from the cargoes database.

Query Parameters

Name Type Description Default Required
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Response: Cargo object.

DELETE /Database/Cargoes/{name}

Deletes a cargo by name from the cargoes database.

Query Parameters

Name Type Description Default Required
None - - - -
GET /Database/Cargoes

Retrieves all cargoes from the cargoes database.

Query Parameters

Name Type Description Default Required
limit integer Limits the number of cargoes returned. 10 false
createdAt string Filter by creation date. none false
shared boolean If true, returns only shared cargoes. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
POST /Database/Cargoes/Multiple

Inserts multiple cargoes into the cargoes database.

Query Parameters

Name Type Description Default Required
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Request Body: {cargoes: array of Cargo objects}.

PUT /Database/Cargoes/{keyIs}

Updates a cargo (partial updates supported).

Query Parameters

Name Type Description Default Required
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Request Body: Partial Cargo object.

GET /Database/Containers/{type}

Retrieves all containers of a specific type (e.g., Truck, Pallet).

Query Parameters

Name Type Description Default Required
limit integer Limits the number returned. 10 false
createdAt string Filter by creation date. none false
shared boolean If true, returns only shared. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
POST /Database/Containers/{type}

Inserts a container into the containers database.

Query Parameters

Name Type Description Default Required
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Request Body: EmptyContainer object.

GET /Database/Containers/{type}/{name}

Retrieves a container by type and name.

Query Parameters

Name Type Description Default Required
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
DELETE /Database/Containers/{type}/{name}

Deletes a container by type and name.

Query Parameters

Name Type Description Default Required
None - - - -

Endpoints: Archive API

GET /Loads

Retrieves all saved loads from the database.

Query Parameters

Name Type Description Default Required
limit integer Limits the number of loads returned. 10 false
createdAt string Filter by creation date. none false
shared boolean If true, returns only shared loads. false false
graphicsCreated boolean If true, includes graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Width of graphics in pixels. 200 false
graphicsImageDepth integer Depth of graphics in pixels. 200 false
graphicsShowScale boolean If true, includes measurements in graphics. false false
graphicsBackgroundColorRGB integer RGB color for graphics background. 0 false
thumbnailsCreated boolean If true, generates space thumbnails. false false
thumbnailsImageWidth integer Width of thumbnails in pixels. 200 false
thumbnailsImageDepth integer Depth of thumbnails in pixels. 200 false
thumbnailsCreatedInBlackWhite boolean If true, thumbnails are in black and white. false false
spacesCreated boolean If true, includes space details. false false
placementsCreated boolean If true, includes placement details. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
GET /Loads/{userId}

Retrieves all saved loads created by a specific user.

Query Parameters

This endpoint supports the same query parameters as GET /Loads (e.g., limit, createdAt, shared, graphicsCreated, etc.).


GET /Loads/{userId}/{title}

Retrieves loads by user ID and title. The search allows for partial matches on the title.

Query Parameters

Name Type Description Default Required
graphicsCreated boolean If true, includes graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Width of graphics. 200 false
graphicsImageDepth integer Depth of graphics. 200 false
graphicsShowScale boolean Include measurements in graphics. false false
graphicsBackgroundColorRGB integer Background color. 0 false
thumbnailsCreated boolean Generate space thumbnails. false false
thumbnailsImageWidth integer Thumbnail width. 200 false
thumbnailsImageDepth integer Thumbnail depth. 200 false
thumbnailsCreatedInBlackWhite boolean Black and white thumbnails. false false
spacesCreated boolean Include space details. false false
placementsCreated boolean Include placement details. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
DELETE /Loads/{userId}/{title}

Deletes a load by user ID and title.

Query Parameters

Name Type Description Default Required
None - - - -
GET /Loads/{userId}/{title}/{filledContainerSeq}

Retrieves a specific filled container from a load.

Query Parameters

Name Type Description Default Required
graphicsCreated boolean If true, includes graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Width of graphics. 200 false
graphicsImageDepth integer Depth of graphics. 200 false
graphicsShowScale boolean Include measurements. false false
graphicsBackgroundColorRGB integer Background color. 0 false
thumbnailsCreated boolean Generate thumbnails. false false
thumbnailsImageWidth integer Thumbnail width. 200 false
thumbnailsImageDepth integer Thumbnail depth. 200 false
thumbnailsCreatedInBlackWhite boolean Black and white. false false
spacesCreated boolean Include space details. false false
placementsCreated boolean Include placement details. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Endpoints: Edit & Upload API

POST /Edit/Load/{userId}

Builds a load from editing data and saves it. /Edit/Build/{userId} is an alias to this endpoint.

Query Parameters

Name Type Description Default Required
multiProcessed boolean Asynchronous processing. false false
webhookListenerURLToNewLoad string Webhook for async. none false
loadSaved boolean Save the load. true false
loadShared boolean Share the load. true false
graphicsCreated boolean Generate graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Graphics width. 200 false
graphicsImageDepth integer Graphics depth. 200 false
graphicsShowScale boolean Show scale in graphics. false false
graphicsBackgroundColorRGB integer Background color. 0 false
thumbnailsCreated boolean Generate thumbnails. false false
thumbnailsImageWidth integer Thumbnail width. 200 false
thumbnailsImageDepth integer Thumbnail depth. 200 false
thumbnailsCreatedInBlackWhite boolean Black and white thumbnails. false false
spacesCreated boolean Include spaces. false false
placementsCreated boolean Include placements. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false
reportLanguage string Report language. ENG false
reportToolbarShown boolean Show toolbar. false false
GET /Edit/{userId}

Retrieves editing data for a user.

Query Parameters

Name Type Description Default Required
None - - - -
DELETE /Edit/{userId}

Deletes editing data for a user.

Query Parameters

Name Type Description Default Required
None - - - -
GET /Edit/Load/{userId}/{filledContainerSeq}

Retrieves a filled container from editing data.

Query Parameters

Name Type Description Default Required
graphicsCreated boolean Include graphics. This may not be available in certain pricing model. false false
graphicsImageWidth integer Graphics width. 200 false
graphicsImageDepth integer Graphics depth. 200 false
graphicsShowScale boolean Show scale. false false
graphicsBackgroundColorRGB integer Background color. 0 false
thumbnailsCreated boolean Generate thumbnails. false false
thumbnailsImageWidth integer Thumbnail width. 200 false
thumbnailsImageDepth integer Thumbnail depth. 200 false
thumbnailsCreatedInBlackWhite boolean Black and white. false false
spacesCreated boolean Include spaces. false false
placementsCreated boolean Include placements. false false
UOM string Unit of measure. [See UOMEnum] UnitEnglish false

Enumerations

The following enumerations are used to dictate types, calculation logic, and physical behaviors within the CubeMaster engine.

ContainerTypeEnum

Value Description
Carton Standard corrugated or cardboard box packaging.
Pallet A flat transport structure, which supports goods in a stable fashion while being lifted by a forklift or jacking device. Structural foundation of a unit load.
SeaVan Ocean freight container (20ft, 40ft, etc.) used for marine shipping.
Truck A motor vehicle or trailer designed to transport cargo.
AirPallet Aviation ULD (Unit Load Device) or air pallet.

VehicleTypeEnum

Value Description
Dry Box trucks/dry vans with walls and a roof, making an enclosed load space.
OpenTop Container without a solid roof.
FlatRack Flatbed trucks having an entirely flat, level platform body, allowing for quick and easy loading but without load protection.

PalletTypeEnum

Defines the physical construction and handling limits of the pallet.

Value Description
Wood2WaysDoube Wooden pallet, 2-way entry, double-faced.
Wood4Ways Wooden pallet, 4-way entry.
Plastic4Ways Plastic pallet, 4-way entry.
Paper Paper or corrugated pallet.
Steel Steel pallet.
Slipsheet Thin slip sheet base.
Plastic2WaysDoube Plastic pallet, 2-way entry, double-faced.
Plastic2WaysSingle Plastic pallet, 2-way entry, single-faced.

CartonTypeEnum

Defines the closure and geometry style of cartons.

Value Description
Tuck Standard tuck-in flap carton.
TuckWithoutMinorFlap Tuck carton without minor flaps.
RSC Regular Slotted Container (RSC).
RSCClosed Regular Slotted Container (Closed).
HSC Half Slotted Container.
Cube Perfect cube dimension carton.
TrayHalf Half-tray carton style.
ShrinkWrap Shrink wrapped bundle.
BottomOpen Carton open at the bottom.

StyleEnum (Cargo)

Value Description
Shipcase Standard rectangular cargo or box.
Palletload Pre-built unitload representing a fully loaded pallet.
Roll Cylindrical cargo.

OrientationEnum

Defines the 6 possible orthogonal rotations of a rectangular cargo block. These string values define the permitted stacking orientations.

Value Name Geometry (Vertical Height Axis)
1 Basic Upright Base: L x W (Height axis = H)
2 Basic Upright Turned Base: W x L (Height axis = H)
3 Turning Side Base: L x H (Height axis = W)
4 Turning Side Turned Base: H x L (Height axis = W)
5 Turning End Base: W x H (Height axis = L)
6 Turning End Turned Base: H x W (Height axis = L)

Permitted Combinations (Allowed String Values):

Any combination of integers 1 through 6 appended to Orientations (e.g. Orientations145 or Orientations123456) is valid.

PatternEnum

Loading pattern strategies for packing homogenous cargo into a layer or unitload.

Value Description
BestFit Automatically selects the most optimal pattern to maximize utilization.
Pattern1Block Arranges cargoes in a single uniform block orientation. The layer is not rotated.
Pattern2Blocks Divides the layer into two distinct blocks allowing rotation between them.
Pattern3Blocks Divides the layer into three distinct blocks.
Pattern4Blocks Arranges cargoes in a 4-block spiral (pinwheel) pattern towards the center.
MultiSurface Allows multiple unique orientations within the same layer.
PatternVoid Empty pattern or forced gap allocation.

CalculationTypeEnum

Value Description
MixLoad Finds optimal number of containers to fill all cargoes when each cargo has different sizes and quantities to be shipped.
UnitLoad Calculates the full capacities of containers/pallets when filled with one cargo; used to calculate the Hi/Ti of a pallet configuration.
SetLoad Calculates the number of complete products to maximize space utilization when the product consists of multiple cargoes kept in a proportional ratio.
MultipleSetLoad Calculates containers to fill a shipment utilizing multiple destinations and stops.

AlgorithmTypeEnum

Value Description
Optimization Heuristic search trading off time and quality. Evaluates a broader search space for better space utilization, taking longer to compute.
MaxVolumeFirst Basic straightforward approach placing load blocks with max volumes at earlier positions. Fastest response time.

BestfitContainersSelectionEnum

Defines the Goal of Mix Load, dictating how the optimization engine prioritizes multiple empty containers.

Value Goal of Mix Load Equivalent Description
BestfitDisabled Quantities and Sequences are limited Fills empty containers sequentially according to their Priority/Sequence. This is the only mode that strictly complies with the specified 'Qty' limits and 'Seq' ordering of the containers.
BestfitMaxEmptySizeFirst Empty spaces are minimized This goal makes CubeMaster fill the largest empty containers first and compares the filled containers with the next largest ones. If they are big enough to replace, the loads of the old containers are moved to the new empty containers. The same steps are done over the rest of the empty containers until all the filled containers are no longer replaced with any empty containers. The Qty and Seq of the empty containers are ignored when this choice is selected.
BestfitMaxVolUtilFirst Space utilization maximized Attempts to fill every available empty container as full as possible. Picks the filled container that yielded the highest volume utilization (%). Container Qty and Seq are ignored.
BestfitMaxLoadVolFirst Load volume maximized Picks the filled container with the highest absolute loaded cargo volume as the solution. Container Qty and Seq are ignored.
BestfitMaxWeightUtilFirst Weight utilization maximized Picks the filled container with the highest weight utilization (Total Cargo Weight / Max Weight limit) as the solution. Container Qty and Seq are ignored.

FillDirectionEnum

Value Description
BottomToTop Places the load on the ground to spread on the floor. Recommended for pallets to stack upwards in a stable spiral shape.
FrontToRear Builds a wall stacking from the inside to the outside (door side of truck/trailer).

StackingRuleEnum & GroupsStackingRuleEnum

Defines relative vertical positioning/stacking restrictions between two different cargoes.

Value Description
HigherStackValueBottomFirst Cargo is only allowed to be placed on top of others with a strictly greater Stack Value.
AllowedTopBottmStackValueSame Cargo is only allowed to be placed on top of others with the exact same Stack Value.
AllowedTopBottomFootPrintSame Cargo is only allowed to be placed on top of others with the exact same footprint (Length x Width).
AllowedTopBottomFootPrintSameOrTopFootPrintSmaller Cargo is only allowed to be placed on others with the same or a strictly larger footprint.
HeavierBottomFirst Cargo is only placed on heavier cargoes. Cargo will never be placed on a lighter cargo.
FollowStackMatrix Follows explicit Yes/No Matrix entries defined globally for each individual cargo.
FollowStackMatrixByCargoNames Derivative matrix matching using direct cargo names.
FollowStackMatrixByStackCodes Follows Stack Code parameters establishing group-class stacking parameters.
AlwaysNotAllowed Never allowed to be placed on top of any other cargo.
FloorStack Forced dead load. Cargo must be placed directly on the floor. Options include Bottom Only or Best Fit.
AlwaysSingleLayerOnBottom Floor stack restricted strictly to a rigid single layer.
FormPyramidStack Layer contour follows a pyramid stack architecture, concentrating weight in the center.
BestFit Unrestricted dynamic placement. Any cargo is placed on top of any other cargo for best utilization.
FloorStackAndHeavierBottomFirst Composite logic combining FloorStack preferences with weight distribution requirements.
AllowedTopBottomFootPrintSameHeavierBottomFirst Composite logic requiring matching footprints while enforcing heavier items at the bottom.
AllowedTopBottomFootPrintSameFollowDeadStack Composite logic pairing matched footprints with dead stack behavior.
AllowedTopBottomFootPrintSameHigherStackValueBottomFirst Composite logic pairing matched footprints with Stack Value validation.

OptionalCargoesFillingActionEnum

Value Description
Starightforward Straightforward filling action.
CargoSequenceRespectedAndDisplacementMinimized Respects cargo sequence while minimizing displacement.
GroupSequenceRespectedAndDisplacementMinimized Respects group sequence while minimizing displacement.

CalculationErrorEnum

Value Code Description
NoErrors 1 Calculation successful without errors.
EmptyCargoList 0 The cargo list is empty.
CargoWidthLongerThanLength -2 Cargo width cannot be longer than its length.
CargoHasZeroLoadCount -3 Cargo has zero load count.
CargoIsTooBig -4 Cargo is too big to fit in any container.
InvalidContainerSize -6 Invalid dimensions specified for container.
CargoHasZeroSetCount -7 Cargo has zero set count.
InvalidCargoSize -8 Invalid dimensions specified for cargo.
InvalidCargoOrientations -9 Invalid orientation flags for cargo.
CargoIsTooSmall -10 Cargo dimensions are too small or zero.
EmptyContainerList -20 The container list is empty.
UnableToSignin -21 Authentication failed. (New at ver 10.10.5.0)

StatusEnum

Value Description
succeed Calculation completed successfully.
invalid_server_settings Server setup or settings are invalid.
null_objects_in_shipment Shipment contains missing or null objects.
unable_to_signin Failed to authenticate user.
exceptional_error_found An unexpected exceptional error occurred.
no_records_found No records were found for the query.
missing_parameters Required parameters are missing.
calculation_pending Calculation is currently in progress.

UOMEnum

Value Description
UnitEnglish English system units (inches, pounds).
UnitMetric Metric system units (millimeters, kilograms).
UnitHighMetric High metric system units (centimeters, kilograms).

FAQ

How do I get an API key?

Log into your CubeMaster account, go to Settings > Integration, and generate or copy your API key. Use it in the header like this: TokenID: YOUR_API_KEY.

What happens if I send a load with an existing title?

The existing load will be overwritten. For example, if you POST /loads with the same title, it updates the existing one.

Can I test the API without saving loads?

Yes, set loadSaved=false in the query parameters. Example: POST /loads?loadSaved=false.

How do asynchronous requests work?

Use multiProcessed=true and provide webhookListenerURLToNewLoad. The server will POST the result to your URL when done.

What units of measure are supported?

UnitEnglish (inches/lbs), UnitMetric (mm/kg), UnitHighMetric (cm/kg). Set UOM in query parameters.

How do I view generated graphics?

Set graphicsCreated=true. The response will include URLs in graphics.images for 3D and 2D views. This may not be available in certain pricing model.

What if I encounter a 401 error?

Check your API key in the TokenID header. Ensure it's correct and not expired.

How do I retrieve all saved loads?

Use GET /Loads with optional parameters like limit=20 or shared=true.

Can I delete a specific load?

Yes, use DELETE /Loads/{userId}/{title}.

How do I add cargo to the database?

Use POST /Database/Cargoes/Multiple with a body containing an array of cargoes.

How do I update a cargo?

Use PUT /Database/Cargoes/{keyIs} with partial cargo object in body.

What’s the difference between synchronous and asynchronous processing?

Synchronous (multiProcessed=false) returns results immediately, while asynchronous (true) uses a webhook for larger loads to avoid timeouts.

How do I specify a custom background color for graphics?

Use graphicsBackgroundColorRGB with an integer RGB value, e.g., 16711680 for red.

Can I retrieve a specific container from a load?

Yes, use GET /Loads/{userId}/{title}/{filledContainerSeq}.

How do I share a load company-wide?

Set loadShared=true when creating or editing the load.

What languages are supported for reports?

ENG, GER, SPN, FRN, BRZ, CHN, JPN, KOR. Set reportLanguage in query.

How do I handle large datasets?

Use POST /Upload/Excel to upload Excel files for mass load creation.

What if my calculation fails?

Check the calculationError field in the response for details on validation or processing issues.

How do I use database-loaded details?

Set cargoDetailLoadedFromDatabase=true and provide only name and qty in cargoes array.

Can I get thumbnails in black and white?

Set thumbnailsCreatedInBlackWhite=true when thumbnailsCreated=true.

How do I include measurements in graphics?

Set graphicsShowScale=true.

What is the max image size for graphics?

Use graphicsImageWidth and graphicsImageDepth, up to reasonable sizes like 800.

How do I limit the number of results in GET /Loads?

Use the limit parameter, e.g., limit=5.

How do I filter loads by creation date?

Use createdAt parameter in GET /Loads, e.g., createdAt=2025-03-26.

What is the difference between spaces and placements?

Spaces are zones with grouped cargo, placements are individual item positions within spaces.

How do I enable detailed placements?

Set placementsCreated=true in query.

Can I use the API for real-time calculations?

Yes, for small loads use synchronous; for large, async with webhook.

How do I integrate with ERP systems?

Fetch data from ERP, construct Load JSON, call POST /loads, process response back to ERP.

Tutorials

Tutorial 1: Creating and Saving a Basic Load

Steps to create a truck load with cargo and save it.

  1. Prepare the Request: Define cargo and container details.
    2. Request Body 
    {
    "title": "Basic Truck Load",
    "description": "Tutorial load",
    "cargoes": [
        {
            "style": "shipcase",
            "name": "Tutorial Box",
            "length": 10,
            "width": 5,
            "height": 3,
            "weight": 20,
            "qty": 40
        }
    ],
    "emptyContainers": [
        {
            "containerType": "Truck",
            "name": "Tutorial Truck",
            "length": 20,
            "width": 8,
            "height": 8,
            "maxWeight": 1000
        }
    ],
    "rules": {
        "calculationType": "MixLoad",
        "algorithmType": "Optimization"
    }
}
  2. Send the Request: POST /loads with TokenID header.
  3. Check the Response: Verify status "succeed" and filledContainers.

Tutorial 2: Using Database Cargo and Containers

Steps to build a load using pre-saved database entries.

  1. Add Cargo to Database: POST /Database/Cargoes/Multiple.
  2. Add Container to Database: POST /Database/Containers/Truck.
  3. Create Load from Database: POST /loads?cargoDetailLoadedFromDatabase=true&containerDetailLoadedFromDatabase=true with names only.
  4. Verify Response: Check load details.

Tutorial 3: Generating Graphics and Reviewing a Load

Steps to create a load with graphics and retrieve it. This may not be available in certain pricing model.

  1. Create Load with Graphics: POST /loads?graphicsCreated=true&graphicsShowScale=true.
  2. Check Graphics in Response: Look for URLs in graphics.images.
  3. Retrieve the Load: GET /Loads/{userId}/{title}.
  4. Review Specific Container: GET /Loads/{userId}/{title}/{seq}.

Tutorial 4: Asynchronous Load Processing

Steps to process a large load asynchronously.

  1. Set Up Webhook: Create a server endpoint to receive POST results.
  2. Send Asynchronous Request: POST /loads?multiProcessed=true&webhookListenerURLToNewLoad=your-url.
  3. Receive Webhook Response: Handle the POST with the Response object.

Tutorial 5: Updating Cargo in Database

Steps to update an existing cargo.

  1. Retrieve Cargo: GET /Database/Cargoes/{name}.
  2. Update: PUT /Database/Cargoes/{name} with partial body, e.g., {"weight": 25}.
  3. Verify: GET again to check changes.

Tutorial 6: Deleting a Load

Steps to delete a saved load.

  1. List Loads: GET /Loads to find the title.
  2. Delete: DELETE /Loads/{userId}/{title}.
  3. Confirm: GET /Loads to see it's gone.

Tutorial 7: Using UnitLoad Calculation

Steps to build pallets.

  1. Prepare: Set rules.calculationType = "UnitLoad".
  2. Send: POST /loads with cargoes and pallet as emptyContainer.
  3. Response: FilledContainers as loaded pallets.

Tutorial 8: Handling Errors

Steps to debug a failed calculation.

  1. Send Invalid Request: e.g., missing required fields.
  2. Check Response: Look for status "failed" and calculationError details.
  3. Fix and Retry: Adjust based on error message.

Tutorial 9: Uploading Excel for Mass Loads

Steps to upload Excel.

  1. Prepare Excel: Format with cargoes and containers as per template.
  2. Upload: POST /Upload/Excel with multipart file.
  3. Response: Processed loads.

Tutorial 10: Retrieving Specific Container with Placements

Steps to get detailed placements.

  1. Create Load: POST /loads?placementsCreated=true.
  2. Retrieve Container: GET /Loads/{userId}/{title}/{seq}?placementsCreated=true.
  3. Analyze: Use spaces.placements for positions.

Tutorial 11: SetLoad for Proportional Loading

Steps to load items in set ratios.

  1. Set Ratios: Use setRatio in cargoes, e.g., 1 for A, 2 for B.
  2. Rules: calculationType = "SetLoad".
  3. Send: POST /loads.
  4. Response: Loads maintaining ratios.

Tutorial 12: Balancing Weight Distribution

Steps to balance load.

  1. Rules: balanceConfiguration = {isUsed: true, maxWeightDifference: 100}.
  2. Send: POST /loads.
  3. Check: Response cog for balance.

Tutorial 13: Using Custom Stacking Matrix

Steps to define stacking compatibility.

  1. Rules: stackingMatrix = array of rules between cargoes.
  2. Send: POST /loads.
  3. Response: Stacking respects matrix.

Tutorial 14: Multi-Container Types

Steps to use different containers.

  1. Rules: isMultiContainerTypesEnabled = true.
  2. EmptyContainers: Array with different types.
  3. Send: POST /loads.
  4. Response: Filled with optimal types.

Tutorial 15: Custom Solution Names

Steps to name solutions.

  1. Rules: isCustomRuleUsedForSolutionsNames = true, prefixOfSolutionsNames = "Load-".
  2. Send: POST /loads.
  3. Response: filledContainers names like "Load-001".