StoaPack API reference
Request fields and defaults
no_upright_fit is an unfitted reason: unit fits only when rotated
off its upright axis; orientation is upright. There is no sideways fallback.
With nesting enabled, packing_solution.nesting_fallbacks explains
upright units packed separately because they would fit a container only when tipped.
Reason no_upright_fit_in_container includes item_id,
container_id, quantity per item/container pair and
action pack_without_nesting. Other nesting restrictions are not
reported as orientation failures.
/api/v1.1/optimize and /api/v1/optimize
are aliases for the same current contract and engine, not different feature sets.
Use v1.1 for new integrations; v1 remains a supported compatibility route.
UN inputs accept UN3139, UN 3139,
UN-3139 or 3139, case-insensitively, and normalize to
UN3139. A single space or hyphen may separate the prefix from four
contiguous ASCII digits; internal separators are rejected. Malformed numbers
return 400. Syntax normalization does not establish classification or transport
coverage. Quantity-reference-only substances remain unverified for classification.
| Field | Type / default | Requirement or example |
|---|---|---|
Item id | String | Required, nonempty, at most 128 characters; "cube". |
width, height, depth | Number / request length unit | Required positive dimensions for boxed items. |
Item weight | Number / request mass unit | Required; zero or more, no default. |
quantity | Integer / 1 | Positive physical-unit count. |
Item orientation | "any" (default) or "upright" | "upright" keeps the item's height vertical; it may still turn on its base. Nested contents use container-local axes. |
Warehouse inventory | Object / all counts zero | Stock at that site, such as {"cube":2}. |
available_boxes | Array / no default | Required box IDs, dimensions, quantity and weight limits. |
Box max_weight | Number / request mass unit | Required positive capacity. |
Box cost | Number / optional | Currency-agnostic carton cost, for example 0.50. Use the same currency for every box. Supply costs explicitly when selecting minimize_cost; these are not carrier rates. |
Box fill_percentage | Number / 100 percent | 80 reserves 20% of volume; geometry and mass limits remain. |
unit / weight_unit | String / cm / g | Lengths: cm or in. Masses: g, kg, oz or lb; also applies to box limits. |
optimization_goal | String / minimize_boxes | See the schema above for every allowed goal. |
ai_review | Boolean / false | true requests AI review, with separate quotas and possible added latency. |
shipping_mode | String / ground | ground: supported ground checks; air: only enforced air coverage; sea: accepted mode, but hazmat sea coverage is unsupported (422). |
Pallet packing — contract 1.4.0
Use the same POST /api/v1.1/optimize endpoint for pallet loads.
Set kind:"pallet" on each pallet in a warehouse's
available_boxes. Omitting kind means "carton".
Do not mix cartons and pallets in the same warehouse catalog.
For a pallet, width and depth describe the deck.
height is the maximum usable load height, and max_weight
is the case-load weight limit in the request's weight_unit.
Stock, fill limits, warehouse inventory and keep-upright controls still apply.
Options
The optional request-level pallet_options object accepts only these fields.
Distances use the request's unit.
| Field | Default | Behavior |
|---|---|---|
mix_skus_in_layer | true | Allow different products in the same layer. |
height_tolerance | 0 | Allowed case-height difference in a mixed layer; at most 5 cm, or its equivalent in inches. |
prefer_single_sku_pallets | true | Prefer grouping full layers of the same product. This is a search preference, not an optimality guarantee. |
max_cog_offset_pct | 10% | Center-of-gravity balance target on each horizontal axis, as a percentage of that deck dimension. The engine attempts to rebalance the top layer and reports cog_offset_high if the target is still exceeded. |
Synchronous limits
When every available box in every warehouse has kind:"pallet",
the limits are 1,000 physical units,
40 item types, 5 warehouses,
25 pallet types, 200 pallet
instances and 1,048,576 request bytes.
Work is bounded by item types × pallet types, capped at
100,000.
Other requests retain parcel limits of 80 units and
262,144 bytes.
The execution budget remains 2 seconds;
being within the size limits does not guarantee completion within that budget.
Pallet mode cannot be combined with enable_nesting:true.
Pallet packing jobs are not supported; use synchronous optimize.
Invalid combinations return 400, size/work limits return 413 or 422,
and exhausted execution capacity returns a retryable 503.
Request example
{
"items": [
{
"depth": 20,
"height": 20,
"id": "case",
"orientation": "upright",
"quantity": 12,
"weight": 10,
"width": 30
}
],
"pallet_options": {
"height_tolerance": 0,
"max_cog_offset_pct": 10,
"mix_skus_in_layer": true,
"prefer_single_sku_pallets": true
},
"unit": "cm",
"warehouses": [
{
"available_boxes": [
{
"cost": 10,
"depth": 100,
"height": 150,
"id": "pallet",
"kind": "pallet",
"max_weight": 1000,
"quantity": 5,
"width": 120
}
],
"id": "main",
"inventory": {
"case": 12
}
}
],
"weight_unit": "kg"
}
Reading the result
Each pallet appears in
solution.warehouses[].packing_solution.boxes[] with kind:"pallet",
the usual packed_items positions and a pallet object.
That object contains load_height, layers,
cases_per_full_layer, cog, cog_offset_pct,
heavy_over_light and min_support.
Layer entries describe their base, height, product counts, coverage and pattern.
A fallback leftover level has kind:"leftover" and
case_unit_ids listing its cases.
min_support is the lowest measured base-contact fraction.
Full same-product/pattern columns require 100% support; other placements require
at least 75%. Base contact does not certify load-bearing strength or transport stability.
The search is bounded, not a guarantee of the globally smallest pallet count.
Package warnings include partial_top_layer, mixed_layer,
mixed_leftovers (informational), cog_offset_high and
heavy_over_light.
exceeds_load_height identifies a case too tall in every allowed
orientation; other unfitted reasons still distinguish mass, fill, stock and orientation.
Requested image steps advance one pallet layer at a time.
Rate limits and response metadata
Rates depend on the key and plan. Response rate metadata and live readiness
describe the effective allowance. Approved corporate accounts are exempt from minute limits.
For 429 or 503, use retryable and Retry-After;
metadata.rejection_reason distinguishes rate and capacity rejections.
Body timing measures application work, not end-to-end network latency.
Large orders can hit the packing time limit even within size limits; split them
if needed. Busy admission can reject large orders first to reserve small-order
capacity. Failed calls use no optimization balance.
See capacity and rate-control details.
For compatibility, a data-quality warning can appear in both
hazmat_summary.warnings and quantity_warnings.
The same item-scoped message identifies one issue, not two.
Packing guides print that diagnostic once.
Complete checked response
Checked offline with the packing engine. IDs and times vary.
{
"success": true,
"solution": {
"warehouses": [
{
"id": "east",
"items_fulfilled": [
{
"id": "cube",
"quantity": 2
}
],
"packing_solution": {
"boxes": [
{
"id": "pkg_east_row_f4247360",
"box_id": "row",
"warehouse_id": "east",
"utilization": 1.0,
"fill_percentage": 100.0,
"real_utilization": 1.0,
"packed_items": [
{
"id": "cube",
"quantity": 1,
"position": {
"x": 0.0,
"y": 0.0,
"z": 0.0
},
"rotation": 0,
"dimensions": {
"width": 10,
"height": 10,
"depth": 10
},
"placed_dimensions": {
"width": 10.0,
"height": 10.0,
"depth": 10.0
},
"unit_id": "east:cube:physical-0"
},
{
"id": "cube",
"quantity": 1,
"position": {
"x": 10.0,
"y": 0.0,
"z": 0.0
},
"rotation": 0,
"dimensions": {
"width": 10,
"height": 10,
"depth": 10
},
"placed_dimensions": {
"width": 10.0,
"height": 10.0,
"depth": 10.0
},
"unit_id": "east:cube:physical-1"
}
],
"dimensions": {
"width": 20.0,
"height": 10.0,
"depth": 10.0
},
"adjusted_dimensions": {
"width": 20.0,
"height": 10.0,
"depth": 10.0
}
}
],
"unboxed_items": [],
"oversized_items": [],
"oversized_items_details": [],
"unfitted_items": [],
"unfitted_items_details": []
}
}
],
"unavailable_items": [],
"unfulfilled_items": [],
"optimization_goal": "minimize_boxes",
"unfitted_outcomes": []
},
"ai_generated": false,
"constraints_applied": false,
"processing_time": 0.0022509098052978516,
"timing": {
"packing_algorithm_ms": 2.18,
"usage_writes_ms": 0.0,
"total_ms": 2.42
},
"metadata": {
"optimization_goal": "minimize_boxes",
"api_version": "1.4.0",
"service": "StoaPack",
"request_id": "00000000-0000-4000-8000-000000000000",
"processing_time": 0.0024251937866210938,
"boxes_count": 1
}
}Route-specific error codes
Read status, code and retryable together.
The same status can identify different failures.
- 400:
validation_error,request_error,numeric_range,unknown_field. - 401:
request_errorfor missing or invalid authorization. 403:jobs_not_approvedfor unapproved async access. - 413:
body_too_large. 422:work_budget_exceeded,unsupported_coverage,review_requirements_not_met. - 429:
rate_limited. 502:provider_error. - 503:
capacity_full,capacity_reserved_small_orders,ingress_full,admission_busy,admission_timeout,admission_unavailable, orauthorization_unavailable.jobs_worker_unavailableis non-retryable when no worker has been observed; a recently missed worker heartbeat is retryable. Honor the response'sRetry-Afteronly when retryable.
Glossary
- Unit
- One physical item.
- Type
- One item or box definition.
- Stock
- Count available at a warehouse.
- Package
- One shipping box with its contents.
- Utilization
- Used volume divided by box volume.
- Fill limit
- Allowed share of box volume.
- Nested
- Placed inside another item.
- Unfitted
- In stock but left unpacked.
- Unavailable
- Missing from stock.
- Backoff
- Wait longer after each retry.
Packing images (optional)
Add render to an optimize request for SVG box views, numbered steps
or printable packing guides. Geometry and sequence come from the returned plan.
"render": {"format":"svg","views":["box","steps","sheet"],"labels":"numbers","sheet":{"size":"4x6"}}
Sheets support Letter, A4 and 4×6 thermal sizes. Standard and monochrome palettes are available; the brand palette is not colorblind-safe. Hazmat markers reflect verified metadata; unknown UNs remain unverified. These guides are neither shipping labels nor regulatory hazmat markings.
Use a box's signed render_ref with authenticated
POST /api/v1/render for a separate SVG or PNG download.
Inline PNG is rejected. Image work has separate capacity and rate control;
render_busy is retryable, while expired references require a new
packing request. Check metadata.render for skipped optional output
and use the reference for options and errors.