Consolidation

Combine multiple small orders going to the same destination into fewer shipments. Consolidation reduces shipping costs by packing items from different orders into shared containers.

Prerequisites

• A valid API key (see Authentication)
• Multiple orders in Received status
• Orders with ship-to addresses that share a common grouping attribute (e.g., same ZIP code, same customer)

When consolidation saves costs

• Multiple small orders to the same address (e.g., a customer places 3 orders in one day)
• Warehouse batch fulfillment where many orders share a region
• B2B shipments where multiple POs go to the same facility
• Orders with the same externalShipmentId from your host system (auto-grouped)

Workflow overview

Create Profile  -->  Evaluate Orders  -->  Create Group  -->  Pack Group

Step 1: Create a consolidation profile

A profile defines how orders are grouped and what constraints apply. groupingKeys specify which order fields must match for orders to be grouped together.

curl -X POST https://api.fractalpack.com/api/v1/consolidation/profiles \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "name": "Same-Customer Parcel",
    "description": "Consolidate orders going to the same customer address",
    "groupingKeys": ["ShipTo.Address.Zip", "ShipTo.Address.State", "Customer.Id"],
    "consolidationLevel": "Box",
    "allowMixedOrdersInCarton": true,
    "constraints": {
      "maxWeightPerGroup": 70,
      "maxOrdersPerGroup": 10,
      "maxItemsPerGroup": 200
    }
  }'

Response (201 Created)

{
  "id": "cprf_m1n2o3p4",
  "name": "Same-Customer Parcel",
  "description": "Consolidate orders going to the same customer address",
  "groupingKeys": ["ShipTo.Address.Zip", "ShipTo.Address.State", "Customer.Id"],
  "consolidationLevel": "Box",
  "allowMixedOrdersInCarton": true,
  "constraints": {
    "maxWeightPerGroup": 70,
    "maxOrdersPerGroup": 10,
    "maxItemsPerGroup": 200
  },
  "createdAt": "2026-04-03T14:00:00Z",
  "updatedAt": "2026-04-03T14:00:00Z",
  "version": 1
}

Profile fields

Step 2: Evaluate orders for consolidation

Pass an array of order IDs to get suggested groupings. The evaluator checks grouping keys, constraints, and splits oversized groups automatically.

curl -X POST https://api.fractalpack.com/api/v1/consolidation/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "orderIds": [
      "ord_aaa111",
      "ord_bbb222",
      "ord_ccc333",
      "ord_ddd444",
      "ord_eee555"
    ],
    "profileId": "cprf_m1n2o3p4"
  }'

Response

{
  "suggestedGroups": [
    {
      "orderIds": ["ord_aaa111", "ord_bbb222", "ord_ccc333"],
      "profileId": "cprf_m1n2o3p4",
      "groupingKeyValues": {
        "ShipTo.Address.Zip": "10001",
        "ShipTo.Address.State": "NY",
        "Customer.Id": "cust_jane"
      },
      "source": "Profile"
    },
    {
      "orderIds": ["ord_ddd444", "ord_eee555"],
      "profileId": "cprf_m1n2o3p4",
      "groupingKeyValues": {
        "ShipTo.Address.Zip": "60601",
        "ShipTo.Address.State": "IL",
        "Customer.Id": "cust_acme"
      },
      "source": "Profile"
    }
  ],
  "ungrouped": []
}

Orders that cannot be grouped appear in ungrouped with a reason:

{
  "ungrouped": [
    {
      "orderId": "ord_fff666",
      "reason": "Insufficient orders with matching grouping keys to form a group"
    },
    {
      "orderId": "ord_ggg777",
      "reason": "Order not found"
    }
  ]
}

A group requires at least 2 orders. Single orders that match no peers are returned as ungrouped.

ExternalShipmentId pre-grouping

Orders with the same externalShipmentId (set at order creation) are automatically grouped before profile-based evaluation. These appear with "source": "ExternalShipmentId":

{
  "suggestedGroups": [
    {
      "orderIds": ["ord_xxx", "ord_yyy"],
      "groupingKeyValues": {
        "ExternalShipmentId": "EXT-SHIP-001"
      },
      "source": "ExternalShipmentId"
    }
  ]
}

You can omit profileId from the evaluate request. The system will attempt to resolve a profile via rules, or fall back to ExternalShipmentId-only grouping.

Step 3: Create a consolidation group

Take a suggested group and formalize it:

