API Reference

BinSolver Docs

Developer-first API for 3D bin packing.

Get API Key Download OpenAPI
Base URL
https://api.binsolver.com
Production
Authentication

Send your API key in x-api-key. Keys are managed in the dashboard.

Version

1.0.2 Stable

Overview

BinSolver API is a focused API for 3D bin packing. Send items and bins with constraints like rotation, nesting, stacking, and shipping objectives, and get an optimized arrangement in milliseconds.

Request shape

Send JSON with item dimensions, bin dimensions, quantities, and an objective. Item ids must be unique; when quantity is set, ids expand with # suffixes. Add an optional x-request-id header for tracing.

Responses

Successful pack calls return packed bins (each with a vizUrl), unplaced items, and stats. Errors share a consistent JSON error envelope.

Quickstart

Create an API key, send a pack request, and inspect the placements. The response is deterministic and fast, even for high-volume shipments.

1
Get an API key

Generate a key in the dashboard and store it as $BINSOLVER_API_KEY.

2
Send a pack request

Use the /v1/pack endpoint for stable clients and set an objective like minBins or minWaste.

3
Render the placements

Use the returned dimensions, positions, and rotations, or open bin.vizUrl in /viz to review the fit or drive fulfillment logic.

curl 
curl -X POST https://api.binsolver.com/v1/pack \
  -H "x-api-key: $BINSOLVER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "allowUnplaced": true,
    "objective": "minBins",
    "items": [
      {
        "id": "item-1",
        "w": 2,
        "h": 2,
        "d": 1,
        "quantity": 2
      }
    ],
    "bins": [
      {
        "id": "small-box",
        "w": 4,
        "h": 3,
        "d": 3,
        "quantity": 1
      }
    ]
  }'

SDKs

Official client libraries are available for Python, TypeScript, and Go.

Python
pip install binsolver

Fully typed with Pydantic models. View on GitHub

TypeScript
npm install binsolver

Generated from OpenAPI specs. View on GitHub

Go
go get github.com/welltyped-systems/binsolver-go

Context-aware and strongly typed. View on GitHub

Authentication

Authenticate requests using your API key in the x-api-key header. .

Header format
x-api-key: $BINSOLVER_API_KEY

Endpoints

Each endpoint is documented with parameters, request shape, and response samples. Use /v1/pack for long-lived clients.

GET /

Service banner

Responses
200 Plain text banner.
Request 
No request body.
Response text/plain
BinSolver API
GET /health

Health check

Responses
200 Service is healthy.
Request 
No request body.
Response text/plain
ok
POST /pack Auth required

Pack items into bins

