Order to Shipment

Full lifecycle walkthrough: create items, create an order, generate a shipment, optimize packing, rate the shipment, and mark it ready for dispatch.

Prerequisites

A valid API key (see Authentication)
Container Master configured with at least one box (or provide containers inline)

Lifecycle overview

Create Items (optional)  -->  Create Order  -->  Create Shipment
                                                       |
                                                       v
                                            Optimize (pack items)
                                                       |
                                                       v
                                              Rate (get quotes)
                                                       |
                                                       v
                                             Mark Ready (dispatch)

Shipment statuses progress through: Created -> Optimizing -> Optimized -> Rating -> Rated -> Ready.

Step 1: Create items in the Item Master

Register items once, then reference them by ID across orders. Skip this step if you provide inline dimensions on order lines.

curl -X POST https://api.fractalpack.com/api/v1/items \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "id": "WIDGET-LG-001",
    "name": "Large Widget",
    "length": 12,
    "width": 8,
    "height": 6,
    "weight": 2.5,
    "category": "widgets",
    "tags": ["fragile"]
  }'

Response (201 Created)

{
  "id": "WIDGET-LG-001",
  "name": "Large Widget",
  "length": 12,
  "width": 8,
  "height": 6,
  "weight": 2.5,
  "category": "widgets",
  "tags": ["fragile"],
  "version": 1,
  "createdAt": "2026-04-03T14:00:00Z",
  "updatedAt": "2026-04-03T14:00:00Z"
}

Create a second item:

curl -X POST https://api.fractalpack.com/api/v1/items \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "id": "GADGET-SM-042",
    "name": "Small Gadget",
    "length": 4,
    "width": 4,
    "height": 3,
    "weight": 0.8,
    "category": "gadgets"
  }'

Step 2: Create an order

Reference items by itemId. The system resolves dimensions from the Item Master. Set submit: true (default) to create the order in Received status, ready for shipment creation.

curl -X POST https://api.fractalpack.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "sourceSystem": "shopify",
    "sourceOrderId": "ORD-2026-04-1001",
    "orderType": "Outbound",
    "priority": "Standard",
    "serviceLevel": "Standard",
    "channel": "ecommerce",
    "shipFrom": {
      "name": "Main Warehouse",
      "address": {
        "street1": "100 Warehouse Blvd",
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90210",
        "country": "US"
      }
    },
    "shipTo": {
      "name": "Jane Smith",
      "address": {
        "street1": "456 Oak Ave",
        "city": "New York",
        "state": "NY",
        "zip": "10001",
        "country": "US"
      },
      "residential": true
    },
    "requiredShipBy": "2026-04-05T23:59:59Z",
    "lines": [
      {
        "lineNumber": 10,
        "itemId": "WIDGET-LG-001",
        "sku": "WIDGET-LG-001",
        "quantityOrdered": 3
      },
      {
        "lineNumber": 20,
        "itemId": "GADGET-SM-042",
        "sku": "GADGET-SM-042",
        "quantityOrdered": 5
      }
    ]
  }'

Response (201 Created)

{
  "id": "ord_a1b2c3d4",
  "sourceSystem": "shopify",
  "sourceOrderId": "ORD-2026-04-1001",
  "status": "Received",
  "orderType": "Outbound",
  "priority": "Standard",
  "serviceLevel": "Standard",
  "channel": "ecommerce",
  "shipFrom": { "name": "Main Warehouse", "address": { "zip": "90210" } },
  "shipTo": { "name": "Jane Smith", "address": { "zip": "10001" }, "residential": true },
  "lines": [
    { "lineNumber": 10, "itemId": "WIDGET-LG-001", "sku": "WIDGET-LG-001", "quantityOrdered": 3 },
    { "lineNumber": 20, "itemId": "GADGET-SM-042", "sku": "GADGET-SM-042", "quantityOrdered": 5 }
  ],
  "version": 1,
  "createdAt": "2026-04-03T14:01:00Z"
}

Alternatively, provide inline dimensions instead of itemId:

{
  "lines": [
    {
      "lineNumber": 10,
      "sku": "CUSTOM-PART-99",
      "quantityOrdered": 1,
      "length": 15,
      "width": 10,
      "height": 5,
      "weight": 3.2
    }
  ]
}

When itemId is provided, inline dimensions are ignored in favor of Item Master data.

Step 3: Create a shipment from the order

curl -X POST https://api.fractalpack.com/api/v1/shipments \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "orderIds": ["ord_a1b2c3d4"],
    "mode": "Parcel",
    "serviceLevel": "Standard"
  }'

Response (201 Created)

