Current contract 1.4.0. These are route aliases for the same current engine, not archived releases. The latest contract is selected by default; its examples use the supported /api/v1.1 URL. A contract version is not a new URL prefix.

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

FieldType / defaultRequirement or example
Item idStringRequired, nonempty, at most 128 characters; "cube".
width, height, depthNumber / request length unitRequired positive dimensions for boxed items.
Item weightNumber / request mass unitRequired; zero or more, no default.
quantityInteger / 1Positive 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 inventoryObject / all counts zeroStock at that site, such as {"cube":2}.
available_boxesArray / no defaultRequired box IDs, dimensions, quantity and weight limits.
Box max_weightNumber / request mass unitRequired positive capacity.
Box costNumber / optionalCurrency-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_percentageNumber / 100 percent80 reserves 20% of volume; geometry and mass limits remain.
unit / weight_unitString / cm / gLengths: cm or in. Masses: g, kg, oz or lb; also applies to box limits.
optimization_goalString / minimize_boxesSee the schema above for every allowed goal.
ai_reviewBoolean / falsetrue requests AI review, with separate quotas and possible added latency.
shipping_modeString / groundground: 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.

FieldDefaultBehavior
mix_skus_in_layertrueAllow different products in the same layer.
height_tolerance0Allowed case-height difference in a mixed layer; at most 5 cm, or its equivalent in inches.
prefer_single_sku_palletstruePrefer grouping full layers of the same product. This is a search preference, not an optimality guarantee.
max_cog_offset_pct10%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_error for missing or invalid authorization. 403: jobs_not_approved for 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, or authorization_unavailable. jobs_worker_unavailable is non-retryable when no worker has been observed; a recently missed worker heartbeat is retryable. Honor the response's Retry-After only 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.