Core Concepts

Multi-Warehouse Optimization

Most packing APIs assume a single warehouse. StoaPack handles the real-world scenario: your inventory is spread across locations, and each warehouse has its own set of box sizes.

When you send a request with multiple warehouses, StoaPack figures out which warehouse ships which items and optimizes for the fewest total packages across all locations. If an item exists in two warehouses, StoaPack picks the one that produces better packing.

{
  "items": [
    { "item_id": "ITEM-A", "width": 6, "height": 4, "length": 8, "weight": 2, "quantity": 2 },
    { "item_id": "ITEM-B", "width": 10, "height": 6, "length": 12, "weight": 5, "quantity": 1 }
  ],
  "warehouses": [
    {
      "warehouse_id": "WH-EAST",
      "boxes": [
        { "box_id": "MEDIUM", "width": 16, "height": 12, "length": 18, "max_weight": 30, "quantity": 50 }
      ],
      "inventory": { "ITEM-A": 5 }
    },
    {
      "warehouse_id": "WH-WEST",
      "boxes": [
        { "box_id": "LARGE", "width": 20, "height": 14, "length": 22, "max_weight": 40, "quantity": 30 }
      ],
      "inventory": { "ITEM-A": 3, "ITEM-B": 10 }
    }
  ],
  "units": "in"
}

In this example, ITEM-A is available at both warehouses. StoaPack decides which warehouse handles which units to minimize total boxes shipped.

Optimization Goals

By default, StoaPack minimizes the number of boxes. You can change this by setting the optimization_goal parameter:

{
  "items": [ ... ],
  "warehouses": [ ... ],
  "units": "in",
  "optimization_goal": "minimize_volume"
}

Box Inventory & Availability

Each warehouse defines its own set of available boxes, each with a quantity. StoaPack won't suggest a box type you've run out of.

If a warehouse has 5 SMALL boxes and 2 LARGE boxes, StoaPack respects those limits. If your items need 6 SMALL boxes, StoaPack will use all 5 SMALL boxes and overflow into LARGE (or another available size).

"boxes": [
  {
    "box_id": "SMALL",
    "width": 12, "height": 10, "length": 14,
    "max_weight": 25,
    "quantity": 5
  },
  {
    "box_id": "LARGE",
    "width": 24, "height": 18, "length": 20,
    "max_weight": 50,
    "quantity": 2
  }
]

AI Custom Instructions

The custom_instructions parameter lets you express packing rules in plain English that are hard to encode as parameters. StoaPack runs the optimization first, then uses AI to review and adjust the solution based on your instructions.

{
  "items": [ ... ],
  "warehouses": [ ... ],
  "units": "in",
  "custom_instructions": "Keep all fragile items in separate boxes from heavy items. Prefer smaller boxes even if it means more packages."
}

Practical use cases:

• Separate fragile items from heavy ones
• Keep product bundles together in the same box
• Prioritize a specific warehouse for certain items
• Add padding rules for specific item categories

Nested Packing

Some items have internal space (bins, baskets, organizers). StoaPack can pack smaller items inside these containers before placing them in shipping boxes. Define nested capacity using the inner_dimensions field on an item:

{
  "item_id": "BASKET-01",
  "width": 14,
  "height": 10,
  "length": 16,
  "weight": 1.5,
  "quantity": 2,
  "inner_dimensions": {
    "width": 12,
    "height": 8,
    "length": 14
  }
}

When StoaPack sees an item with inner_dimensions, it first tries to fit smaller items inside the container, then packs the container (with its contents) into a shipping box.

Hazmat & Compliance

StoaPack enforces hazardous materials segregation per 49 CFR (ground transport) and IATA DGR (air transport). Tag items with their hazmat classification and StoaPack handles the rest:

{
  "item_id": "SOLVENT-X",
  "width": 4,
  "height": 6,
  "length": 4,
  "weight": 3.0,
  "quantity": 2,
  "hazmat": {
    "un_number": "UN1993",
    "hazard_class": "3",
    "packing_group": "III",
    "proper_shipping_name": "Flammable liquid, n.o.s."
  }
}

StoaPack will:

• Never pack incompatible hazard classes in the same box
• Enforce quantity limits per package (Q-value calculations for air)
• Apply conservative safety margins
• Flag violations in the response rather than silently ignoring them

Fragile Items

Use fill_percentage (1–100) to limit how full a box can be when it contains fragile items. A fill percentage of 70 means StoaPack leaves 30% of box volume as padding space.

{
  "item_id": "GLASS-VASE",
  "width": 6,
  "height": 10,
  "length": 6,
  "weight": 1.8,
  "quantity": 4,
  "fragile": true,
  "fill_percentage": 70
}

Units

Set "units": "in" for inches/pounds or "units": "cm" for centimeters/kilograms. This applies to all dimensions and weights in the request and response. The default is inches.