API reference

Call the packing engine directly over HTTP. Send a shipment (products and box types) and receive the optimal set of parcels. Responses are deterministic for a given request.

Download Postman collection Open interactive API reference

Base URL

http://localhost:5180

Authentication

Every request must include your API key in the X-Api-Key header. Contact your Paxon administrator to obtain a key.

X-Api-Key: your-api-key

Endpoint

POST http://localhost:5180/api/v1/pack

Request fields

Field	Type	Notes
maxParcels	int	Max parcels (boxes + boxless).
rotationMode	string	None \| UprightOnly \| Free.
products	array	id, length, width, height (mm), weight (g), quantity, breakable, dg, boxless?, orientationConstrained?, tags?.
boxTypes	array	id, length, width, height (mm), maxWeight (g), breakableAllowed, dgAllowed, priority (lower preferred), minCutHeight? (mm — the machine can trim the box down to this height).
rules	array?	type (keep-separate \| keep-together \| limit-quantity), tagA, tagB?, quantity?.
maxRuntimeSeconds	int?	Override the solve budget (bounded by a server ceiling).
forceRecompute	bool?	Bypass the cache lookup (result still cached).

Response fields

Field	Type	Notes
status	string	SUCCESS \| NO_SOLUTION \| NOT_FOUND \| ERROR.
parcelsUsed	int	Boxes + boxless items used.
boxes	array	Chosen boxes with their placements, contentsHeight (mm, how tall the contents stack) and cutHeight? (mm, present only when the box is cuttable).
boxlessItems	array	Items shipped without a box.
timedOut	bool	True if the solve budget elapsed.
runtimeMs	long	Solve time in milliseconds.
errors	array?	Present when status is ERROR.

Result status

SUCCESS: a solution was found. NO_SOLUTION: proven impossible within the limits. NOT_FOUND: no solution found but not proven impossible (see timedOut). ERROR: the request was invalid (see errors).

Errors

Invalid input returns HTTP 200 with status ERROR and an errors array; each entry has a code (a field path such as products[0].weight) and a human-readable message.

Limits

Up to 100 requests per minute per IP address; request bodies are capped at 1 MB.

Example request

{
  "maxParcels": 6,
  "rotationMode": "Free",
  "products": [
    { "id": "SKU-1", "length": 220, "width": 150, "height": 20, "weight": 500, "quantity": 1, "breakable": false, "dg": false }
  ],
  "boxTypes": [
    { "id": "A1", "length": 225, "width": 150, "height": 100, "maxWeight": 15000, "breakableAllowed": true, "dgAllowed": true, "priority": 20, "minCutHeight": 20 }
  ]
}

Example response

{
  "success": true,
  "parcelsUsed": 1,
  "boxes": [ { "boxTypeId": "A1", "contentsHeight": 20, "cutHeight": 20, "placements": [ { "productId": "SKU-1" } ] } ],
  "boxlessItems": [],
  "status": "SUCCESS",
  "timedOut": false,
  "runtimeMs": 3
}