We Taught Our Boxes to Play Tetris

“Does StoaPack support nesting?”

A potential client asked us this yesterday. Friday afternoon. The sensible thing would have been to add it to the backlog and call it a week.

It didn’t support nesting. But it should.

So we built it.

By end of day, we shipped nested container packing in StoaPack API v1.1. 54 tests covering the algorithm, backward compatibility, constraints, and validation. Full regression suite. All green.

What is nested packing?

Picture this: A customer orders a storage bin along with several small accessories.

Before nesting: The algorithm treats the bin like any other item. It goes in a shipping box. The accessories go somewhere else. Maybe the same box, maybe not. The bin ships empty.

After nesting: The algorithm recognizes that those accessories could go inside the bin before packing everything into the shipping container.

It’s the same logic every parent uses when packing for a road trip. The cooler isn’t just cargo. It’s storage.

The tricky part

Shipping new features to a production API comes with a constraint: you can’t break what’s already working.

We designed the feature with this in mind:

Entirely opt-in. Existing integrations don’t need to change anything. Want nesting? Add the enable_nesting flag to your request. Don’t add it? Everything works exactly as before.

Smart edge cases. Not everything should nest:

• Hazmat containers won’t accept nested items. Safety regulations exist for a reason.
• Fragile items can be marked as non-nestable. Glass stays outside.
• Compatibility groups keep similar items together. Electronics nest with electronics, not with clothing.

Weight limits. Containers have a max_nested_weight property. The algorithm respects it.

Clear feedback. The API response tells you exactly what happened:

• How many containers were used for nesting
• How many items were nested
• How many containers were skipped (and why)

“It didn’t work” is never a helpful error message. We tell you what nested, what didn’t, and why.

How to use it

Add nesting properties to your items:

For items that can hold other items:

• is_container: true
• internal_dimensions (length, width, height)
• max_nested_weight

For items that shouldn’t be nested inside other items:

• nestable: false

For compatibility grouping:

• nest_group: "electronics" (or whatever category makes sense)

Then add enable_nesting: true to your request.

The algorithm handles the rest.

Why it matters

This isn’t optimization for optimization’s sake. Nested packing has real business impact:

Fewer boxes. When accessories fit inside products, you need fewer shipping containers.

Cheaper shipping. Better space utilization means smaller shipments and lower costs.

Less waste. Fewer boxes means less cardboard. Better for the environment, better for your sustainability metrics.

Better customer experience. People actually like receiving their storage bin with the accessories already organized inside. It feels intentional, not haphazard.

The takeaway

Friday afternoon feature requests can be fun. Sometimes the best work happens when you decide to just go for it.

We shipped a production feature in a few hours because:

1. The use case was clear
2. The design was straightforward (opt-in, backward compatible)
3. We have good testing infrastructure
4. We didn’t overthink it

If you’re building logistics software and want smarter packing optimization, we’d love to help. StoaPack handles the hard math so you can focus on your business.

---

Ready to try nested packing? Learn more at StoaPack or get in touch.