Parameters
x-request-id
header optional
Optional request correlation id.
string
Request body
application/json PackRequest Required
Request schema
PackRequest
Expand
items
Items to pack (expanded by quantity). Maximum items per request is plan-dependent (free 100, paid 1000).
array<ItemInput> Required
Array of ItemInput Expand
id
Optional item identifier. If omitted, the API assigns one.
string
w
Item width (X axis).
number (double) Required
h
Item height (Y axis).
number (double) Required
d
Item depth (Z axis).
number (double) Required
weight
Weight of a single unit of this item (used for load limits and shipping).
number (double)
allowRotation
If true, the item can be rotated 90 degrees on any axis. Defaults to true.
boolean
rotation
Detailed rotation rules (overrides allowRotation when provided).
RotationRulesInput
RotationRulesInput Expand
mode
Rotation strategy. upright/noFlip keep height on Y axis.
Values: any, none, upright, noFlip, axis, custom
RotationMode
RotationMode Expand
No documented properties.
allowAxes
Allowed axis swaps when mode=axis.
RotationAxes
RotationAxes Expand
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
allowed
Allowed explicit rotations when mode=custom.
Values: xyz, xzy, yxz, yzx, zxy, zyx
array<string>
stacking
Stacking constraints for stability and load.
StackingRulesInput
StackingRulesInput Expand
minSupportRatio
Minimum supported base area ratio (0..1).
number (double)
minSupportArea
Minimum supported base area (absolute units).
number (double)
maxLoad
Maximum load this item can support above it.
number (double)
maxStackHeight
Maximum stacked height above this item.
number (double)
requireCogSupport
Require center-of-gravity to be supported.
boolean
packaging
Grouping, hazmat, fragile, and padding rules.
PackagingRulesInput
PackagingRulesInput Expand
group
Group identifier. Items sharing the same group id are governed by groupMode.
string
groupMode
keepTogether packs the entire group in the same bin (or leaves all unplaced); separate isolates the group to its own bins. Defaults to keepTogether when group is set.
Values: keepTogether, separate
GroupMode
GroupMode Expand
No documented properties.
hazmat
Marks item as hazardous; requires allowHazmat=true on bins.
boolean
fragile
Marks item as fragile; prevents stacking weight above.
boolean
nestable
When false, this item cannot be nested inside other items. Defaults to true.
boolean
nesting
Defines an internal cavity so other items may be packed inside this item.
NestingRulesInput
NestingRulesInput Expand
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
padding
Clearance added around the item dimensions.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
quantity
When set, total expanded items must remain within plan limits (free 100, paid 1000).
integer
bins
Bin templates to pack into. Maximum bin types per request is plan-dependent (free 50, paid 200).
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowUnplaced
When false, the request fails if any item cannot be placed. Defaults to true.
boolean
objective
Packing objective (speed, bins used, placed count, waste minimization, cost, or shipping). minCost requires bin cost values; shipping requires bin shipping profiles. Defaults to 'fast'.
Values: fast, minBins, maxPlaced, minWaste, minCost, shipping
string
shippingObjective
Weights for shipping-aware optimization. Used when objective=shipping; can also tune shipping scoring while using other objectives.
ShippingObjectiveInput
ShippingObjectiveInput Expand
costWeight
Weight applied to cost in the shipping objective.
number (double)
carbonWeight
Weight applied to carbon impact in the shipping objective.
number (double)
slaWeight
Weight applied to SLA days in the shipping objective (lower is better).
number (double)
dimWeightDivisor
Override bin shipping dimWeightDivisor for optimization.
number (double)
palletization
Two-stage packing (items->pallets->containers). Returns pallet results and split assignments. (Paid plan only)
PalletizationInput Pro only
PalletizationInput Expand
pallets
Pallet templates used for the first packing stage.
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowMixedContainers
When false, all pallets must fit a single container template.
boolean
includeInstructions
If true, returns step-by-step packing instructions for each bin. (Paid plan only) Defaults to false.
boolean Pro only
labelFormat
If 'zpl', generates a ZPL label string for each bin. (Paid plan only) Defaults to 'none'.
Values: none, zpl
string Pro only
nestingStrategy
Controls pre-pack nesting. auto uses the main objective to decide nesting; maximize fills cavities first; none disables nesting. Defaults to 'auto'.
Values: auto, maximize, none
string
Responses
200 Packing result. (PackResponse)
400 Invalid payload or limits exceeded. (ErrorResponse)
401 Missing or invalid API key. (ErrorResponse)
402 Usage exceeded. (ErrorResponse)
403 Forbidden. (ErrorResponse)
408 Request timeout.
429 Rate limited. (ErrorResponse)
502 Upstream auth provider error. (ErrorResponse)
Response schema
PackResponse 200
Expand
bins
Packed bins (containers) with placements.
array<BinResult> Required
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
pallets
Packed pallets when palletization is enabled.
array<BinResult>
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
unplaced
Items that could not be placed.
array<UnplacedItem> Required
Array of UnplacedItem Expand
itemId
Item identifier.
string Required
w
Item width.
number (double) Required
h
Item height.
number (double) Required
d
Item depth.
number (double) Required
weight
Item weight.
number (double)
reason
Reason code for why the item was not placed (e.g., no_fit, pallet_unplaced).
string Required
unplacedPallets
Pallets that could not be placed into containers.
array<UnplacedPallet>
Array of UnplacedPallet Expand
palletId
Pallet instance id.
string Required
reason
Reason code for why the pallet was not placed.
string Required
splits
Item-to-container assignments with pallet audit trails.
array<SplitAssignment>
Array of SplitAssignment Expand
itemId
Item identifier.
string Required
binId
Container/bin identifier where the item ultimately lands.
string Required
palletId
Pallet identifier if palletization was used.
string
stats
PackStats Required
PackStats Expand
items
Total items requested (after quantity expansion).
integer Required
placed
Number of items successfully placed.
integer Required
unplaced
Number of items not placed.
integer Required
nested
Number of items nested inside other items.
integer
binsUsed
Number of bins used.
integer Required
palletsUsed
Number of pallets used (if palletization enabled).
integer
durationMs
Packing duration in milliseconds.
integer (int64) Required
requestId
Echoed request id when provided.
string
Response schema
ErrorResponse 400, 401, 402, 403, 429, 502
Expand
error
ErrorBody Required
ErrorBody Expand
code
Machine-readable error code.
string Required
message
Human-readable error message.
string Required
requestId
Request identifier when provided.
string
Request 
{
  "allowUnplaced": true,
  "objective": "minBins",
  "items": [
    {
      "id": "item-1",
      "w": 2,
      "h": 2,
      "d": 1,
      "quantity": 2
    }
  ],
  "bins": [
    {
      "id": "small-box",
      "w": 4,
      "h": 3,
      "d": 3,
      "quantity": 1
    }
  ]
}
Response application/json
{
  "bins": [
    {
      "binId": "bin-1",
      "templateId": "small-box",
      "w": 4,
      "h": 3,
      "d": 3,
      "vizUrl": "https://binsolver.com/viz?l=example",
      "utilization": 0.44,
      "placements": [
        {
          "itemId": "item-1#1",
          "x": 0,
          "y": 0,
          "z": 0,
          "w": 2,
          "h": 2,
          "d": 1,
          "rotation": "xyz"
        },
        {
          "itemId": "item-1#2",
          "x": 2,
          "y": 0,
          "z": 0,
          "w": 2,
          "h": 2,
          "d": 1,
          "rotation": "xyz"
        }
      ]
    }
  ],
  "unplaced": [],
  "stats": {
    "items": 2,
    "placed": 2,
    "unplaced": 0,
    "binsUsed": 1,
    "durationMs": 3
  }
}
POST /v1/pack Auth required

