Create a packing job

Validates the request, reserves the worst-case price from your credits and queues a job.

POSThttps://runner.cargoduo.com/v1/pack

Answers 202 with the job; poll GET /v1/jobs/{id}, or pass ?wait= to hold the response until it ends. Validation failures (422) are free and create no job.

Authentication

Bearer API key with scopepack:writeLearn more

Query parameters

NameTypeRequiredDescription

waitinteger

integer

Seconds to hold the response for the job to finish. Finished in time: 200 with the result inlined. Otherwise: 202.

Default 00–60

Header parameters

NameTypeRequiredDescription

Idempotency-Keystring

string

Any unique string, such as a UUID or your order id. The same key within 24 h returns the original job instead of creating and charging a new one.

≤ 128 chars

Body parameters

application/json

NameTypeRequiredDescription

referencestring

string

Your own reference (order number, shipment id…). Echoed back on the job.

≤ 128 chars

vehiclesVehicle[]required

Vehicle[]

Yes

Vehicle definitions. Each one may have quantity > 1. At least one.

idstring

string

Your identifier, unique within the request. Results refer to it as vehicle_id. Defaults to vehicle_id.

≤ 128 chars

vehicle_idstring

string

A vehicle id from GET /v1/vehicles: a preset or one of your organization's vehicles (veh_…). Supplies type, name, dimensions, payload and every other saved value.

typestring

string

Vehicle type. Required unless vehicle_id is given. Only the types listed in GET /v1/limits (allowed_vehicle_types) are accepted.

trucktrailerflatbedcontainerpalletaircraftship

namestring

string

