StoaPack Quick Start Guide

1. Register for an account or log in to your existing account 30-Day Free Trial
2. Select your subscription plan (all plans include a 30-day free trial)
3. Navigate to your Dashboard
4. Click "Create New API Key"
5. Give your key a descriptive name (e.g., "Production" or "Testing")
6. Copy and securely store your new API key

Select the plan that best fits your needs:

• Starter

  1,500 packaging requests and 50 AI reviews
  $30/month
• Professional

  10,000 packaging requests and 500 AI reviews
  $100/month
• Enterprise

  50,000 packaging requests and 2,500 AI reviews
  $300/month

You can start with the Starter plan and upgrade as your needs grow.

Use these examples to test the API with a basic optimization request:

{
  "Content-Type": "application/json",
  "X-API-Key": "YOUR_API_KEY"
}

{
  "items": [
    {
      "id": "product-123",
      "width": 10,
      "height": 15,
      "depth": 5,
      "weight": 1.2,
      "quantity": 3,
      "requires_box": true
    },
    {
      "id": "product-456",
      "width": 20,
      "height": 10,
      "depth": 10,
      "weight": 2.5,
      "quantity": 2,
      "requires_box": false
    }
  ],
  "warehouses": [
    {
      "id": "warehouse-main",
      "inventory": {
        "product-123": 10,
        "product-456": 5
      },
      "available_boxes": [
        {
          "id": "box-small",
          "width": 25,
          "height": 25,
          "depth": 25,
          "max_weight": 10,
          "quantity": 100,
          "fill_percentage": 80
        },
        {
          "id": "box-medium",
          "width": 40,
          "height": 30,
          "depth": 35,
          "max_weight": 25,
          "quantity": 50
        }
      ]
    }
  ],
  "unit": "cm",
  "ai_review": true,
  "custom_instructions": "Optimize for minimal box count and ensure fragile items are well-protected."
}

{
  "solution": {
    "warehouses": [
      {
        "id": "warehouse-main",
        "items_fulfilled": [
          {
            "id": "product-123",
            "quantity": 3
          },
          {
            "id": "product-456",
            "quantity": 2
          }
        ],
        "packing_solution": {
          "boxes": [
            {
              "id": "pkg_warehouse-main_box-small_a1b2c3",
              "box_id": "box-small",
              "warehouse_id": "warehouse-main",
              "utilization": 0.72,
              "real_utilization": 0.58,
              "fill_percentage": 80,
              "dimensions": {
                "width": 25,
                "height": 25,
                "depth": 25
              },
              "adjusted_dimensions": {
                "width": 23.21,
                "height": 23.21,
                "depth": 23.21
              },
              "packed_items": [
                {
                  "id": "product-123",
                  "position": {
                    "x": 0,
                    "y": 0,
                    "z": 0
                  },
                  "rotation": 0,
                  "dimensions": {
                    "width": 10,
                    "height": 15,
                    "depth": 5
                  }
                }
              ]
            }
          ],
          "unboxed_items": [
            {
              "id": "product-456",
              "quantity": 2
            }
          ],
          "unfitted_items": []
        }
      }
    ],
    "unfulfilled_items": []
  },
  "ai_review": {
    "assessment": "The packing solution optimizes space efficiently while following constraints.",
    "meets_requirements": true,
    "issues": [],
    "recommendations": [
      "Consider grouping similar items together for easier handling."
    ],
    "overall_rating": 4.5,
    "custom_instructions_used": "Optimize for minimal box count and ensure fragile items are well-protected."
  },
  "metadata": {
    "api_version": "1.1.0",
    "request_id": "req_a1b2c3d4e5f6",
    "processing_time": 0.754
  }
}

The API returns a JSON response with the optimized packing solution:

• solution: Contains the optimized packing solution across warehouses
• warehouses: Lists each warehouse with its packing solution and items fulfilled
• unfulfilled_items: Items that couldn't be fulfilled from ANY warehouse's inventory (e.g., insufficient inventory quantity or not stocked in any warehouse)
• unfitted_items: Items that couldn't be fitted into boxes at a SPECIFIC warehouse (e.g., too large for any available box). These appear in each warehouse's packing solution, not in the global unfulfilled_items list.
• unfitted_items_details: Detailed information about items that couldn't be fitted, including quantities and specific reasons why they couldn't be fitted.
• unboxed_items: Items marked with requires_box: false that don't need packaging
• ai_review: If requested, contains AI assessment of the packing solution
• metadata: Information about the API request including version and processing time

Note the id field in each packed box follows the format: pkg_<warehouse_id>_<box_id>_<random_string>

Multi-Warehouse Optimization

Supply multiple warehouses to optimize across your entire network:

• The API prioritizes the solution requiring the fewest total packages to minimize shipping costs
• Warehouses are analyzed to find the most efficient packing solution regardless of input order
• Items not available in the optimal warehouse will be allocated to other warehouses
• Each warehouse can have its own inventory levels and box assortment

Fill Percentage Control

Control how full each box can be packed using the fill_percentage parameter:

• Set a value between 1-100% to specify how much of the box's volume can be used
• The algorithm proportionally reduces each dimension by applying the cube root of the fill percentage
• Provides extra space for padding, void fillers, or fragile items
• Apply different fill percentages to different box types in each warehouse
• Response includes both utilization (relative to adjusted dimensions) and real_utilization (relative to original dimensions)

AI-Powered Reviews and Solutions Beta

Add the ai_review: true and custom_instructions fields to get AI feedback:

• The AI will evaluate your packing solution against your custom requirements
• When custom_instructions is provided, the AI will create the packing solution directly instead of using the algorithm
• AI-generated packing solutions can incorporate complex requirements (e.g., "place heavy items at the bottom" or "separate fragile items")
• Both AI reviews and AI-generated packing solutions count against your monthly AI usage limits

• Store API keys securely and never expose them in client-side code
• Implement proper error handling to manage API rate limits and errors
• Use consistent units (cm or in) across all dimensions
• Use the requires_box: false flag for items that can ship without packaging
• Use the fill_percentage parameter (1-100%) to control how full boxes can be packed:
  • Useful for fragile items that need extra padding space
  • Helpful when using void fillers that require additional space
  • Lower fill percentages ensure items won't be tightly packed
  • The API adjusts internal box dimensions proportionally based on this value
• Test with small batches before implementing in production
• Consider creating separate API keys for development and production