Home / Quickstart

Quickstart

Pack your first box in under 2 minutes.

Prerequisites

Your first pack request

The /api/v1/pack endpoint takes a list of items and containers, then returns an optimal packing arrangement.

curl

curl -X POST https://api.fractalpack.com/api/v1/pack \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_key_here" \
  -d '{
    "items": [
      {
        "id": "SKU-A100",
        "length": 10,
        "width": 8,
        "height": 6,
        "weight": 2.5,
        "quantity": 3
      },
      {
        "id": "SKU-B200",
        "length": 5,
        "width": 5,
        "height": 4,
        "weight": 1.2,
        "quantity": 2
      }
    ],
    "containers": [
      {
        "id": "BOX-MED",
        "length": 18,
        "width": 14,
        "height": 12,
        "maxWeight": 50
      }
    ]
  }'

Python

import requests

response = requests.post(
    "https://api.fractalpack.com/api/v1/pack",
    headers={"X-Api-Key": "fpk_test_your_key_here"},
    json={
        "items": [
            {"id": "SKU-A100", "length": 10, "width": 8, "height": 6, "weight": 2.5, "quantity": 3},
            {"id": "SKU-B200", "length": 5, "width": 5, "height": 4, "weight": 1.2, "quantity": 2},
        ],
        "containers": [
            {"id": "BOX-MED", "length": 18, "width": 14, "height": 12, "maxWeight": 50}
        ],
    },
)

result = response.json()
for container in result["results"]:
    print(f"Container: {container['containerId']}")
    print(f"  Utilization: {container['volumeUtilizationPercent']:.1f}%")
    print(f"  Packed items: {len(container['packedItems'])}")

JavaScript

const response = await fetch("https://api.fractalpack.com/api/v1/pack", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "fpk_test_your_key_here",
  },
  body: JSON.stringify({
    items: [
      { id: "SKU-A100", length: 10, width: 8, height: 6, weight: 2.5, quantity: 3 },
      { id: "SKU-B200", length: 5, width: 5, height: 4, weight: 1.2, quantity: 2 },
    ],
    containers: [
      { id: "BOX-MED", length: 18, width: 14, height: 12, maxWeight: 50 },
    ],
  }),
});

const result = await response.json();
for (const container of result.results) {
  console.log(`Container: ${container.containerId}`);
  console.log(`  Utilization: ${container.volumeUtilizationPercent.toFixed(1)}%`);
  console.log(`  Packed items: ${container.packedItems.length}`);
}

C#

using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "fpk_test_your_key_here");

var response = await client.PostAsJsonAsync(
    "https://api.fractalpack.com/api/v1/pack",
    new
    {
        items = new[]
        {
            new { id = "SKU-A100", length = 10.0, width = 8.0, height = 6.0, weight = 2.5, quantity = 3 },
            new { id = "SKU-B200", length = 5.0, width = 5.0, height = 4.0, weight = 1.2, quantity = 2 },
        },
        containers = new[]
        {
            new { id = "BOX-MED", length = 18.0, width = 14.0, height = 12.0, maxWeight = 50.0 },
        },
    });

var result = await response.Content.ReadFromJsonAsync<PackResponse>();

Understanding the response

{
  "algorithm": "ebAfit",
  "results": [
    {
      "containerId": "BOX-MED",
      "boxIndex": 0,
      "containerDimensions": { "length": 18, "width": 14, "height": 12 },
      "packedItems": [
        {
          "id": "SKU-A100",
          "coordinate": { "x": 0, "y": 0, "z": 0 },
          "packedDimensions": { "length": 10, "width": 8, "height": 6 },
          "weight": 2.5,
          "tags": []
        }
      ],
      "unpackedItems": [],
      "volumeUtilizationPercent": 72.3,
      "totalWeight": 9.9
    }
  ]
}

Key fields:

Field Description
algorithm The packing algorithm used (default: ebAfit)
results One entry per container used
results[].containerId Which container type was selected
results[].boxIndex Instance index when multiple boxes of the same type are used
results[].packedItems Items placed in this container, with 3D coordinates
results[].unpackedItems Items that did not fit (empty when everything fits)
results[].volumeUtilizationPercent How efficiently the container space is used
results[].totalWeight Combined weight of all packed items

Each packed item includes coordinate (x, y, z origin in inches) and packedDimensions (the item's oriented dimensions inside the container).

Multiple containers

Set "allowMultipleBoxes": true to let the solver use more than one box when items do not fit in a single container.

Omitting containers

If you omit containers from the request, FractalPack loads your organization's Container Master -- the boxes, pallets, and equipment you have configured via the API or dashboard.

Next steps