Pack items into bins

Parameters
x-request-id
header optional
Optional request correlation id.
string
Request body
application/json PackRequest Required
Request schema
PackRequest
Expand
items
Items to pack (expanded by quantity). Maximum items per request is plan-dependent (free 100, paid 1000).
array<ItemInput> Required
Array of ItemInput Expand
id
Optional item identifier. If omitted, the API assigns one.
string
w
Item width (X axis).
number (double) Required
h
Item height (Y axis).
number (double) Required
d
Item depth (Z axis).
number (double) Required
weight
Weight of a single unit of this item (used for load limits and shipping).
number (double)
allowRotation
If true, the item can be rotated 90 degrees on any axis. Defaults to true.
boolean
rotation
Detailed rotation rules (overrides allowRotation when provided).
RotationRulesInput
RotationRulesInput Expand
mode
Rotation strategy. upright/noFlip keep height on Y axis.
Values: any, none, upright, noFlip, axis, custom
RotationMode
RotationMode Expand
No documented properties.
allowAxes
Allowed axis swaps when mode=axis.
RotationAxes
RotationAxes Expand
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
allowed
Allowed explicit rotations when mode=custom.
Values: xyz, xzy, yxz, yzx, zxy, zyx
array<string>
stacking
Stacking constraints for stability and load.
StackingRulesInput
StackingRulesInput Expand
minSupportRatio
Minimum supported base area ratio (0..1).
number (double)
minSupportArea
Minimum supported base area (absolute units).
number (double)
maxLoad
Maximum load this item can support above it.
number (double)
maxStackHeight
Maximum stacked height above this item.
number (double)
requireCogSupport
Require center-of-gravity to be supported.
boolean
packaging
Grouping, hazmat, fragile, and padding rules.
PackagingRulesInput
PackagingRulesInput Expand
group
Group identifier. Items sharing the same group id are governed by groupMode.
string
groupMode
keepTogether packs the entire group in the same bin (or leaves all unplaced); separate isolates the group to its own bins. Defaults to keepTogether when group is set.
Values: keepTogether, separate
GroupMode
GroupMode Expand
No documented properties.
hazmat
Marks item as hazardous; requires allowHazmat=true on bins.
boolean
fragile
Marks item as fragile; prevents stacking weight above.
boolean
nestable
When false, this item cannot be nested inside other items. Defaults to true.
boolean
nesting
Defines an internal cavity so other items may be packed inside this item.
NestingRulesInput
NestingRulesInput Expand
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
padding
Clearance added around the item dimensions.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
quantity
When set, total expanded items must remain within plan limits (free 100, paid 1000).
integer
bins
Bin templates to pack into. Maximum bin types per request is plan-dependent (free 50, paid 200).
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowUnplaced
When false, the request fails if any item cannot be placed. Defaults to true.
boolean
objective
Packing objective (speed, bins used, placed count, waste minimization, cost, or shipping). minCost requires bin cost values; shipping requires bin shipping profiles. Defaults to 'fast'.
Values: fast, minBins, maxPlaced, minWaste, minCost, shipping
string
shippingObjective
Weights for shipping-aware optimization. Used when objective=shipping; can also tune shipping scoring while using other objectives.
ShippingObjectiveInput
ShippingObjectiveInput Expand
costWeight
Weight applied to cost in the shipping objective.
number (double)
carbonWeight
Weight applied to carbon impact in the shipping objective.
number (double)
slaWeight
Weight applied to SLA days in the shipping objective (lower is better).
number (double)
dimWeightDivisor
Override bin shipping dimWeightDivisor for optimization.
number (double)
palletization
Two-stage packing (items->pallets->containers). Returns pallet results and split assignments. (Paid plan only)
PalletizationInput Pro only
PalletizationInput Expand
pallets
Pallet templates used for the first packing stage.
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowMixedContainers
When false, all pallets must fit a single container template.
boolean
includeInstructions
If true, returns step-by-step packing instructions for each bin. (Paid plan only) Defaults to false.
boolean Pro only
labelFormat
If 'zpl', generates a ZPL label string for each bin. (Paid plan only) Defaults to 'none'.
Values: none, zpl
string Pro only
nestingStrategy
Controls pre-pack nesting. auto uses the main objective to decide nesting; maximize fills cavities first; none disables nesting. Defaults to 'auto'.
Values: auto, maximize, none
string
Responses
200 Packing result. (PackResponse)
400 Invalid payload or limits exceeded. (ErrorResponse)
401 Missing or invalid API key. (ErrorResponse)
402 Usage exceeded. (ErrorResponse)
403 Forbidden. (ErrorResponse)
408 Request timeout.
429 Rate limited. (ErrorResponse)
502 Upstream auth provider error. (ErrorResponse)
Response schema
PackResponse 200
Expand
bins
Packed bins (containers) with placements.
array<BinResult> Required
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
pallets
Packed pallets when palletization is enabled.
array<BinResult>
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
unplaced
Items that could not be placed.
array<UnplacedItem> Required
Array of UnplacedItem Expand
itemId
Item identifier.
string Required
w
Item width.
number (double) Required
h
Item height.
number (double) Required
d
Item depth.
number (double) Required
weight
Item weight.
number (double)
reason
Reason code for why the item was not placed (e.g., no_fit, pallet_unplaced).
string Required
unplacedPallets
Pallets that could not be placed into containers.
array<UnplacedPallet>
Array of UnplacedPallet Expand
palletId
Pallet instance id.
string Required
reason
Reason code for why the pallet was not placed.
string Required
splits
Item-to-container assignments with pallet audit trails.
array<SplitAssignment>
Array of SplitAssignment Expand
itemId
Item identifier.
string Required
binId
Container/bin identifier where the item ultimately lands.
string Required
palletId
Pallet identifier if palletization was used.
string
stats
PackStats Required
PackStats Expand
items
Total items requested (after quantity expansion).
integer Required
placed
Number of items successfully placed.
integer Required
unplaced
Number of items not placed.
integer Required
nested
Number of items nested inside other items.
integer
binsUsed
Number of bins used.
integer Required
palletsUsed
Number of pallets used (if palletization enabled).
integer
durationMs
Packing duration in milliseconds.
integer (int64) Required
requestId
Echoed request id when provided.
string
Response schema
ErrorResponse 400, 401, 402, 403, 429, 502
Expand
error
ErrorBody Required
ErrorBody Expand
code
Machine-readable error code.
string Required
message
Human-readable error message.
string Required
requestId
Request identifier when provided.
string
Request 
{
  "allowUnplaced": true,
  "objective": "minBins",
  "items": [
    {
      "id": "item-1",
      "w": 2,
      "h": 2,
      "d": 1,
      "quantity": 2
    }
  ],
  "bins": [
    {
      "id": "small-box",
      "w": 4,
      "h": 3,
      "d": 3,
      "quantity": 1
    }
  ]
}
Response application/json
{
  "bins": [
    {
      "binId": "bin-1",
      "templateId": "small-box",
      "w": 4,
      "h": 3,
      "d": 3,
      "vizUrl": "https://binsolver.com/viz?l=example",
      "utilization": 0.44,
      "placements": [
        {
          "itemId": "item-1#1",
          "x": 0,
          "y": 0,
          "z": 0,
          "w": 2,
          "h": 2,
          "d": 1,
          "rotation": "xyz"
        },
        {
          "itemId": "item-1#2",
          "x": 2,
          "y": 0,
          "z": 0,
          "w": 2,
          "h": 2,
          "d": 1,
          "rotation": "xyz"
        }
      ]
    }
  ],
  "unplaced": [],
  "stats": {
    "items": 2,
    "placed": 2,
    "unplaced": 0,
    "binsUsed": 1,
    "durationMs": 3
  }
}