{
  "id": "shp_e5f6g7h8",
  "status": "Created",
  "orderIds": ["ord_a1b2c3d4"],
  "mode": "Parcel",
  "serviceLevel": "Standard",
  "lines": [
    {
      "lineNumber": 10,
      "itemId": "WIDGET-LG-001",
      "sku": "WIDGET-LG-001",
      "quantity": 3,
      "length": 12,
      "width": 8,
      "height": 6,
      "weight": 2.5
    },
    {
      "lineNumber": 20,
      "itemId": "GADGET-SM-042",
      "sku": "GADGET-SM-042",
      "quantity": 5,
      "length": 4,
      "width": 4,
      "height": 3,
      "weight": 0.8
    }
  ],
  "version": 1,
  "createdAt": "2026-04-03T14:02:00Z"
}

The shipment resolves item dimensions from the Item Master at creation time. The source order transitions to Planned status.

You can create a shipment from multiple orders by passing multiple IDs in orderIds. All orders must belong to the same organization and be in Received status.

Step 4: Optimize shipment packing

Run the packing engine against the shipment's items. Containers are loaded from your Container Master automatically.

curl -X POST https://api.fractalpack.com/api/v1/shipments/shp_e5f6g7h8/optimize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{}'

Optionally specify an algorithm:

curl -X POST https://api.fractalpack.com/api/v1/shipments/shp_e5f6g7h8/optimize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{
    "algorithm": "fpFast"
  }'

Response (200 OK)

{
  "id": "shp_e5f6g7h8",
  "status": "Optimized",
  "packPlan": {
    "status": "Completed",
    "algorithm": "ebAfit",
    "results": [
      {
        "containerId": "BOX-MEDIUM",
        "boxIndex": 0,
        "packedItems": [
          { "id": "WIDGET-LG-001", "weight": 2.5 },
          { "id": "WIDGET-LG-001", "weight": 2.5 },
          { "id": "WIDGET-LG-001", "weight": 2.5 },
          { "id": "GADGET-SM-042", "weight": 0.8 },
          { "id": "GADGET-SM-042", "weight": 0.8 },
          { "id": "GADGET-SM-042", "weight": 0.8 },
          { "id": "GADGET-SM-042", "weight": 0.8 },
          { "id": "GADGET-SM-042", "weight": 0.8 }
        ],
        "unpackedItems": [],
        "volumeUtilizationPercent": 62.5,
        "totalWeight": 11.5
      }
    ]
  },
  "version": 2
}

The shipment status transitions: Created -> Optimizing -> Optimized.

If optimization fails (e.g., items too large for any container), the status becomes OptimizationFailed and the error details appear in the response.

Step 5: Rate the shipment

Get shipping rate quotes for the optimized pack plan.

curl -X POST https://api.fractalpack.com/api/v1/shipments/shp_e5f6g7h8/rate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key" \
  -d '{}'

Optionally filter by carrier:

{
  "carriers": ["ups", "fedex"]
}

Response (200 OK)

{
  "id": "shp_e5f6g7h8",
  "status": "Rated",
  "version": 3
}

The shipment status transitions: Optimized -> Rating -> Rated.

If rating fails (e.g., carrier API unavailable), the status becomes RateFailed.

Step 6: Mark ready for dispatch

curl -X POST https://api.fractalpack.com/api/v1/shipments/shp_e5f6g7h8/ready \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: fpk_test_your_api_key"

Response (200 OK)

{
  "id": "shp_e5f6g7h8",
  "status": "Ready",
  "version": 4
}

Status transitions

From	To	Trigger
--	`Created`	POST /shipments
`Created`	`Optimizing`	POST /shipments/{id}/optimize
`Optimizing`	`Optimized`	Optimization completes
`Optimizing`	`OptimizationFailed`	Optimization fails
`Optimized`	`Rating`	POST /shipments/{id}/rate
`Rating`	`Rated`	Rating completes
`Rating`	`RateFailed`	Rating fails
`Rated`	`Ready`	POST /shipments/{id}/ready
Any	`Cancelled`	DELETE /shipments/{id}

Error handling

Status	Cause	Fix
404	Order or shipment not found	Check the ID
400	Order not in `Received` status	Only received orders can create shipments
400	Shipment not in correct status for the action	Follow the status progression
422	Item resolution failed (itemId not found in Item Master)	Create the item first or provide inline dimensions
409	Concurrency conflict (version mismatch)	Re-fetch and retry with the current version

Cancellation

Cancel a shipment at any point before Ready:

curl -X DELETE https://api.fractalpack.com/api/v1/shipments/shp_e5f6g7h8 \
  -H "X-Api-Key: fpk_test_your_api_key"

To revert the source order back to Received status after cancelling its shipment:

curl -X POST https://api.fractalpack.com/api/v1/orders/ord_a1b2c3d4/revert \
  -H "X-Api-Key: fpk_test_your_api_key"

Next steps

Basic Packing -- standalone packing without the order/shipment lifecycle
Batch Packing -- pack many orders asynchronously
Consolidation -- combine multiple orders into fewer shipments