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.

Unitload

Parameter	Type	Description
isPalletized	boolean	If true, cargo is palletized before loading.
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	RGB color code for visualization.
colorHexaCode	string	Hex color code.
colorKnownName	string	Known color name.

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.
maxWeight	integer	Maximum load weight allowed in the container, 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	Number of containers (often 0 for a single definition).
priority	integer	Priority for container selection (e.g., 0).
emptyWeight	integer	Weight of the empty container in kg (e.g., 0).
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).
maxCargoTypes	integer	Maximum number of cargo types (0 if unrestricted).
price	integer	Container cost (e.g., 0).
maxPrice	integer	Maximum allowable cost (e.g., 0).

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).
colorHexaCode	string	Hex color code (empty if not specified).
colorKnownName	string	Human-readable color name (empty if not specified).
palletOverhang	boolean	Whether pallet overhang is allowed (e.g., false).
palletOverhangLength	integer	Overhang length in cm (e.g., 0).
palletOverhangWidth	integer	Overhang width in cm (e.g., 0).
palletUnderhang	boolean	Whether pallet underhang is allowed (e.g., false).
palletUnderhangLength	integer	Underhang length in cm (e.g., 0).
palletUnderhangWidth	integer	Underhang width in cm (e.g., 0).
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	Load Type / processing procedure (e.g., "MixLoad", "UnitLoad", "SetLoad"). 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.
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.
isUnitloadsPartialAllowedWhenUnitloadsFirst	boolean	If true, allows 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.
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.
minWeightDifferencePercentageForStackingTwoCargoes	number	Min weight difference % for stacking two different cargoes.
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	{isUsed: boolean, algorithm: "ProportionalToGroundPlacementWidth", proportionalRateToSetMaxStackingHeight: 1.5} - Controls max stack height dynamically.

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, uses sequence within groups.
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.
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.
maxFillQtyPerContainer	integer	Max fill quantity per container.
isCargoCostComputedFromShipCost	boolean	If true, computes cargo cost from shipping cost. Read-only.
isIdenticalCargoStayInOneContainerWhenNotSpread	boolean	If true, keeps identical cargo in one container when not spread. Read-only.
isSideSpaceOfCargoFilledWithSameCargo	boolean	If true, fills side spaces with same cargo. Read-only.
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.
maxPlacementSize	number	Max placement size. Read-only.
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))
}

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}/{title}

Retrieves a specific load by user ID and 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.

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

POST /Upload/Excel

Uploads an Excel file to build mass loads.

Query Parameters

Name	Type	Description	Default	Required
multiProcessed	boolean	Asynchronous processing.	false	false
webhookListenerURLToNewLoad	string	Webhook URL.	none	false
loadSaved	boolean	Save the load.	true	false
loadShared	boolean	Share the load.	true	false
userId	string	User email.	API email	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.	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
reportLanguage	string	Report language.	ENG	false
reportToolbarShown	boolean	Show toolbar.	false	false

Request Body: Multipart form with Excel file.

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):

OrientationsBasic (Permits 1, 2)
OrientationsNonBasic (Permits 3, 4, 5, 6)
OrientationsDefault (Permits 1, 2, 3, 4)
OrientationsAll (Permits 1, 2, 3, 4, 5, 6)
Orientations1
Orientations2
Orientations3
Orientations4
Orientations5
Orientations6
Orientations12
Orientations13
Orientations123 ... etc.

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.

Prepare the Request: Define cargo and container details.

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"
    }
}

Send the Request: POST /loads with TokenID header.
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.

Add Cargo to Database: POST /Database/Cargoes/Multiple.
Add Container to Database: POST /Database/Containers/Truck.
Create Load from Database: POST /loads?cargoDetailLoadedFromDatabase=true&containerDetailLoadedFromDatabase=true with names only.
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.

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

Tutorial 4: Asynchronous Load Processing

Steps to process a large load asynchronously.

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

Tutorial 5: Updating Cargo in Database

Steps to update an existing cargo.

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

Tutorial 6: Deleting a Load

Steps to delete a saved load.

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

Tutorial 7: Using UnitLoad Calculation

Steps to build pallets.

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

Tutorial 8: Handling Errors

Steps to debug a failed calculation.

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

Tutorial 9: Uploading Excel for Mass Loads

Steps to upload Excel.

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

Tutorial 10: Retrieving Specific Container with Placements

Steps to get detailed placements.

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

Tutorial 11: SetLoad for Proportional Loading

Steps to load items in set ratios.

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

Tutorial 12: Balancing Weight Distribution

Steps to balance load.

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

Tutorial 13: Using Custom Stacking Matrix

Steps to define stacking compatibility.

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

Tutorial 14: Multi-Container Types

Steps to use different containers.

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

Tutorial 15: Custom Solution Names

Steps to name solutions.

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