Home / Core Concepts

Core Concepts

FractalPack models the end-to-end fulfillment workflow from catalog items through packed shipments. This guide explains each entity and how they relate.

Entity lifecycle

Items (catalog)     Containers (box/pallet library)
     │                        │
     ▼                        ▼
  Orders ──────────────► Pack ◄── Rules (business logic)
     │                    │
     ▼                    ▼
 Shipments          Pack Results
     │
     ▼
Fulfillment Plans (parcel vs LTL)
     │
     ▼
 Wave Plans (pick optimization)

Items

Items represent SKUs in your catalog with physical properties. Create items via POST /api/v1/items or manage them through CSV/bulk import.

{
  "id": "SKU-A100",
  "name": "Widget Pro",
  "length": 10,
  "width": 8,
  "height": 6,
  "weight": 2.5,
  "category": "electronics",
  "tags": ["fragile", "battery"]
}

Key properties:

Containers

Containers define the boxes, pallets, and equipment available for packing. Manage them via POST /api/v1/containers or load them into your Container Master for automatic use.

Boxes (fixed-size)

{
  "id": "BOX-MED",
  "containerType": "Box",
  "innerLength": 18,
  "innerWidth": 14,
  "innerHeight": 12,
  "weightMaxGross": 50,
  "baseCost": 1.25
}

Dynamic containers

Variable-size containers (e.g., cut-to-fit boxes) with min/max dimension ranges:

{
  "id": "DYNBOX-1",
  "minLength": 6, "maxLength": 24,
  "minWidth": 6,  "maxWidth": 18,
  "minHeight": 4, "maxHeight": 16,
  "maxWeight": 50
}

Pallets

{
  "id": "PLT-48x40",
  "length": 48,
  "width": 40,
  "maxHeight": 60,
  "palletWeight": 45,
  "maxWeight": 2500,
  "platformHeight": 6,
  "maxStackWeight": 1200
}

Equipment (trailers)

{
  "id": "TRAILER-53",
  "length": 636,
  "width": 98,
  "height": 108,
  "tareWeight": 15000,
  "maxWeight": 45000,
  "equipmentType": "DryVan"
}

Container Master fallback

When a pack request omits containers, FractalPack automatically loads your organization's Container Master -- all active boxes, pallets, and equipment. An explicit empty array ("containers": []) opts out of this fallback.

Orders

Orders represent customer orders with line items. Each line references a SKU with a quantity.

{
  "sourceOrderId": "ORD-2026-1234",
  "lines": [
    { "sku": "SKU-A100", "quantityOrdered": 3 },
    { "sku": "SKU-B200", "quantityOrdered": 1 }
  ]
}

Order statuses: pending -> processing -> packed -> shipped -> cancelled

Shipments

Shipments are packable units created from orders. Creating a shipment resolves order line SKUs against your Item Master to get physical dimensions, then prepares the items for packing.

curl -X POST https://api.fractalpack.com/api/v1/shipments \
  -H "X-Api-Key: fpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "ORD-2026-1234" }'

Shipment lifecycle: created -> optimized -> rated -> ready -> shipped / cancelled

Key operations:

Pack

The core algorithm endpoint. Send items and containers, get back a 3D packing solution.

POST /api/v1/pack

Options:

See the Quickstart for a complete pack request example.

Rules

Rules inject business logic into the packing process without changing your API calls. They are evaluated server-side before every pack operation.

Rule types:

Managing rules via the API

# List all rules
curl https://api.fractalpack.com/api/v1/rules \
  -H "X-Api-Key: fpk_test_your_api_key"

# Create a rule
curl -X POST https://api.fractalpack.com/api/v1/rules \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Separate hazmat from food",
    "ruleType": "IncompatibilityGroup",
    "enabled": true,
    "priority": 10,
    "conditions": {
      "operator": "or",
      "conditions": [
        { "field": "tags", "operator": "contains", "value": "hazmat" },
        { "field": "tags", "operator": "contains", "value": "food" }
      ]
    }
  }'

# Update a rule
curl -X PUT https://api.fractalpack.com/api/v1/rules/rule_abc123 \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# Delete a rule
curl -X DELETE https://api.fractalpack.com/api/v1/rules/rule_abc123 \
  -H "X-Api-Key: fpk_test_your_api_key"

When rules fire during a pack request, the response includes a firedRules array:

{
  "firedRules": [
    {
      "ruleId": "rule_abc123",
      "ruleName": "Fragile Separation",
      "ruleType": "IncompatibilityGroup",
      "summary": "Separated items into 2 compatibility groups"
    }
  ]
}

Consolidation

Consolidation combines multiple orders heading to the same destination into fewer shipments, reducing shipping costs.

  1. Evaluate (POST /api/v1/consolidation/evaluate) -- analyze orders for consolidation opportunities
  2. Create group (POST /api/v1/consolidation/groups) -- group orders together
  3. Pack group (POST /api/v1/consolidation/groups/{id}/pack) -- pack the consolidated group

Consolidation profiles control constraints: whether mixed orders can share a carton, consolidation level (carton vs pallet), and more.

Fulfillment Plans

Fulfillment plans evaluate the best shipping strategy for an order. The system compares parcel (small package) vs LTL (less-than-truckload) options and returns cost breakdowns for each.

curl -X POST https://api.fractalpack.com/api/v1/fulfillment-plans \
  -H "X-Api-Key: fpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "orderIds": ["ORD-2026-1234"] }'

Response includes multiple options with cost comparisons. Select an option via POST /fulfillment-plans/{id}/select to create shipments automatically.

Wave Planning

Wave planning optimizes warehouse pick paths across multiple orders. Given a set of orders and warehouse layout, the algorithm groups orders into waves and sequences pick locations to minimize travel distance.

curl -X POST https://api.fractalpack.com/api/v1/wave-plan \
  -H "X-Api-Key: fpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [...],
    "maxOrdersPerWave": 20,
    "algorithm": "nearest-neighbor-2opt"
  }'

Available algorithms: nearest-neighbor-2opt (default, higher quality) and nearest-neighbor (faster).