curl -X POST https://api.fractalpack.com/api/v1/consolidation/groups \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "profileId": "cprf_m1n2o3p4",
    "sourceOrderIds": ["ord_aaa111", "ord_bbb222", "ord_ccc333"],
    "groupingKeyValues": {
      "ShipTo.Address.Zip": "10001",
      "ShipTo.Address.State": "NY",
      "Customer.Id": "cust_jane"
    }
  }'

Response (201 Created)

{
  "id": "cgrp_q1r2s3t4",
  "profileId": "cprf_m1n2o3p4",
  "groupingKeyValues": {
    "ShipTo.Address.Zip": "10001",
    "ShipTo.Address.State": "NY",
    "Customer.Id": "cust_jane"
  },
  "sourceOrderIds": ["ord_aaa111", "ord_bbb222", "ord_ccc333"],
  "status": "Created",
  "wasManualOverride": false,
  "createdAt": "2026-04-03T14:05:00Z",
  "createdBy": "user_abc",
  "version": 1
}

Validation warnings and manual override

If the group violates profile constraints (e.g., mismatched ZIP codes), the API returns 422 with warnings:

{
  "rejected": [
    {
      "orderIds": ["ord_aaa111", "ord_bbb222"],
      "warnings": [
        "Orders have mismatched ShipTo.Address.Zip values: 10001, 10002"
      ]
    }
  ]
}

To override and create the group anyway, set forceOverride: true:

curl -X POST https://api.fractalpack.com/api/v1/consolidation/groups \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "sourceOrderIds": ["ord_aaa111", "ord_bbb222"],
    "forceOverride": true
  }'

The response will include wasManualOverride: true and overrideWarnings for audit purposes.

Step 4: Pack the consolidation group

Pack all items from the group's orders into shared containers:

curl -X POST https://api.fractalpack.com/api/v1/consolidation/groups/cgrp_q1r2s3t4/pack \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "allowMultipleBoxes": true
  }'

Omit containers to use Container Master defaults. Optionally provide containers inline:

{
  "containers": [
    {
      "id": "BOX-LARGE",
      "length": 24,
      "width": 18,
      "height": 16,
      "maxWeight": 50
    }
  ],
  "allowMultipleBoxes": true,
  "algorithm": "ebAfit"
}

Response

{
  "packResult": {
    "algorithm": "ebAfit",
    "results": [
      {
        "containerId": "BOX-LARGE",
        "boxIndex": 0,
        "packedItems": [
          {
            "id": "ord_aaa111:10:WIDGET-LG-001",
            "weight": 2.5,
            "tags": ["order:ord_aaa111"]
          },
          {
            "id": "ord_bbb222:10:GADGET-SM-042",
            "weight": 0.8,
            "tags": ["order:ord_bbb222"]
          },
          {
            "id": "ord_ccc333:10:CABLE-USB-C",
            "weight": 0.1,
            "tags": ["order:ord_ccc333"]
          }
        ],
        "unpackedItems": [],
        "volumeUtilizationPercent": 45.2,
        "totalWeight": 3.4
      }
    ]
  },
  "orderMapping": {
    "BOX-LARGE": ["ord_aaa111", "ord_bbb222", "ord_ccc333"]
  },
  "groupId": "cgrp_q1r2s3t4",
  "groupStatus": "Packed"
}

Key response fields:

Item IDs in the pack result follow the format {orderId}:{lineNumber}:{sku} for traceability. Each item is tagged with order:{orderId}.

Mixed vs. separated cartons

When allowMixedOrdersInCarton is false on the profile, the engine adds separation groups so items from different orders never share a box. The orderMapping will show each container containing items from only one order, but all containers ship together as one consolidated shipment.

Managing groups

List groups

curl "https://api.fractalpack.com/api/v1/consolidation/groups?limit=20&status=Created" \
  -H "X-Api-Key: fpk_test_your_api_key"

Get a group

curl "https://api.fractalpack.com/api/v1/consolidation/groups/cgrp_q1r2s3t4" \
  -H "X-Api-Key: fpk_test_your_api_key"

Dissolve a group

Release orders back to their original state:

curl -X DELETE "https://api.fractalpack.com/api/v1/consolidation/groups/cgrp_q1r2s3t4" \
  -H "X-Api-Key: fpk_test_your_api_key"

Cannot dissolve a group that has already been packed.

Error handling

Next steps

• Order to Shipment -- single-order shipment lifecycle
• Batch Packing -- high-volume async packing
• CSV Import -- bulk import orders before consolidation