Schemas

Types referenced across the API. Click to reveal fields.

PackRequest
View fields
items
Items to pack (expanded by quantity). Maximum items per request is plan-dependent (free 100, paid 1000).
array<ItemInput> Required
Array of ItemInput Expand
id
Optional item identifier. If omitted, the API assigns one.
string
w
Item width (X axis).
number (double) Required
h
Item height (Y axis).
number (double) Required
d
Item depth (Z axis).
number (double) Required
weight
Weight of a single unit of this item (used for load limits and shipping).
number (double)
allowRotation
If true, the item can be rotated 90 degrees on any axis. Defaults to true.
boolean
rotation
Detailed rotation rules (overrides allowRotation when provided).
RotationRulesInput
RotationRulesInput Expand
mode
Rotation strategy. upright/noFlip keep height on Y axis.
Values: any, none, upright, noFlip, axis, custom
RotationMode
RotationMode Expand
No documented properties.
allowAxes
Allowed axis swaps when mode=axis.
RotationAxes
RotationAxes Expand
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
allowed
Allowed explicit rotations when mode=custom.
Values: xyz, xzy, yxz, yzx, zxy, zyx
array<string>
stacking
Stacking constraints for stability and load.
StackingRulesInput
StackingRulesInput Expand
minSupportRatio
Minimum supported base area ratio (0..1).
number (double)
minSupportArea
Minimum supported base area (absolute units).
number (double)
maxLoad
Maximum load this item can support above it.
number (double)
maxStackHeight
Maximum stacked height above this item.
number (double)
requireCogSupport
Require center-of-gravity to be supported.
boolean
packaging
Grouping, hazmat, fragile, and padding rules.
PackagingRulesInput
PackagingRulesInput Expand
group
Group identifier. Items sharing the same group id are governed by groupMode.
string
groupMode
keepTogether packs the entire group in the same bin (or leaves all unplaced); separate isolates the group to its own bins. Defaults to keepTogether when group is set.
Values: keepTogether, separate
GroupMode
GroupMode Expand
No documented properties.
hazmat
Marks item as hazardous; requires allowHazmat=true on bins.
boolean
fragile
Marks item as fragile; prevents stacking weight above.
boolean
nestable
When false, this item cannot be nested inside other items. Defaults to true.
boolean
nesting
Defines an internal cavity so other items may be packed inside this item.
NestingRulesInput
NestingRulesInput Expand
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
padding
Clearance added around the item dimensions.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
quantity
When set, total expanded items must remain within plan limits (free 100, paid 1000).
integer
bins
Bin templates to pack into. Maximum bin types per request is plan-dependent (free 50, paid 200).
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowUnplaced
When false, the request fails if any item cannot be placed. Defaults to true.
boolean
objective
Packing objective (speed, bins used, placed count, waste minimization, cost, or shipping). minCost requires bin cost values; shipping requires bin shipping profiles. Defaults to 'fast'.
Values: fast, minBins, maxPlaced, minWaste, minCost, shipping
string
shippingObjective
Weights for shipping-aware optimization. Used when objective=shipping; can also tune shipping scoring while using other objectives.
ShippingObjectiveInput
ShippingObjectiveInput Expand
costWeight
Weight applied to cost in the shipping objective.
number (double)
carbonWeight
Weight applied to carbon impact in the shipping objective.
number (double)
slaWeight
Weight applied to SLA days in the shipping objective (lower is better).
number (double)
dimWeightDivisor
Override bin shipping dimWeightDivisor for optimization.
number (double)
palletization
Two-stage packing (items->pallets->containers). Returns pallet results and split assignments. (Paid plan only)
PalletizationInput Pro only
PalletizationInput Expand
pallets
Pallet templates used for the first packing stage.
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowMixedContainers
When false, all pallets must fit a single container template.
boolean
includeInstructions
If true, returns step-by-step packing instructions for each bin. (Paid plan only) Defaults to false.
boolean Pro only
labelFormat
If 'zpl', generates a ZPL label string for each bin. (Paid plan only) Defaults to 'none'.
Values: none, zpl
string Pro only
nestingStrategy
Controls pre-pack nesting. auto uses the main objective to decide nesting; maximize fills cavities first; none disables nesting. Defaults to 'auto'.
Values: auto, maximize, none
string
ItemInput
View fields
id
Optional item identifier. If omitted, the API assigns one.
string
w
Item width (X axis).
number (double) Required
h
Item height (Y axis).
number (double) Required
d
Item depth (Z axis).
number (double) Required
weight
Weight of a single unit of this item (used for load limits and shipping).
number (double)
allowRotation
If true, the item can be rotated 90 degrees on any axis. Defaults to true.
boolean
rotation
Detailed rotation rules (overrides allowRotation when provided).
RotationRulesInput
RotationRulesInput Expand
mode
Rotation strategy. upright/noFlip keep height on Y axis.
Values: any, none, upright, noFlip, axis, custom
RotationMode
RotationMode Expand
No documented properties.
allowAxes
Allowed axis swaps when mode=axis.
RotationAxes
RotationAxes Expand
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
allowed
Allowed explicit rotations when mode=custom.
Values: xyz, xzy, yxz, yzx, zxy, zyx
array<string>
stacking
Stacking constraints for stability and load.
StackingRulesInput
StackingRulesInput Expand
minSupportRatio
Minimum supported base area ratio (0..1).
number (double)
minSupportArea
Minimum supported base area (absolute units).
number (double)
maxLoad
Maximum load this item can support above it.
number (double)
maxStackHeight
Maximum stacked height above this item.
number (double)
requireCogSupport
Require center-of-gravity to be supported.
boolean
packaging
Grouping, hazmat, fragile, and padding rules.
PackagingRulesInput
PackagingRulesInput Expand
group
Group identifier. Items sharing the same group id are governed by groupMode.
string
groupMode
keepTogether packs the entire group in the same bin (or leaves all unplaced); separate isolates the group to its own bins. Defaults to keepTogether when group is set.
Values: keepTogether, separate
GroupMode
GroupMode Expand
No documented properties.
hazmat
Marks item as hazardous; requires allowHazmat=true on bins.
boolean
fragile
Marks item as fragile; prevents stacking weight above.
boolean
nestable
When false, this item cannot be nested inside other items. Defaults to true.
boolean
nesting
Defines an internal cavity so other items may be packed inside this item.
NestingRulesInput
NestingRulesInput Expand
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
padding
Clearance added around the item dimensions.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
quantity
When set, total expanded items must remain within plan limits (free 100, paid 1000).
integer
BinInput
View fields
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
PackResponse
View fields
bins
Packed bins (containers) with placements.
array<BinResult> Required
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
pallets
Packed pallets when palletization is enabled.
array<BinResult>
Array of BinResult Expand
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
unplaced
Items that could not be placed.
array<UnplacedItem> Required
Array of UnplacedItem Expand
itemId
Item identifier.
string Required
w
Item width.
number (double) Required
h
Item height.
number (double) Required
d
Item depth.
number (double) Required
weight
Item weight.
number (double)
reason
Reason code for why the item was not placed (e.g., no_fit, pallet_unplaced).
string Required
unplacedPallets
Pallets that could not be placed into containers.
array<UnplacedPallet>
Array of UnplacedPallet Expand
palletId
Pallet instance id.
string Required
reason
Reason code for why the pallet was not placed.
string Required
splits
Item-to-container assignments with pallet audit trails.
array<SplitAssignment>
Array of SplitAssignment Expand
itemId
Item identifier.
string Required
binId
Container/bin identifier where the item ultimately lands.
string Required
palletId
Pallet identifier if palletization was used.
string
stats
PackStats Required
PackStats Expand
items
Total items requested (after quantity expansion).
integer Required
placed
Number of items successfully placed.
integer Required
unplaced
Number of items not placed.
integer Required
nested
Number of items nested inside other items.
integer
binsUsed
Number of bins used.
integer Required
palletsUsed
Number of pallets used (if palletization enabled).
integer
durationMs
Packing duration in milliseconds.
integer (int64) Required
requestId
Echoed request id when provided.
string
BinResult
View fields
binId
Instance id for the packed bin.
string Required
templateId
Template id from the request.
string Required
w
Bin width.
number (double) Required
h
Bin height.
number (double) Required
d
Bin depth.
number (double) Required
weight
Total weight of items in this bin.
number (double)
shipping
Shipping cost/weight metrics for the packed bin (if shipping profile provided).
ShippingResult
ShippingResult Expand
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
vizUrl
URL to replay this bin packing result in the BinSolver visualizer.
string (uri) Required
utilization
Volume utilization of the bin (0.0 to 1.0).
number (double) Required
placements
Item placements in this bin.
array<Placement> Required
Array of Placement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
instructions
Step-by-step packing instructions (if requested).
array<string>
label
Generated label code (e.g. ZPL) for the bin (if requested).
string
Placement
View fields
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin.
number (double) Required
y
Y coordinate of the placement origin.
number (double) Required
z
Z coordinate of the placement origin.
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
nested
Items packed inside this item (if nesting was used). Coordinates are relative to the item's local origin.
array<NestedPlacement>
Array of NestedPlacement Expand
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
NestedPlacement
View fields
itemId
Item identifier for this placement.
string Required
x
X coordinate of the placement origin (relative to container).
number (double) Required
y
Y coordinate of the placement origin (relative to container).
number (double) Required
z
Z coordinate of the placement origin (relative to container).
number (double) Required
w
Packed width (includes item padding if provided).
number (double) Required
h
Packed height (includes item padding if provided).
number (double) Required
d
Packed depth (includes item padding if provided).
number (double) Required
rotation
Applied rotation permutation.
Values: xyz, xzy, yxz, yzx, zxy, zyx
string Required
UnplacedItem
View fields
itemId
Item identifier.
string Required
w
Item width.
number (double) Required
h
Item height.
number (double) Required
d
Item depth.
number (double) Required
weight
Item weight.
number (double)
reason
Reason code for why the item was not placed (e.g., no_fit, pallet_unplaced).
string Required
UnplacedPallet
View fields
palletId
Pallet instance id.
string Required
reason
Reason code for why the pallet was not placed.
string Required
SplitAssignment
View fields
itemId
Item identifier.
string Required
binId
Container/bin identifier where the item ultimately lands.
string Required
palletId
Pallet identifier if palletization was used.
string
ShippingResult
View fields
billableWeight
max(actual weight, dimensional weight).
number (double) Required
dimensionalWeight
Dimensional weight computed from bin volume and divisor.
number (double) Required
cost
Estimated shipping cost.
number (double) Required
carbon
Estimated carbon impact.
number (double) Required
slaDays
Estimated delivery time in days.
number (double) Required
RotationRulesInput
Controls which rotations are allowed for this item.
View fields
mode
Rotation strategy. upright/noFlip keep height on Y axis.
Values: any, none, upright, noFlip, axis, custom
RotationMode
RotationMode Expand
No documented properties.
allowAxes
Allowed axis swaps when mode=axis.
RotationAxes
RotationAxes Expand
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
allowed
Allowed explicit rotations when mode=custom.
Values: xyz, xzy, yxz, yzx, zxy, zyx
array<string>
RotationMode
Rotation mode selector.
View fields
No documented properties.
RotationAxes
Allowed axis swaps for axis-specific rotation control.
View fields
xy
Allow swapping X and Y.
boolean
xz
Allow swapping X and Z.
boolean
yz
Allow swapping Y and Z.
boolean
StackingRulesInput
Stability and stacking constraints for this item.
View fields
minSupportRatio
Minimum supported base area ratio (0..1).
number (double)
minSupportArea
Minimum supported base area (absolute units).
number (double)
maxLoad
Maximum load this item can support above it.
number (double)
maxStackHeight
Maximum stacked height above this item.
number (double)
requireCogSupport
Require center-of-gravity to be supported.
boolean
PackagingRulesInput
Packaging and compatibility constraints.
View fields
group
Group identifier. Items sharing the same group id are governed by groupMode.
string
groupMode
keepTogether packs the entire group in the same bin (or leaves all unplaced); separate isolates the group to its own bins. Defaults to keepTogether when group is set.
Values: keepTogether, separate
GroupMode
GroupMode Expand
No documented properties.
hazmat
Marks item as hazardous; requires allowHazmat=true on bins.
boolean
fragile
Marks item as fragile; prevents stacking weight above.
boolean
nestable
When false, this item cannot be nested inside other items. Defaults to true.
boolean
nesting
Defines an internal cavity so other items may be packed inside this item.
NestingRulesInput
NestingRulesInput Expand
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
padding
Clearance added around the item dimensions.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
NestingRulesInput
Internal cavity definition for nesting.
View fields
innerW
Inner cavity width (X axis).
number (double) Required
innerH
Inner cavity height (Y axis).
number (double) Required
innerD
Inner cavity depth (Z axis).
number (double) Required
padding
Clearance between nested items and cavity walls.
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
maxWeight
Maximum total weight allowed inside this cavity.
number (double)
allowHazmat
If false, hazmat items cannot be nested inside this cavity. Defaults to true.
boolean
allowedGroups
If set, only items whose packaging.group is in this list may be nested.
array<string>
GroupMode
Grouping mode for items sharing the same group id. groupMode without group is invalid.
View fields
No documented properties.
PaddingInput
Padding/clearance values (all sets defaults for x/y/z).
View fields
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
ShippingInput
Shipping profile for a bin or container.
View fields
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
ShippingObjectiveInput
Weights used to score shipping tradeoffs during optimization.
View fields
costWeight
Weight applied to cost in the shipping objective.
number (double)
carbonWeight
Weight applied to carbon impact in the shipping objective.
number (double)
slaWeight
Weight applied to SLA days in the shipping objective (lower is better).
number (double)
dimWeightDivisor
Override bin shipping dimWeightDivisor for optimization.
number (double)
PalletizationInput
Two-stage packing: items -> pallets -> containers.
View fields
pallets
Pallet templates used for the first packing stage.
array<BinInput> Required
Array of BinInput Expand
id
Optional bin identifier. If omitted, the API assigns one.
string
w
Bin width (X axis).
number (double) Required
h
Bin height (Y axis).
number (double) Required
d
Bin depth (Z axis).
number (double) Required
maxWeight
Maximum weight capacity of this bin (sum of item weights).
number (double)
cost
Cost of using this bin (required for minCost objective).
number (double)
tareWeight
Empty weight of the bin or pallet (added to shipment weight).
number (double)
allowHazmat
If false, hazmat items cannot be placed in this bin. Defaults to true.
boolean
padding
Clearance between items and bin walls (shrinks usable interior).
PaddingInput
PaddingInput Expand
all
Uniform padding on all axes.
number (double)
x
Padding on the X axis.
number (double)
y
Padding on the Y axis.
number (double)
z
Padding on the Z axis.
number (double)
shipping
Shipping profile for this bin (required for objective=shipping).
ShippingInput
ShippingInput Expand
baseCost
Fixed cost per shipment for this bin.
number (double)
ratePerWeight
Variable cost per unit of billable weight.
number (double)
dimWeightDivisor
Divisor for dimensional weight (volume / divisor).
number (double)
carbonPerWeight
Carbon cost per unit of billable weight.
number (double)
slaDays
Estimated delivery time for this bin.
number (double)
quantity
When set, must not exceed plan limits (free 100, paid 1000).
integer
allowMixedContainers
When false, all pallets must fit a single container template.
boolean
PackStats
View fields
items
Total items requested (after quantity expansion).
integer Required
placed
Number of items successfully placed.
integer Required
unplaced
Number of items not placed.
integer Required
nested
Number of items nested inside other items.
integer
binsUsed
Number of bins used.
integer Required
palletsUsed
Number of pallets used (if palletization enabled).
integer
durationMs
Packing duration in milliseconds.
integer (int64) Required
requestId
Echoed request id when provided.
string
ErrorResponse
View fields
error
ErrorBody Required
ErrorBody Expand
code
Machine-readable error code.
string Required
message
Human-readable error message.
string Required
requestId
Request identifier when provided.
string
ErrorBody
View fields
code
Machine-readable error code.
string Required
message
Human-readable error message.
string Required
requestId
Request identifier when provided.
string

Errors

Errors follow a consistent JSON envelope with a code, message, and optional request id for tracing.

Error body
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "requestId": "req_3f2e9d"
  }
}
Status codes
400 Invalid payload or limits exceeded.
401 Missing or invalid API key.
402 Usage exceeded.
403 Forbidden.
408 Request timeout.
429 Rate limited.
502 Upstream auth provider error.