Guides
Examples
Real-world scenarios with complete request and response JSON. Copy, adapt, and ship.
1. Simple Single-Warehouse Packing
The "hello world" — pack 3 widgets into available boxes at one warehouse.
{
"items": [
{
"item_id": "WIDGET-001",
"width": 6,
"height": 4,
"length": 8,
"weight": 2.5,
"quantity": 3
}
],
"warehouses": [
{
"warehouse_id": "WH-MAIN",
"boxes": [
{
"box_id": "SMALL",
"width": 12,
"height": 10,
"length": 14,
"max_weight": 25,
"quantity": 100
}
],
"inventory": {
"WIDGET-001": 10
}
}
],
"units": "in"
}{
"packages": [
{
"package_id": "pkg_WH-MAIN_SMALL_x7k2m",
"warehouse_id": "WH-MAIN",
"box_id": "SMALL",
"box_dimensions": { "width": 12, "height": 10, "length": 14 },
"items": [
{
"item_id": "WIDGET-001",
"position": { "x": 0, "y": 0, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
},
{
"item_id": "WIDGET-001",
"position": { "x": 6, "y": 0, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
},
{
"item_id": "WIDGET-001",
"position": { "x": 0, "y": 4, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
}
],
"total_weight": 7.5,
"volume_utilization": 0.41
}
],
"summary": {
"total_packages": 1,
"total_items_packed": 3,
"warehouses_used": ["WH-MAIN"]
},
"unfitted_items": []
}All 3 widgets fit in a single SMALL box. The position fields show exactly where each item sits inside the box.
2. Multi-Warehouse with Split Inventory
You have a 3-item order. Item A is only at Warehouse East, Item B is only at Warehouse West, and Item C is at both. StoaPack figures out the optimal split.
{
"items": [
{ "item_id": "BOOK-A", "width": 6, "height": 1, "length": 9, "weight": 0.8, "quantity": 2 },
{ "item_id": "MUG-B", "width": 4, "height": 5, "length": 4, "weight": 1.2, "quantity": 1 },
{ "item_id": "CHARGER-C", "width": 3, "height": 1, "length": 5, "weight": 0.3, "quantity": 4 }
],
"warehouses": [
{
"warehouse_id": "WH-EAST",
"boxes": [
{ "box_id": "FLAT-MD", "width": 14, "height": 4, "length": 10, "max_weight": 15, "quantity": 50 }
],
"inventory": { "BOOK-A": 10, "CHARGER-C": 20 }
},
{
"warehouse_id": "WH-WEST",
"boxes": [
{ "box_id": "CUBE-SM", "width": 10, "height": 10, "length": 10, "max_weight": 20, "quantity": 40 }
],
"inventory": { "MUG-B": 5, "CHARGER-C": 15 }
}
],
"units": "in"
}{
"packages": [
{
"package_id": "pkg_WH-EAST_FLAT-MD_r4t5y",
"warehouse_id": "WH-EAST",
"box_id": "FLAT-MD",
"items": [
{ "item_id": "BOOK-A", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 0.8 },
{ "item_id": "BOOK-A", "position": { "x": 6, "y": 0, "z": 0 }, "weight": 0.8 },
{ "item_id": "CHARGER-C", "position": { "x": 0, "y": 1, "z": 0 }, "weight": 0.3 },
{ "item_id": "CHARGER-C", "position": { "x": 3, "y": 1, "z": 0 }, "weight": 0.3 }
],
"total_weight": 2.2,
"volume_utilization": 0.36
},
{
"package_id": "pkg_WH-WEST_CUBE-SM_u8i9o",
"warehouse_id": "WH-WEST",
"items": [
{ "item_id": "MUG-B", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 1.2 },
{ "item_id": "CHARGER-C", "position": { "x": 4, "y": 0, "z": 0 }, "weight": 0.3 },
{ "item_id": "CHARGER-C", "position": { "x": 7, "y": 0, "z": 0 }, "weight": 0.3 }
],
"total_weight": 1.8,
"volume_utilization": 0.10
}
],
"summary": {
"total_packages": 2,
"total_items_packed": 7,
"warehouses_used": ["WH-EAST", "WH-WEST"]
},
"unfitted_items": []
}StoaPack split the CHARGER-C items across both warehouses to minimize total packages. Books ship from East (the only warehouse that stocks them), mugs from West.
3. Subscription Box Optimization
You're packing 50 identical subscription boxes. Each box gets the same set of items. Find the smallest box that fits everything.
{
"items": [
{ "item_id": "SNACK-BAR", "width": 6, "height": 1, "length": 2, "weight": 0.2, "quantity": 3 },
{ "item_id": "SAMPLE-BOTTLE", "width": 2, "height": 5, "length": 2, "weight": 0.5, "quantity": 2 },
{ "item_id": "INFO-CARD", "width": 5, "height": 0.1, "length": 7, "weight": 0.05, "quantity": 1 }
],
"warehouses": [
{
"warehouse_id": "WH-FULFILLMENT",
"boxes": [
{ "box_id": "SUB-SM", "width": 8, "height": 6, "length": 8, "max_weight": 10, "quantity": 200 },
{ "box_id": "SUB-MD", "width": 10, "height": 8, "length": 10, "max_weight": 15, "quantity": 200 },
{ "box_id": "SUB-LG", "width": 12, "height": 10, "length": 12, "max_weight": 20, "quantity": 200 }
],
"inventory": {
"SNACK-BAR": 500,
"SAMPLE-BOTTLE": 500,
"INFO-CARD": 500
}
}
],
"units": "in",
"optimization_goal": "minimize_volume"
}{
"packages": [
{
"package_id": "pkg_WH-FULFILLMENT_SUB-SM_a2b3c",
"warehouse_id": "WH-FULFILLMENT",
"box_id": "SUB-SM",
"box_dimensions": { "width": 8, "height": 6, "length": 8 },
"items": [
{ "item_id": "SNACK-BAR", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 0.2 },
{ "item_id": "SNACK-BAR", "position": { "x": 6, "y": 0, "z": 0 }, "weight": 0.2 },
{ "item_id": "SNACK-BAR", "position": { "x": 0, "y": 1, "z": 0 }, "weight": 0.2 },
{ "item_id": "SAMPLE-BOTTLE", "position": { "x": 0, "y": 0, "z": 2 }, "weight": 0.5 },
{ "item_id": "SAMPLE-BOTTLE", "position": { "x": 2, "y": 0, "z": 2 }, "weight": 0.5 },
{ "item_id": "INFO-CARD", "position": { "x": 0, "y": 5.9, "z": 0 }, "weight": 0.05 }
],
"total_weight": 1.65,
"volume_utilization": 0.31
}
],
"summary": {
"total_packages": 1,
"total_items_packed": 6,
"warehouses_used": ["WH-FULFILLMENT"]
},
"unfitted_items": []
}With minimize_volume, StoaPack chose the smallest box (SUB-SM) that fits all items. Use this result to know which box size to order for your subscription fulfillment.
4. Fragile + Heavy Items Together
An order with delicate glassware and heavy books. Use fill_percentage to leave padding space for fragile items.
{
"items": [
{
"item_id": "WINE-GLASS",
"width": 4,
"height": 8,
"length": 4,
"weight": 0.6,
"quantity": 4,
"fragile": true,
"fill_percentage": 60
},
{
"item_id": "HARDCOVER-BOOK",
"width": 7,
"height": 2,
"length": 10,
"weight": 3.0,
"quantity": 2
}
],
"warehouses": [
{
"warehouse_id": "WH-CENTRAL",
"boxes": [
{ "box_id": "MEDIUM", "width": 16, "height": 12, "length": 16, "max_weight": 30, "quantity": 50 },
{ "box_id": "LARGE", "width": 20, "height": 16, "length": 20, "max_weight": 50, "quantity": 20 }
],
"inventory": {
"WINE-GLASS": 20,
"HARDCOVER-BOOK": 15
}
}
],
"units": "in"
}{
"packages": [
{
"package_id": "pkg_WH-CENTRAL_MEDIUM_p3q4r",
"warehouse_id": "WH-CENTRAL",
"box_id": "MEDIUM",
"items": [
{ "item_id": "WINE-GLASS", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 0.6, "fragile": true },
{ "item_id": "WINE-GLASS", "position": { "x": 4, "y": 0, "z": 0 }, "weight": 0.6, "fragile": true },
{ "item_id": "WINE-GLASS", "position": { "x": 8, "y": 0, "z": 0 }, "weight": 0.6, "fragile": true },
{ "item_id": "WINE-GLASS", "position": { "x": 12, "y": 0, "z": 0 }, "weight": 0.6, "fragile": true }
],
"total_weight": 2.4,
"volume_utilization": 0.17
},
{
"package_id": "pkg_WH-CENTRAL_MEDIUM_s5t6u",
"warehouse_id": "WH-CENTRAL",
"box_id": "MEDIUM",
"items": [
{ "item_id": "HARDCOVER-BOOK", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 3.0 },
{ "item_id": "HARDCOVER-BOOK", "position": { "x": 7, "y": 0, "z": 0 }, "weight": 3.0 }
],
"total_weight": 6.0,
"volume_utilization": 0.09
}
],
"summary": {
"total_packages": 2,
"total_items_packed": 6,
"warehouses_used": ["WH-CENTRAL"]
},
"unfitted_items": []
}The fragile wine glasses get their own box with 40% empty space left for padding material. The heavy books are packed separately. The fill_percentage: 60 means StoaPack only fills 60% of the box volume when fragile items are present.
5. AI-Powered Custom Rules
Beta feature. Each AI review request counts against your plan's AI review quota.
Use plain-English instructions to enforce business logic that's hard to express as parameters. Here, we tell StoaPack to keep product bundles together.
{
"items": [
{ "item_id": "SHAMPOO", "width": 3, "height": 8, "length": 3, "weight": 1.0, "quantity": 2 },
{ "item_id": "CONDITIONER", "width": 3, "height": 8, "length": 3, "weight": 1.0, "quantity": 2 },
{ "item_id": "BODY-WASH", "width": 3, "height": 9, "length": 3, "weight": 1.2, "quantity": 2 },
{ "item_id": "LOOFAH", "width": 5, "height": 2, "length": 5, "weight": 0.1, "quantity": 2 }
],
"warehouses": [
{
"warehouse_id": "WH-BEAUTY",
"boxes": [
{ "box_id": "GIFT-BOX", "width": 12, "height": 10, "length": 10, "max_weight": 15, "quantity": 100 }
],
"inventory": {
"SHAMPOO": 50, "CONDITIONER": 50,
"BODY-WASH": 50, "LOOFAH": 50
}
}
],
"units": "in",
"custom_instructions": "Pack items as gift bundles: each box should contain exactly 1 shampoo, 1 conditioner, 1 body wash, and 1 loofah. Do not split bundles across boxes."
}{
"packages": [
{
"package_id": "pkg_WH-BEAUTY_GIFT-BOX_m1n2o",
"warehouse_id": "WH-BEAUTY",
"box_id": "GIFT-BOX",
"items": [
{ "item_id": "SHAMPOO", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 1.0 },
{ "item_id": "CONDITIONER", "position": { "x": 3, "y": 0, "z": 0 }, "weight": 1.0 },
{ "item_id": "BODY-WASH", "position": { "x": 6, "y": 0, "z": 0 }, "weight": 1.2 },
{ "item_id": "LOOFAH", "position": { "x": 0, "y": 9, "z": 0 }, "weight": 0.1 }
],
"total_weight": 3.3,
"volume_utilization": 0.22
},
{
"package_id": "pkg_WH-BEAUTY_GIFT-BOX_p3q4r",
"warehouse_id": "WH-BEAUTY",
"box_id": "GIFT-BOX",
"items": [
{ "item_id": "SHAMPOO", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 1.0 },
{ "item_id": "CONDITIONER", "position": { "x": 3, "y": 0, "z": 0 }, "weight": 1.0 },
{ "item_id": "BODY-WASH", "position": { "x": 6, "y": 0, "z": 0 }, "weight": 1.2 },
{ "item_id": "LOOFAH", "position": { "x": 0, "y": 9, "z": 0 }, "weight": 0.1 }
],
"total_weight": 3.3,
"volume_utilization": 0.22
}
],
"ai_review": {
"applied": true,
"instructions": "Pack items as gift bundles: each box should contain exactly 1 shampoo, 1 conditioner, 1 body wash, and 1 loofah.",
"adjustments_made": 1
},
"summary": {
"total_packages": 2,
"total_items_packed": 8,
"warehouses_used": ["WH-BEAUTY"]
},
"unfitted_items": []
}The AI reviewed the initial packing solution and reorganized items into matching gift bundles. The ai_review field confirms the instructions were applied.
6. Hazmat Shipment
Shipping items with hazardous materials classifications. StoaPack enforces segregation rules automatically.
{
"items": [
{
"item_id": "PAINT-THINNER",
"width": 4, "height": 6, "length": 4,
"weight": 3.5,
"quantity": 2,
"hazmat": {
"un_number": "UN1263",
"hazard_class": "3",
"packing_group": "II",
"proper_shipping_name": "Paint related material"
}
},
{
"item_id": "OXIDIZER-CLEANER",
"width": 3, "height": 5, "length": 3,
"weight": 2.0,
"quantity": 1,
"hazmat": {
"un_number": "UN1479",
"hazard_class": "5.1",
"packing_group": "II",
"proper_shipping_name": "Oxidizing solid, n.o.s."
}
},
{
"item_id": "SAFE-SPONGE",
"width": 5, "height": 3, "length": 5,
"weight": 0.2,
"quantity": 3
}
],
"warehouses": [
{
"warehouse_id": "WH-HAZMAT",
"boxes": [
{ "box_id": "HAZ-SM", "width": 12, "height": 10, "length": 12, "max_weight": 20, "quantity": 50 },
{ "box_id": "HAZ-MD", "width": 16, "height": 12, "length": 16, "max_weight": 35, "quantity": 30 }
],
"inventory": {
"PAINT-THINNER": 20,
"OXIDIZER-CLEANER": 10,
"SAFE-SPONGE": 100
}
}
],
"units": "in"
}{
"packages": [
{
"package_id": "pkg_WH-HAZMAT_HAZ-SM_h1a2z",
"warehouse_id": "WH-HAZMAT",
"box_id": "HAZ-SM",
"items": [
{ "item_id": "PAINT-THINNER", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 3.5 },
{ "item_id": "PAINT-THINNER", "position": { "x": 4, "y": 0, "z": 0 }, "weight": 3.5 },
{ "item_id": "SAFE-SPONGE", "position": { "x": 8, "y": 0, "z": 0 }, "weight": 0.2 }
],
"total_weight": 7.2,
"hazmat_info": {
"contains_hazmat": true,
"hazard_classes": ["3"],
"un_numbers": ["UN1263"]
}
},
{
"package_id": "pkg_WH-HAZMAT_HAZ-SM_m3a4t",
"warehouse_id": "WH-HAZMAT",
"box_id": "HAZ-SM",
"items": [
{ "item_id": "OXIDIZER-CLEANER", "position": { "x": 0, "y": 0, "z": 0 }, "weight": 2.0 },
{ "item_id": "SAFE-SPONGE", "position": { "x": 3, "y": 0, "z": 0 }, "weight": 0.2 },
{ "item_id": "SAFE-SPONGE", "position": { "x": 8, "y": 0, "z": 0 }, "weight": 0.2 }
],
"total_weight": 2.4,
"hazmat_info": {
"contains_hazmat": true,
"hazard_classes": ["5.1"],
"un_numbers": ["UN1479"]
}
}
],
"summary": {
"total_packages": 2,
"total_items_packed": 6,
"warehouses_used": ["WH-HAZMAT"],
"hazmat_segregation_applied": true
},
"unfitted_items": []
}Class 3 (flammable liquid) and Class 5.1 (oxidizer) are incompatible per 49 CFR segregation rules. StoaPack automatically placed them in separate boxes. The non-hazmat sponges were distributed across both packages to help fill space.