Display name (defaults to the saved vehicle's name or the id).

≤ 255 chars

lengthnumber · cm

number · cm

Internal cargo-space length, along x (from the front wall toward the door). Required unless vehicle_id is given.

widthnumber · cm

number · cm

Internal cargo-space width, along z. Required unless vehicle_id is given.

heightnumber · cm

number · cm

Internal cargo-space height, along y. Required unless vehicle_id is given.

max_weightnumber · kg

number · kg

Maximum payload. Required unless vehicle_id is given.

quantityinteger

integer

How many identical vehicles of this definition are available.

Default 11–100

floor_load_capacitynumber · kg/m²

number · kg/m²

Floor load capacity: 0 or more (0 = no limit).

aux_deckboolean

boolean

The vehicle has a second deck (double-decker).

Default false

aux_deck_heightnumber · cm

number · cm

Second deck height above the floor. Required when aux_deck is true.

aux_deck_max_weightnumber · kg

number · kg

Load limit of the second deck. Required when aux_deck is true.

blocked_areasRect[]

Rect[]

Floor zones nothing may stand on (wheel arches, damage, reserved space). Each must lie on the vehicle floor.

≤ 32 items

axle_positionsRequires accessnumber[] · cm

number[] · cm

Axle (support point) positions measured from the front of the cargo area; negative = in front of it. Same length as axle_max_loads. Each between −300 (an axle ahead of the cargo area, e.g. a rigid truck's front axle under the cab) and the vehicle length.

≤ 10 items

axle_max_loadsRequires accessnumber[] · kg

number[] · kg

Maximum cargo load per axle, in the order of axle_positions. Each greater than 0 and at most 100000.

≤ 10 items

cog_range_xRequires accessnumber · cm

number · cm

Allowed centre-of-gravity deviation from the middle of the length: 0 to length / 2.

cog_range_yRequires accessnumber · cm

number · cm

Allowed centre-of-gravity deviation from the middle of the width: 0 to width / 2.

tractor_weightRequires accessnumber · kg

number · kg

Semi-trailer axle model: tractor unit mass.

empty_trailer_weightRequires accessnumber · kg

number · kg

Semi-trailer axle model: unladen trailer mass.

front_axle_to_middle_axleRequires accessnumber · cm

number · cm

Semi-trailer axle model: tractor front axle to drive (middle) axle.

front_axle_to_tractor_cogRequires accessnumber · cm

number · cm

Semi-trailer axle model: front axle to tractor centre of gravity.

front_axle_to_kingpinRequires accessnumber · cm

number · cm

Semi-trailer axle model: front axle to kingpin (fifth wheel).

kingpin_to_rear_axleRequires accessnumber · cm

number · cm

Semi-trailer axle model: kingpin to trailer rear axle group.

trailer_cog_to_rear_axleRequires accessnumber · cm

number · cm

Semi-trailer axle model: trailer centre of gravity to rear axle group.

trailer_start_to_kingpinRequires accessnumber · cm

number · cm

Semi-trailer axle model: trailer front to kingpin.

max_middle_axle_weightRequires accessnumber · kg

number · kg

Semi-trailer axle model: legal drive (middle) axle limit.

max_rear_axle_weightRequires accessnumber · kg

number · kg

Semi-trailer axle model: legal rear axle group limit.

itemsItem[]required

Item[]

Yes

Item definitions. Each one may have quantity > 1. At least one.

groupsGroup[]

Group[]

Optional groups (customers, stops, orders). Required for every group an item names when options.group_routing is not "none"; otherwise groups are created from the item group names in order of appearance.

optionsOptions

Options

Packing options. Every field is optional.

Example request

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

const res = await fetch("https://runner.cargoduo.com/v1/pack", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CARGODUO_API_KEY}`,
    "Idempotency-Key": "order-1042-v1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }),
});

const data = await res.json();
console.log(res.status, data);

import os
import requests

response = requests.post(
    "https://runner.cargoduo.com/v1/pack",
    headers={"Authorization": f"Bearer {os.environ['CARGODUO_API_KEY']}", "Idempotency-Key": "order-1042-v1"},
    json={
        "reference": "order-1042",
        "vehicles": [
            {
                "id": "trailer",
                "type": "trailer",
                "name": "13.6 m trailer",
                "length": 1360,
                "width": 245,
                "height": 270,
                "max_weight": 24000,
            },
        ],
        "items": [
            {
                "id": "pallet-eu",
                "label": "Euro pallet",
                "length": 120,
                "width": 80,
                "height": 140,
                "weight": 450,
                "quantity": 18,
                "stackable": False,
            },
            {
                "id": "carton-a",
                "label": "Carton A",
                "length": 60,
                "width": 40,
                "height": 40,
                "weight": 12,
                "quantity": 40,
                "rotation": "upright",
            },
        ],
        "options": {
            "packing_mode": "auto",
        },
    },
)
print(response.status_code, response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "reference": "order-1042",
  "vehicles": [
    {
      "id": "trailer",
      "type": "trailer",
      "name": "13.6 m trailer",
      "length": 1360,
      "width": 245,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "pallet-eu",
      "label": "Euro pallet",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false
    },
    {
      "id": "carton-a",
      "label": "Carton A",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "rotation": "upright"
    }
  ],
  "options": {
    "packing_mode": "auto"
  }
}`)

	req, err := http.NewRequest("POST", "https://runner.cargoduo.com/v1/pack", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("CARGODUO_API_KEY"))
	req.Header.Set("Idempotency-Key", "order-1042-v1")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "reference": "order-1042",
              "vehicles": [
                {
                  "id": "trailer",
                  "type": "trailer",
                  "name": "13.6 m trailer",
                  "length": 1360,
                  "width": 245,
                  "height": 270,
                  "max_weight": 24000
                }
              ],
              "items": [
                {
                  "id": "pallet-eu",
                  "label": "Euro pallet",
                  "length": 120,
                  "width": 80,
                  "height": 140,
                  "weight": 450,
                  "quantity": 18,
                  "stackable": false
                },
                {
                  "id": "carton-a",
                  "label": "Carton A",
                  "length": 60,
                  "width": 40,
                  "height": 40,
                  "weight": 12,
                  "quantity": 40,
                  "rotation": "upright"
                }
              ],
              "options": {
                "packing_mode": "auto"
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://runner.cargoduo.com/v1/pack"))
            .header("Authorization", "Bearer " + System.getenv("CARGODUO_API_KEY"))
            .header("Idempotency-Key", "order-1042-v1")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("CARGODUO_API_KEY"));
client.DefaultRequestHeaders.Add("Idempotency-Key", "order-1042-v1");

var json = """
    {
      "reference": "order-1042",
      "vehicles": [
        {
          "id": "trailer",
          "type": "trailer",
          "name": "13.6 m trailer",
          "length": 1360,
          "width": 245,
          "height": 270,
          "max_weight": 24000
        }
      ],
      "items": [
        {
          "id": "pallet-eu",
          "label": "Euro pallet",
          "length": 120,
          "width": 80,
          "height": 140,
          "weight": 450,
          "quantity": 18,
          "stackable": false
        },
        {
          "id": "carton-a",
          "label": "Carton A",
          "length": 60,
          "width": 40,
          "height": 40,
          "weight": 12,
          "quantity": 40,
          "rotation": "upright"
        }
      ],
      "options": {
        "packing_mode": "auto"
      }
    }
    """;

var request = new HttpRequestMessage(HttpMethod.Post, "https://runner.cargoduo.com/v1/pack")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json"),
};
var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

<?php

$payload = <<<'JSON'
{
  "reference": "order-1042",
  "vehicles": [
    {
      "id": "trailer",
      "type": "trailer",
      "name": "13.6 m trailer",
      "length": 1360,
      "width": 245,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "pallet-eu",
      "label": "Euro pallet",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false
    },
    {
      "id": "carton-a",
      "label": "Carton A",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "rotation": "upright"
    }
  ],
  "options": {
    "packing_mode": "auto"
  }
}
JSON;

$ch = curl_init('https://runner.cargoduo.com/v1/pack');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CARGODUO_API_KEY'),
        'Idempotency-Key: order-1042-v1',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $response, PHP_EOL;

require "net/http"
require "uri"

