Home / Recipes / Cost-Optimized Packing

Cost-Optimized Packing

Optimize container selection to minimize shipping cost rather than maximize volume utilization. Cost optimization considers carrier rate tables, dimensional weight pricing, and box costs to pick the cheapest combination.

Prerequisites

How cost optimization works

By default, the packing engine optimizes for volume -- it minimizes the number of boxes used. With optimizeFor: "cost", the engine:

  1. Packs items into all feasible container combinations
  2. Calculates the shipping cost for each combination using your rate tables
  3. Factors in dimensional weight pricing (carriers charge whichever is greater: actual weight or dimensional weight)
  4. Adds the box material cost (cost field on containers)
  5. Selects the combination with the lowest total cost

This means a slightly larger box can be cheaper than a tight-fitting one if it avoids a dimensional weight surcharge or falls into a lower rate tier.

Step 1: Pack with volume optimization (baseline)

curl -X POST https://api.fractalpack.com/api/v1/pack \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "items": [
      {
        "id": "LAMP-DESK-BLK",
        "length": 16,
        "width": 8,
        "height": 22,
        "weight": 4.5,
        "quantity": 1
      },
      {
        "id": "BULB-LED-4PK",
        "length": 6,
        "width": 6,
        "height": 4,
        "weight": 0.8,
        "quantity": 2
      }
    ],
    "containers": [
      {
        "id": "BOX-A",
        "length": 18,
        "width": 10,
        "height": 24,
        "maxWeight": 30,
        "cost": 1.20
      },
      {
        "id": "BOX-B",
        "length": 24,
        "width": 16,
        "height": 24,
        "maxWeight": 50,
        "cost": 2.50
      }
    ],
    "allowMultipleBoxes": true
  }'

Volume optimization selects the smallest box that fits everything -- BOX-A:

{
  "algorithm": "ebAfit",
  "results": [
    {
      "containerId": "BOX-A",
      "boxIndex": 0,
      "packedItems": [
        { "id": "LAMP-DESK-BLK", "weight": 4.5 },
        { "id": "BULB-LED-4PK", "weight": 0.8 },
        { "id": "BULB-LED-4PK", "weight": 0.8 }
      ],
      "unpackedItems": [],
      "volumeUtilizationPercent": 73.4,
      "totalWeight": 6.1
    }
  ]
}

Step 2: Pack with cost optimization

Add optimizeFor: "cost" along with originZip and destinationZip. The engine loads your configured rate tables automatically.

curl -X POST https://api.fractalpack.com/api/v1/pack \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "items": [
      {
        "id": "LAMP-DESK-BLK",
        "length": 16,
        "width": 8,
        "height": 22,
        "weight": 4.5,
        "quantity": 1
      },
      {
        "id": "BULB-LED-4PK",
        "length": 6,
        "width": 6,
        "height": 4,
        "weight": 0.8,
        "quantity": 2
      }
    ],
    "containers": [
      {
        "id": "BOX-A",
        "length": 18,
        "width": 10,
        "height": 24,
        "maxWeight": 30,
        "cost": 1.20
      },
      {
        "id": "BOX-B",
        "length": 24,
        "width": 16,
        "height": 24,
        "maxWeight": 50,
        "cost": 2.50
      }
    ],
    "allowMultipleBoxes": true,
    "optimizeFor": "cost",
    "originZip": "90210",
    "destinationZip": "10001"
  }'

Response

Cost optimization selects BOX-B here because its dimensions yield a lower dimensional weight rate:

{
  "algorithm": "ebAfit",
  "results": [
    {
      "containerId": "BOX-B",
      "boxIndex": 0,
      "packedItems": [
        { "id": "LAMP-DESK-BLK", "weight": 4.5 },
        { "id": "BULB-LED-4PK", "weight": 0.8 },
        { "id": "BULB-LED-4PK", "weight": 0.8 }
      ],
      "unpackedItems": [],
      "volumeUtilizationPercent": 35.2,
      "totalWeight": 6.1,
      "costBreakdown": {
        "shippingCost": 8.45,
        "boxCost": 2.50,
        "totalCost": 10.95,
        "billableWeight": 6.1,
        "dimWeight": 5.8,
        "actualWeight": 6.1,
        "carrier": "ups",
        "service": "ground",
        "zone": 8
      }
    }
  ]
}

Understanding the cost breakdown

Each container result includes a costBreakdown when cost optimization is used:

Field Description
shippingCost Carrier rate for this box based on billable weight and zone
boxCost Material cost of the container (from the cost field)
totalCost shippingCost + boxCost
billableWeight The greater of actualWeight and dimWeight
dimWeight Dimensional weight: (L x W x H) / divisor (carrier-specific, typically 139 for domestic)
actualWeight Sum of item weights in the box
carrier The carrier used for rating
service The service level used
zone Shipping zone between origin and destination

Why cost optimization picks a different box

In the example above:

The exact cost comparison depends on your rate tables. The engine evaluates all combinations and picks the cheapest total.

Flat-rate containers

Containers with a flatRateCost use a fixed shipping price regardless of weight:

{
  "containers": [
    {
      "id": "USPS-FLAT-RATE-MED",
      "length": 11,
      "width": 8.5,
      "height": 5.5,
      "maxWeight": 70,
      "flatRateCost": 15.05
    }
  ]
}

Cost optimization compares flat-rate options against standard rated options and picks whichever is cheaper.

Carrier service containers

Set carrierService to restrict a container to a specific carrier service:

{
  "containers": [
    {
      "id": "FEDEX-PAK",
      "length": 15.5,
      "width": 12,
      "height": 1,
      "maxWeight": 50,
      "cost": 0,
      "carrierService": "fedex_express_saver"
    }
  ]
}

Tips

Error handling

Status Cause Fix
400 Invalid optimizeFor value Use "volume" or "cost"
400 No containers provided Add containers or configure Container Master

If no rate tables are found for your account, the engine silently falls back to volume optimization. Check your response's costBreakdown field -- if it is absent, rate tables were not applied.

Next steps