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.

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

Core Components

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

Orientations

Unitload

Extended

Advanced

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

Drop Deck

Extended

Advanced

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

Stacking

Grouping

Advanced

Palletizing

Balancing

{
  "calculationType": "MixLoad",
  "algorithmType": "Optimization",
  "allowMix": true,
  "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

Load Summary

Filled Containers

Document

{
  "status": "succeed",
  "message": "OK",
  "calculationError": null,
  "document": {
    "title": "Sample Load",
    "isShared": true,
    "calculationTimeInSeconds": 5,
    "createdAt": "2025-03-26T10:00:00Z"
  },
  "loadSummary": {
    "cargoesLoaded": 50,
    "piecesLoaded": 50,
    "unitloadsLoaded": 1,
    "weightAdded": 1000
  },
  "filledContainers": [
    {
      "name": "Truck 1_1",
      "sequence": 1,
      "loadQty": 50,
      "grossWeight": 1000,
      "volumeUtilization": 80.5
    }
  ]
}

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

Load Summary

Graphics

Spaces

Placements (Sub of Spaces)

Manifest

Advanced

{
  "name": "Truck 1_1",
  "sequence": 1,
  "loadQty": 50,
  "grossWeight": 1000,
  "volumeUtilization": 80.5
}

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

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)

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)

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)

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

 '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

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

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

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

Query Parameters

Request Body: Load object (see Load Schema).

Response: Response object (see Response Schema).

Endpoints: Database/Master Data

Retrieves a cargo by name from the cargoes database.

Query Parameters

Response: Cargo object.

Deletes a cargo by name from the cargoes database.

Query Parameters

Retrieves all cargoes from the cargoes database.

Query Parameters

Inserts multiple cargoes into the cargoes database.

Query Parameters

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

Updates a cargo (partial updates supported).

Query Parameters

Request Body: Partial Cargo object.

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

Query Parameters

Inserts a container into the containers database.

Query Parameters

Request Body: EmptyContainer object.

Retrieves a container by type and name.

Query Parameters

Deletes a container by type and name.

Query Parameters

Endpoints: Archive API

Retrieves all saved loads from the database.

Query Parameters

Retrieves a specific load by user ID and title.

Query Parameters

Deletes a load by user ID and title.

Query Parameters

Retrieves a specific filled container from a load.

Query Parameters

Endpoints: Edit & Upload API

Builds a load from editing data and saves it.

Query Parameters

Retrieves editing data for a user.

Query Parameters

Deletes editing data for a user.

Query Parameters

Retrieves a filled container from editing data.

Query Parameters

Uploads an Excel file to build mass loads.

Query Parameters

Request Body: Multipart form with Excel file.

Enumerations

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.

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.
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.

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