uri = URI("https://runner.cargoduo.com/v1/pack")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("CARGODUO_API_KEY")}"
request["Idempotency-Key"] = "order-1042-v1"
request["Content-Type"] = "application/json"
request.body = <<~'JSON'
  {
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts response.code, response.body

Example response

202 Accepted · Job

{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

Responses

200OKJob finished within ?wait, result inlined. Also an idempotent replay of a finished job.Job
NameTypeRequiredDescription
idstringrequired
string
Yes
Job id (job_…).
objectstringrequired
string
Yes
Always job.
job
statusstringrequired
string
Yes
queued → running → succeeded | failed | canceled.
queuedrunningsucceededfailedcanceled
referencestring
string
No
Your reference from the request.
sourcestring
string
No
Where the job was created.
apiplayground
project_idstring
string
No
The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.
created_atstringrequired
string
Yes
RFC 3339 timestamp.
started_atstring | null
string | null
No
When computing started (RFC 3339) or null.
finished_atstring | null
string | null
No
When the job ended (RFC 3339) or null.
progressJobProgress
JobProgress
No
Live progress while queued/running.
summaryJobSummary
JobSummary
No
Counts and timings.
costJobCost
JobCost
No
Credits charged (final once the job ended) and the reservation held while it ran.
errorJobError | null
JobError | null
No
Why the job failed or was canceled; null otherwise.
warningsWarning[]
Warning[]
No
Non-blocking remarks about the request (also repeated in the result).
result_urlstring
string
No
GET this URL for the full result once status is succeeded.
pdf_urlstring
string
No
A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.
expires_atstring
string
No
When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.
resultResult
Result
No
The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.
202AcceptedJob accepted (queued or running).Job
NameTypeRequiredDescription
idstringrequired
string
Yes
Job id (job_…).
objectstringrequired
string
Yes
Always job.
job
statusstringrequired
string
Yes
queued → running → succeeded | failed | canceled.
queuedrunningsucceededfailedcanceled
referencestring
string
No
Your reference from the request.
sourcestring
string
No
Where the job was created.
apiplayground
project_idstring
string
No
The project (prj_…) a POST /v1/projects/{id}/pack job saves its plan into. Absent on other jobs.
created_atstringrequired
string
Yes
RFC 3339 timestamp.
started_atstring | null
string | null
No
When computing started (RFC 3339) or null.
finished_atstring | null
string | null
No
When the job ended (RFC 3339) or null.
progressJobProgress
JobProgress
No
Live progress while queued/running.
summaryJobSummary
JobSummary
No
Counts and timings.
costJobCost
JobCost
No
Credits charged (final once the job ended) and the reservation held while it ran.
errorJobError | null
JobError | null
No
Why the job failed or was canceled; null otherwise.
warningsWarning[]
Warning[]
No
Non-blocking remarks about the request (also repeated in the result).
result_urlstring
string
No
GET this URL for the full result once status is succeeded.
pdf_urlstring
string
No
A browser link that renders the load plan as a PDF (3D views + loading steps). Valid until expires_at. Empty after expiry.
expires_atstring
string
No
When the request/result bodies and the PDF link are deleted (RFC 3339). Job metadata and charges are kept.
resultResult
Result
No
The full result, inlined only when requested (?include=result) or when POST /v1/pack?wait= finished in time.
400Bad requestinvalid_jsonidempotency_key_invalidError
- invalid_jsonThe body is not valid JSON or a field has the wrong type.
- idempotency_key_invalidThe Idempotency-Key header is longer than 128 characters.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
401Unauthorizedunauthorizedkey_revokedkey_expiredError
- unauthorizedMissing, malformed or unknown API key.
- key_revokedThe key was revoked.
- key_expiredThe key passed its expiry date.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
402Payment requiredinsufficient_creditsError
- insufficient_creditsAvailable credits do not cover the smallest possible run of this job.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missingError
- ip_not_allowedThe calling IP is not on the key's allowlist.
- subscription_inactiveThe organization has no active subscription that includes the API.
- account_inactiveThe organization is suspended, or has no owner whose account is active.
- scope_missingThe key lacks a scope this endpoint needs.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
413Payload too largepayload_too_largeError
- payload_too_largeThe request body exceeds 10 MB.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
422Unprocessable entityvalidation_failedError
- validation_failedThe request is well-formed JSON but describes an invalid job. details[] lists every problem.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
429Too many requeststoo_many_jobsrate_limitedError
- too_many_jobsThe organization already has the maximum number of queued + running jobs.
- rate_limitedToo many requests in the current minute, hour or day (per key or per organization), or more than 60 failed authentications per minute from your IP address.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
500Internal server errorinternal_errorError
- internal_errorSomething failed on our side.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes
503Service unavailableapi_disabledError
- api_disabledThe API is temporarily disabled (maintenance) or switched off for the organization.
NameTypeRequiredDescription
errorErrorBodyrequired
ErrorBody
Yes
All error codes

QuickstartCreate a key, send one request, read the plan.IdempotencyRetry POST /v1/pack without creating a second job.Credits & pricingWhat a job costs and where credits come from.Results & coordinatesWhere every item sits, in which orientation and loading order.

Authentication

Query parameters

Header parameters

Body parameters

Example request

Example response

Responses

Related