API docs by Redocly

FractalPack Packing API (1.0.0)

Download OpenAPI specification:

FractalPack Engineering: support@fractalpack.com URL: https://fractalpack.com License: Proprietary

The FractalPack Packing API provides 3D bin-packing, order management, shipment optimization, consolidation, wave planning, and fulfillment planning capabilities.

Scope: this reference documents the public customer surface only. Staff-only routes (under /api/admin/) are intentionally excluded — they require internal Cognito group membership that API key holders cannot satisfy. Admin workflows are documented in the repository's feature docs (docs/feature-named-pipeline-configs.md and related).

All endpoints are served under https://api.fractalpack.com and require authentication via either an API key or a JWT bearer token.

Pack vs. plan — two distinct primitives

POST /api/v1/pack is a single-stage primitive. It runs the 3D bin-packing algorithm against one set of items and returns a direct result. It does NOT load your organization's PipelineConfig, so pallet and equipment rules do not apply. Use /pack for carton-level packing only.

POST /api/v1/fulfillment-plans is the pipeline path. It evaluates parcel vs. LTL vs. FTL strategies, applies your organization's default PipelineConfig (container levels: carton → pallet → equipment), and loads packing policies and rules for each level in the pipeline. Use fulfillment plans when you need multi-level packing, pallet/equipment rules, or cost comparison across shipping modes.

This asymmetry is a deliberate contract. MCP tools and AI-assistant capabilities that call /pack directly are carton-level only by design.

Pagination

List endpoints use cursor-based pagination. Pass limit (page size) and cursor (opaque token from a previous response's nextCursor). The response includes an items array and a nextCursor field (null when there are no more results).

Rate Limiting

Certain endpoint categories are rate-limited: pack, batch, ai, and rates. Every rate-limited response includes these headers:

Header Description
X-RateLimit-Limit Max requests in the current window
X-RateLimit-Remaining Requests remaining
X-RateLimit-Reset Seconds until the window resets
Retry-After Seconds to wait (only on 429)

Errors

All errors use RFC 9457 Problem Details format with a doc_url extension linking to the relevant error documentation.

Packing

Core 3D bin-packing engine

Pack items into containers

Run the 3D bin-packing algorithm to optimally place items into containers. If no containers are specified, the system falls back to the organization's Container Master.

Pack is a single-stage primitive. It does NOT load the organization's PipelineConfig. Pallet-level and equipment-level packing rules do not apply here. To run multi-level packing with pipeline-aware rules, use POST /api/v1/fulfillment-plans.

Rules with no applicableLevels restriction (or with carton in their applicableLevels) are evaluated. By default every such rule the org has marked Enabled runs. To restrict which rules apply for a single request, pass ruleIds: ["..."] — only rules in the whitelist that are also globally Enabled are evaluated. An empty list disables rules for the request.

Rate limit category: pack

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
Array of objects (ItemDto) [ 1 .. 10000 ] items

Items to pack

Array of objects (ContainerDto) <= 1000 items

Fixed-size containers. If omitted, falls back to Container Master.

Array of objects (DynamicContainerDto) <= 1000 items

Variable-size containers

Array of objects (PalletDto) <= 100 items

Pallet definitions

Array of objects (EquipmentDto) <= 100 items

Equipment (trailers, etc.)

allowMultipleBoxes
boolean
Default: true

Allow items to be packed into multiple boxes. Defaults to true. Set to false to enable per-container cartonization fitness mode: the solver reports each candidate container's fit independently rather than packing across multiple boxes.

loadingMode
string
Default: "palletized"

Loading mode: "standard", "palletized"

algorithm
string
Enum: "fpFast" "fpLayer" "ebAfit" "liquidFill"

Packing algorithm: "fpFast" (default), "fpLayer", "liquidFill". The legacy value "ebAfit" is a permanent alias for "fpLayer". Default switched from "fpLayer" to "fpFast" because FpFast packs at a fraction of FpLayer's runtime on production-shaped orders with equivalent quality on most inputs. Pass an explicit algorithm to override.

useCasePacks
boolean
Default: false

Use case pack configurations from items

allowPalletStacking
boolean
Default: false

Allow stacking pallets in trailers

respectTiHi
boolean
Default: true

Use vendor-prescribed Ti/Hi pallet patterns

separationGroups
Array of strings[ items ]

Groups of item tags that cannot share a container. Items from different groups are packed separately.

Array of objects (AffinityGroupDto)

Pin specific items to specific containers

optimizeFor
string
Enum: "volume" "cost"

Optimization objective (default "volume")

originZip
string <= 10 characters

Origin ZIP code (required for cost optimization)

destinationZip
string <= 10 characters

Destination ZIP code (required for cost optimization)

ruleIds
Array of strings

Optional whitelist of rule IDs to apply for this request. When omitted, every globally Enabled PreSolve rule is evaluated automatically (the historical behavior). When provided, only rules whose id is in the list and globally Enabled are evaluated. An empty list disables rules entirely for this request.

Use GET /v1/rules to discover the rules available for your org.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "containers": [
    ],
  • "algorithm": "fpLayer"
}

Response samples

Content type
application/json
{
  • "algorithm": "fpLayer",
  • "results": [
    ],
  • "firedRules": [ ]
}

Batch

Asynchronous batch packing

Submit a batch of packing jobs

Submit up to 10,000 orders for asynchronous packing. Returns immediately with a batch ID and status URL.

Optionally provide a webhookUrl (HTTPS only) to receive a callback when the batch completes.

Rate limit category: batch

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
Array of objects (BatchOrderRequest) [ 1 .. 10000 ] items
webhookUrl
string <uri> <= 2048 characters

HTTPS URL to receive completion callback

Responses

Request samples

Content type
application/json
{
  • "orders": [
    ],
  • "webhookUrl": "https://example.com/webhook/batch-complete"
}

Response samples

Content type
application/json
{
  • "batchId": "bat_abc123",
  • "status": "submitted",
  • "totalOrders": 1,
  • "statusUrl": "/api/v1/batch/bat_abc123"
}

List batches

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

after
string

Pagination cursor from nextPageToken

Responses

Response samples

Content type
application/json
{
  • "batches": [
    ],
  • "nextPageToken": "string",
  • "hasMore": true
}

Get batch status and results

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
batchId
required
string
query Parameters
status
string
Enum: "pending" "completed" "failed"

Filter orders by status

limit
integer [ 1 .. 1000 ]
Default: 100
after
string

Pagination cursor

Responses

Response samples

Content type
application/json
{
  • "batchId": "string",
  • "status": "submitted",
  • "totalOrders": 0,
  • "completedOrders": 0,
  • "failedOrders": 0,
  • "pendingOrders": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "orders": [
    ],
  • "nextPageToken": "string",
  • "hasMore": true
}

Items

Item Master CRUD and bulk operations

Create an item

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
id
required
string [ 1 .. 128 ] characters
name
string <= 256 characters
description
string <= 2000 characters
object
category
string <= 64 characters
commodityCode
string <= 64 characters
hsCode
string <= 64 characters
countryOfOrigin
string <= 64 characters
tags
Array of strings
object
length
required
number <double>

Length in inches

width
required
number <double>
height
required
number <double>
dimensionUnit
string <= 64 characters
weight
required
number <double>

Weight in lbs

netWeight
number <double>
weightUnit
string <= 64 characters
volume
number <double>
volumeUnit
string <= 64 characters
unitOfMeasure
string <= 64 characters
object (RollPropertiesDto)
object (VoidSpaceDto)
shape
string
Enum: "rectangular" "cylindrical" "spherical" "irregular" "lShape" "tShape" "custom"
object
maxWeightOnTop
number <double>
maxStackHeight
integer
crushClass
string
Enum: "none" "light" "moderate" "fragile" "extreme"
shipAlone
boolean
maxPerContainer
integer
Array of objects
casePackQuantity
integer
caseLength
number <double>
caseWidth
number <double>
caseHeight
number <double>
caseWeight
number <double>
object
freightClass
string <= 64 characters
imageUrl
string <uri> <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "id": "WIDGET-001",
  • "name": "Blue Widget",
  • "length": 10,
  • "width": 8,
  • "height": 6,
  • "weight": 2.5,
  • "category": "electronics",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "externalIds": {
    },
  • "category": "string",
  • "tags": [
    ],
  • "length": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "weight": 0.1,
  • "unitOfMeasure": "string",
  • "shape": "string",
  • "shipAlone": true,
  • "packagingLevels": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

List items

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

search
string

Full-text search across ID, name, and description

category
string

Filter by category

tags
string

Comma-separated list of tags to filter by

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get an item by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
itemId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "externalIds": {
    },
  • "category": "string",
  • "tags": [
    ],
  • "length": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "weight": 0.1,
  • "unitOfMeasure": "string",
  • "shape": "string",
  • "shipAlone": true,
  • "packagingLevels": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Partially update an item

Update one or more fields on an item. Requires the current version for optimistic concurrency control.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
itemId
required
string
Request Body schema: application/json
required
version
required
integer >= 1

Current version for optimistic concurrency

name
string <= 256 characters
description
string <= 2000 characters
category
string <= 64 characters
tags
Array of strings
length
number <double>
width
number <double>
height
number <double>
weight
number <double>
shipAlone
boolean
packagingLevels
Array of objects

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "weight": 3,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "externalIds": {
    },
  • "category": "string",
  • "tags": [
    ],
  • "length": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "weight": 0.1,
  • "unitOfMeasure": "string",
  • "shape": "string",
  • "shipAlone": true,
  • "packagingLevels": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Delete an item

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
itemId
required
string

Responses

Response samples

Content type
application/problem+json
{}

Bulk import items

Import up to 1,000 items at once. Existing items (by ID) are updated; new items are created. Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
Array of objects (CreateItemRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "errors": [
    ]
}

Import items from CSV

Upload a CSV file to bulk import items. Max file size: 5 MB. Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "errors": [
    ]
}

Look up an item by external ID

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
type
required
string
Example: type=sku

External ID type (e.g. "sku", "upc", "ean")

value
required
string
Example: value=WIDGET-001

External ID value

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "externalIds": {
    },
  • "category": "string",
  • "tags": [
    ],
  • "length": 0.1,
  • "width": 0.1,
  • "height": 0.1,
  • "weight": 0.1,
  • "unitOfMeasure": "string",
  • "shape": "string",
  • "shipAlone": true,
  • "packagingLevels": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Get multiple items by ID

Retrieve up to 100 items in a single request.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
itemIds
required
Array of strings [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "itemIds": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Containers

Container Master CRUD and bulk operations

Create a container

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
id
required
string [ 1 .. 128 ] characters
name
required
string <= 256 characters
containerType
required
string
Enum: "Box" "Pallet" "Equipment"
description
string <= 2000 characters
subType
string <= 64 characters
tags
Array of strings
object
innerLength
required
number <double>
innerWidth
required
number <double>
innerHeight
required
number <double>
outerLength
number <double>
outerWidth
number <double>
outerHeight
number <double>
dimensionUnit
string <= 64 characters
weightTare
number <double>
weightMaxGross
required
number <double> <= 200000
weightUnit
string <= 64 characters
isDynamic
boolean
minLength
number <double>
minWidth
number <double>
minHeight
number <double>
stackable
boolean
maxStackWeight
number <double>
material
string <= 64 characters
wallThickness
number <double>
baseCost
number <double>
isActive
boolean
Default: true
object
object

Responses

Request samples

Content type
application/json
{
  • "id": "BOX-MEDIUM",
  • "name": "Medium Box",
  • "containerType": "Box",
  • "innerLength": 20,
  • "innerWidth": 15,
  • "innerHeight": 12,
  • "weightMaxGross": 50
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "containerType": "Box",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List containers

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
containerType
string
Enum: "Box" "Pallet" "Equipment"

Filter by container type

search
string

Search by ID or name

tags
string

Comma-separated tags

isActive
boolean

Filter by active status

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get a container by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
containerId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "containerType": "Box",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Partially update a container

Requires the current version for optimistic concurrency.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
containerId
required
string
Request Body schema: application/json
required
version
required
integer >= 1
name
string <= 256 characters
description
string <= 2000 characters
innerLength
number <double>
innerWidth
number <double>
innerHeight
number <double>
weightMaxGross
number <double>
isActive
boolean

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "weightMaxGross": 55
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "containerType": "Box",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a container

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
containerId
required
string

Responses

Response samples

Content type
application/problem+json
{}

Bulk import containers

Import up to 1,000 containers. Existing containers (by ID) are updated; new ones are created. Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
Array of objects (CreateContainerRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "containers": [
    ]
}

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "errors": [
    ]
}

Import containers from CSV

Max file size: 5 MB. Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "created": 0,
  • "updated": 0,
  • "errors": [
    ]
}

Orders

Order lifecycle management

Create an order

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
sourceSystem
string <= 128 characters
sourceOrderId
string <= 128 characters
orderType
string
Default: "Outbound"
Enum: "Outbound" "Inbound" "Transfer" "Return"
priority
string
Default: "Standard"
Enum: "Standard" "High" "Urgent" "Critical"
serviceLevel
string
Default: "Standard"
Enum: "Economy" "Standard" "Expedited" "NextDay" "SameDay"
channel
string <= 128 characters
object (AddressParty)
object (AddressParty)
object
orderedAt
string <date-time>
requiredShipBy
string <date-time>
requiredDeliverBy
string <date-time>
Array of objects
tags
Array of strings
object
externalShipmentId
string <= 128 characters

Host system consolidation signal

submit
boolean
Default: true

If true, order created in RECEIVED status; if false, DRAFT

required
Array of objects (CreateOrderLineRequest) [ 1 .. 200 ] items

Responses

Request samples

Content type
application/json
{
  • "sourceOrderId": "SO-2026-001",
  • "orderType": "Outbound",
  • "priority": "Standard",
  • "shipTo": {
    },
  • "lines": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceSystem": "string",
  • "sourceOrderId": "string",
  • "orderType": "string",
  • "priority": "string",
  • "serviceLevel": "string",
  • "status": "Draft",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "lines": [
    ],
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List orders

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
status
string
Enum: "Draft" "Received" "Planned" "Cancelled"

Filter by order status

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get an order by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceSystem": "string",
  • "sourceOrderId": "string",
  • "orderType": "string",
  • "priority": "string",
  • "serviceLevel": "string",
  • "status": "Draft",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "lines": [
    ],
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update an order

Requires the current version for optimistic concurrency.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
orderId
required
string
Request Body schema: application/json
required
version
required
integer
priority
string
Enum: "Standard" "High" "Urgent" "Critical"
serviceLevel
string
Enum: "Economy" "Standard" "Expedited" "NextDay" "SameDay"
channel
string
object (AddressParty)
object (AddressParty)
requiredShipBy
string <date-time>
requiredDeliverBy
string <date-time>
tags
Array of strings
Array of objects (CreateOrderLineRequest)

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "priority": "Standard",
  • "serviceLevel": "Economy",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "requiredShipBy": "2019-08-24T14:15:22Z",
  • "requiredDeliverBy": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "lines": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceSystem": "string",
  • "sourceOrderId": "string",
  • "orderType": "string",
  • "priority": "string",
  • "serviceLevel": "string",
  • "status": "Draft",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "lines": [
    ],
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Cancel an order

Sets the order status to Cancelled.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceSystem": "string",
  • "sourceOrderId": "string",
  • "orderType": "string",
  • "priority": "string",
  • "serviceLevel": "string",
  • "status": "Draft",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "lines": [
    ],
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Revert an order to its previous status

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceSystem": "string",
  • "sourceOrderId": "string",
  • "orderType": "string",
  • "priority": "string",
  • "serviceLevel": "string",
  • "status": "Draft",
  • "channel": "string",
  • "shipFrom": {
    },
  • "shipTo": {
    },
  • "lines": [
    ],
  • "tags": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Import orders from CSV

Upload a CSV file to import orders. Existing orders (by sourceOrderId) are updated; new orders are created. Max file size: 5 MB.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "ordersCreated": 0,
  • "ordersUpdated": 0,
  • "ordersUnchanged": 0,
  • "totalLines": 0,
  • "errors": [
    ]
}

Shipments

Shipment optimization, rating, and lifecycle

Create a shipment from orders

Creates a shipment from one or more orders. Items are resolved from the Item Master when orders reference itemIds.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
orderIds
required
Array of strings non-empty
packingConfig
object

Optional packing configuration overrides

mode
string
Enum: "Parcel" "Ltl" "Ftl" "Air" "Ocean" "Intermodal"
serviceLevel
string
Enum: "Economy" "Standard" "Expedited" "NextDay" "SameDay"
carrier
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "orderIds": [
    ],
  • "mode": "Parcel",
  • "serviceLevel": "Standard"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List shipments

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
status
string

Filter by shipment status

orderId
string

Filter by order ID

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get a shipment by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a shipment

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string
Request Body schema: application/json
required
version
required
integer
packingConfig
object
mode
string
Enum: "Parcel" "Ltl" "Ftl" "Air" "Ocean" "Intermodal"
serviceLevel
string
Enum: "Economy" "Standard" "Expedited" "NextDay" "SameDay"
carrier
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "packingConfig": { },
  • "mode": "Parcel",
  • "serviceLevel": "Economy",
  • "carrier": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Cancel a shipment

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Run packing optimization on a shipment

Runs the 3D bin-packing algorithm on the shipment's items and updates the shipment with the pack result.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string
Request Body schema: application/json
algorithm
string <= 64 characters

Packing algorithm to use

Responses

Request samples

Content type
application/json
{
  • "algorithm": "fpLayer"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get shipping rates for a shipment

Fetches live shipping rates from connected carriers for the optimized shipment parcels.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string
Request Body schema: application/json
carriers
Array of strings

Carrier IDs to rate (defaults to all connected)

Responses

Request samples

Content type
application/json
{
  • "carriers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Mark a shipment as ready

Transitions the shipment to the Ready state.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "string",
  • "mode": "string",
  • "serviceLevel": "string",
  • "carrier": "string",
  • "packResult": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Rules

Packing rules engine

List all packing rules

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a packing rule

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
id
string <= 128 characters
name
string <= 256 characters
description
string <= 2000 characters
enabled
boolean
Default: true
priority
integer

Lower numbers execute first

ruleType
string
Enum: "BoxSetFilter" "CarrierPackagingRule" "DestinationOverride" "OrderPreprocessing" "IncompatibilityGroup" "StackingConstraint" "OrientationRestriction" "ItemGrouping" "PostSolveValidation" "ObjectiveWeightModifier" "ReSolveTrigger" "ConsolidationProfile"
executionTarget
string
Default: "PreSolve"
Enum: "PreSolve" "SolverConfig" "PostSolve"
object

Condition group with operator and nested conditions

object

Rule action with type and payload

version
integer
createdAt
string <date-time>
updatedAt
string <date-time>
createdBy
string

Responses

Request samples

Content type
application/json
{
  • "name": "Exclude small boxes for heavy items",
  • "ruleType": "BoxSetFilter",
  • "enabled": true,
  • "priority": 10,
  • "conditions": {
    },
  • "action": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "enabled": true,
  • "priority": 0,
  • "ruleType": "BoxSetFilter",
  • "executionTarget": "PreSolve",
  • "conditions": {
    },
  • "action": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Get a rule by ID

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "enabled": true,
  • "priority": 0,
  • "ruleType": "BoxSetFilter",
  • "executionTarget": "PreSolve",
  • "conditions": {
    },
  • "action": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Update a rule

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
id
string <= 128 characters
name
string <= 256 characters
description
string <= 2000 characters
enabled
boolean
Default: true
priority
integer

Lower numbers execute first

ruleType
string
Enum: "BoxSetFilter" "CarrierPackagingRule" "DestinationOverride" "OrderPreprocessing" "IncompatibilityGroup" "StackingConstraint" "OrientationRestriction" "ItemGrouping" "PostSolveValidation" "ObjectiveWeightModifier" "ReSolveTrigger" "ConsolidationProfile"
executionTarget
string
Default: "PreSolve"
Enum: "PreSolve" "SolverConfig" "PostSolve"
object

Condition group with operator and nested conditions

object

Rule action with type and payload

version
integer
createdAt
string <date-time>
updatedAt
string <date-time>
createdBy
string

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "enabled": true,
  • "priority": 0,
  • "ruleType": "BoxSetFilter",
  • "executionTarget": "PreSolve",
  • "conditions": {
    },
  • "action": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "enabled": true,
  • "priority": 0,
  • "ruleType": "BoxSetFilter",
  • "executionTarget": "PreSolve",
  • "conditions": {
    },
  • "action": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Delete a rule

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{}

Consolidation

Multi-order consolidation

Evaluate orders for consolidation

Analyzes a set of orders and suggests consolidation groups based on destination, shipping mode, and profile constraints.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
orderIds
required
Array of strings non-empty
profileId
string

Responses

Request samples

Content type
application/json
{
  • "orderIds": [
    ],
  • "profileId": "prof_default"
}

Response samples

Content type
application/json
{
  • "suggestedGroups": [
    ],
  • "ungrouped": [
    ]
}

Create a consolidation group

Groups orders for consolidated packing. Requires at least 2 orders. Set forceOverride: true to bypass validation warnings.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
profileId
string <= 128 characters
object
sourceOrderIds
required
Array of strings >= 2 items
forceOverride
boolean
Default: false

Override validation warnings

Responses

Request samples

Content type
application/json
{
  • "sourceOrderIds": [
    ],
  • "profileId": "prof_default"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceOrderIds": [
    ],
  • "profileId": "string",
  • "status": "Pending",
  • "groupingKeyValues": {
    },
  • "wasManualOverride": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "version": 0
}

List consolidation groups

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

status
string
Enum: "Pending" "Packed" "Dissolved"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get a consolidation group

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
groupId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceOrderIds": [
    ],
  • "profileId": "string",
  • "status": "Pending",
  • "groupingKeyValues": {
    },
  • "wasManualOverride": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "version": 0
}

Dissolve a consolidation group

Returns member orders to their ungrouped state.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
groupId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceOrderIds": [
    ],
  • "profileId": "string",
  • "status": "Pending",
  • "groupingKeyValues": {
    },
  • "wasManualOverride": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "version": 0
}

Pack a consolidation group

Runs packing optimization on all orders in the group. Items from different orders can be mixed within containers unless the profile disallows it.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
groupId
required
string
Request Body schema: application/json
required
Array of objects (ContainerDto)
Array of objects (DynamicContainerDto)
Array of objects (PalletDto)
Array of objects (EquipmentDto)
algorithm
string <= 64 characters
loadingMode
string <= 64 characters
allowMultipleBoxes
boolean
Default: true
allowPalletStacking
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "containers": [
    ],
  • "dynamicContainers": [
    ],
  • "pallets": [
    ],
  • "equipment": [
    ],
  • "algorithm": "string",
  • "loadingMode": "string",
  • "allowMultipleBoxes": true,
  • "allowPalletStacking": false
}

Response samples

Content type
application/json
{
  • "packResult": {
    },
  • "orderMapping": {
    },
  • "groupId": "string",
  • "groupStatus": "string"
}

Consolidation Profiles

Consolidation profile templates

List consolidation profiles

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create a consolidation profile

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
name
required
string <= 256 characters
description
string <= 2000 characters
groupingKeys
required
Array of strings non-empty

Fields to group by (e.g. "shipTo.postalCode", "serviceLevel")

consolidationLevel
string
Default: "Box"
Enum: "Box" "Pallet"
allowMixedOrdersInCarton
boolean
Default: false
object

Responses

Request samples

Content type
application/json
{
  • "name": "Same-destination consolidation",
  • "groupingKeys": [
    ],
  • "consolidationLevel": "Box",
  • "allowMixedOrdersInCarton": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "groupingKeys": [
    ],
  • "consolidationLevel": "string",
  • "allowMixedOrdersInCarton": true,
  • "constraints": { },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get a consolidation profile

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "groupingKeys": [
    ],
  • "consolidationLevel": "string",
  • "allowMixedOrdersInCarton": true,
  • "constraints": { },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a consolidation profile

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
required
string <= 256 characters
description
string <= 2000 characters
groupingKeys
required
Array of strings non-empty

Fields to group by (e.g. "shipTo.postalCode", "serviceLevel")

consolidationLevel
string
Default: "Box"
Enum: "Box" "Pallet"
allowMixedOrdersInCarton
boolean
Default: false
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "groupingKeys": [
    ],
  • "consolidationLevel": "Box",
  • "allowMixedOrdersInCarton": false,
  • "constraints": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "groupingKeys": [
    ],
  • "consolidationLevel": "string",
  • "allowMixedOrdersInCarton": true,
  • "constraints": { },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a consolidation profile

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{}

Wave Planning

Warehouse wave planning and pick optimization

Generate an optimized wave plan

Analyzes orders and warehouse layout to generate optimized pick waves that minimize travel distance using TSP-based routing.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
Array of objects non-empty
object

Responses

Request samples

Content type
application/json
{
  • "orders": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "warehouseId": "string",
  • "waves": [
    ],
  • "summary": {
    }
}

List available wave planning algorithms

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • "nearest-neighbor-2opt",
  • "nearest-neighbor"
]

Fulfillment Plans

Multi-modal fulfillment strategy evaluation

Create a fulfillment plan

Evaluates parcel vs LTL vs FTL shipping strategies for the given orders and returns options with cost breakdowns.

This is the pipeline path. Unlike POST /api/v1/pack (which is a single-stage carton-only primitive), fulfillment plans load the organization's PipelineConfig and apply packing rules at each container level (carton → pallet → equipment). Pallet-level and equipment-level rules only fire here.

Orders whose total unit count is at or below the tier-1 threshold (SSM /fractalpack/compute/tier-1-max-units, currently 1,000) return 201 Created with the full plan inline.

Orders above the threshold return 202 Accepted immediately with a planId and a statusUrl. Poll GET /api/v1/fulfillment-plans/{planId} every 2 seconds until status is a terminal value (ready, failed, expired).

When request-level overrides (Load Planner toggles or containerLevels) narrow the effective level set below what the dispatched pipeline defines, the plan records a plan.levels_narrowed_by_override warning in FulfillmentPlan.warnings. Check this field after the plan reaches ready status.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
orderIds
required
Array of strings non-empty
packingConfig
object

Packing configuration overrides

parcelCarriers
Array of strings

Parcel carrier IDs to rate (defaults to all connected)

ltlCarriers
Array of strings

LTL carrier IDs to rate (defaults to all connected)

ruleIds
Array of strings

Optional whitelist of rule IDs to apply when evaluating this plan. When omitted, every globally Enabled PreSolve rule applies (default). When provided, only rules whose id is in the list and globally Enabled are evaluated across the parcel, LTL, and FTL strategies. An empty list disables rules entirely.

Use GET /v1/rules to discover the rules available for your org. Drives the Load Planner's per-plan rule selection card.

Responses

Request samples

Content type
application/json
{
  • "orderIds": [
    ],
  • "parcelCarriers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "pending",
  • "options": {
    },
  • "error": "string",
  • "resultUrl": "https://s3.amazonaws.com/fractalpack-data/org123/p_550e/plan.json?X-Amz-Expires=3600&...",
  • "estimatedDurationSeconds": 90,
  • "selectedOptionKey": "string",
  • "shipmentIds": [
    ],
  • "warnings": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List fulfillment plans

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
status
string

Filter by plan status

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of items to return

cursor
string

Opaque pagination cursor from a previous response's nextCursor

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Get a fulfillment plan

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
planId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "pending",
  • "options": {
    },
  • "error": "string",
  • "resultUrl": "https://s3.amazonaws.com/fractalpack-data/org123/p_550e/plan.json?X-Amz-Expires=3600&...",
  • "estimatedDurationSeconds": 90,
  • "selectedOptionKey": "string",
  • "shipmentIds": [
    ],
  • "warnings": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Cancel a fulfillment plan

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
planId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "pending",
  • "options": {
    },
  • "error": "string",
  • "resultUrl": "https://s3.amazonaws.com/fractalpack-data/org123/p_550e/plan.json?X-Amz-Expires=3600&...",
  • "estimatedDurationSeconds": 90,
  • "selectedOptionKey": "string",
  • "shipmentIds": [
    ],
  • "warnings": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Select a fulfillment option

Select an option (e.g. "parcel" or "ltl") from a ready plan. This creates the corresponding shipment(s).

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
planId
required
string
Request Body schema: application/json
required
optionKey
required
string

Option key to select (e.g. "parcel", "ltl")

Responses

Request samples

Content type
application/json
{
  • "optionKey": "parcel"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orderIds": [
    ],
  • "status": "pending",
  • "options": {
    },
  • "error": "string",
  • "resultUrl": "https://s3.amazonaws.com/fractalpack-data/org123/p_550e/plan.json?X-Amz-Expires=3600&...",
  • "estimatedDurationSeconds": 90,
  • "selectedOptionKey": "string",
  • "shipmentIds": [
    ],
  • "warnings": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Integrations

ERP/host system connectors and webhooks

List configured integrations

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List available connector types

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get integration config for a connector type

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string
Example: sap-s4hana

Responses

Response samples

Content type
application/json
{
  • "connectorType": "string",
  • "displayName": "string",
  • "enabled": true,
  • "tenantUrl": "string",
  • "fieldMappings": {
    },
  • "settings": {
    },
  • "status": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Create or update an integration

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string
Request Body schema: application/json
required
tenantUrl
string
enabled
boolean
object

Connector-specific credentials (stored encrypted)

object (IntegrationSettings)
object (IntegrationFieldMappings)

Responses

Request samples

Content type
application/json
{
  • "tenantUrl": "https://my-sap.example.com",
  • "enabled": true,
  • "credentials": {
    },
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "connectorType": "string",
  • "displayName": "string",
  • "enabled": true,
  • "tenantUrl": "string",
  • "fieldMappings": {
    },
  • "settings": {
    },
  • "status": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete an integration

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/problem+json
{}

Test integration connectivity

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "latencyMs": 0
}

Trigger a master data sync

Pulls items and/or orders from the connected host system.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "itemsSynced": 0,
  • "itemsSkipped": 0,
  • "warnings": [
    ],
  • "errors": [
    ]
}

Get last sync status

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "lastSyncAt": "2019-08-24T14:15:22Z",
  • "lastSyncStatus": "string",
  • "lastSyncItemCount": 0,
  • "lastError": "string"
}

Get field mappings for an integration

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "itemMappings": [
    ],
  • "deliveryMappings": [
    ]
}

Update field mappings

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string
Request Body schema: application/json
required
Array of objects (FieldMappingRule)
Array of objects (FieldMappingRule)

Responses

Request samples

Content type
application/json
{
  • "itemMappings": [
    ],
  • "deliveryMappings": [
    ]
}

Response samples

Content type
application/json
{
  • "itemMappings": [
    ],
  • "deliveryMappings": [
    ]
}

Reset field mappings to defaults

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "itemMappings": [
    ],
  • "deliveryMappings": [
    ]
}

Get default field mapping template

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
connectorType
required
string

Responses

Response samples

Content type
application/json
{
  • "itemMappings": [
    ],
  • "deliveryMappings": [
    ]
}

Receive a webhook from a host system

Unauthenticated endpoint for receiving push notifications from connected host systems. Validated via HMAC signature in the X-Webhook-Signature header.

path Parameters
connectorType
required
string
orgId
required
string
header Parameters
X-Webhook-Signature
string

HMAC-SHA256 signature of the request body

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "success": true,
  • "itemsSynced": 0,
  • "itemsSkipped": 0,
  • "warnings": [
    ],
  • "errors": [
    ]
}

Identity

Current user and algorithm information

Get the current authenticated user

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "orgId": "org_abc123",
  • "isAdmin": false
}

List available packing algorithms

Public endpoint (no authentication required).

Responses

Response samples

Content type
application/json
{
  • "algorithms": [
    ],
  • "defaultAlgorithm": "fpFast"
}

API Keys

API key management

Create an API key

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
label
string <= 256 characters

Human-readable label for the key

expiresInDays
integer

Expiration in days (null = no expiration)

Responses

Request samples

Content type
application/json
{
  • "label": "Production integration",
  • "expiresInDays": 365
}

Response samples

Content type
application/json
{
  • "keyId": "key_abc123",
  • "label": "Production integration",
  • "apiKey": "fpk_live_abc123def456...",
  • "keyPrefix": "fpk_live_abc",
  • "isActive": true,
  • "createdAt": "2026-04-01T00:00:00Z",
  • "expiresAt": "2027-04-01T00:00:00Z",
  • "mode": "live"
}

List API keys

Returns all API keys for the organization. The full key value is never returned after creation, only the prefix.

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revoke an API key

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
keyId
required
string

Responses

Response samples

Content type
application/problem+json
{}

Users

Organization user management. Requires the admin role within your organization.

List users

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
email
required
string <email> <= 256 characters
temporaryPassword
required
string [ 1 .. 256 ] characters
isAdmin
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "email": "newuser@example.com",
  • "temporaryPassword": "TempPass123!",
  • "isAdmin": false
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "nickname": "string",
  • "status": "string",
  • "enabled": true,
  • "isAdmin": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "nickname": "string",
  • "status": "string",
  • "enabled": true,
  • "isAdmin": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Update a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string
Request Body schema: application/json
required
nickname
string <= 256 characters
isAdmin
boolean

Responses

Request samples

Content type
application/json
{
  • "nickname": "John",
  • "isAdmin": true
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "nickname": "string",
  • "status": "string",
  • "enabled": true,
  • "isAdmin": true,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/problem+json
{}

Disable a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/problem+json
{}

Enable a user

Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/problem+json
{}

Reset a user's password

Sends a password reset email. Requires admin role.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
username
required
string

Responses

Response samples

Content type
application/problem+json
{}

Usage

Usage statistics

Get usage statistics

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
days
integer
Default: 30

Number of days to include

Responses

Response samples

Content type
application/json
{
  • "totalRequests": 12450,
  • "totalItemsPacked": 89300,
  • "totalContainersUsed": 4200,
  • "dailyBreakdown": [
    ]
}

Entitlements

Organization entitlements and limits

Get organization entitlements

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "enabledProducts": [
    ],
  • "maxUsers": 25,
  • "rateLimits": {
    },
  • "monthlyRequestQuota": 100000
}

Packing Policies

Packing policy and rule authoring — list, create, update, and lint policies; run the policy simulator

List packing policies

Returns all packing policies for the authenticated organization, including disabled ones.

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a packing policy

Creates a packing policy for the authenticated organization. selector.customers and selector.sites each accept at most 100 entries. ruleIds accepts at most 500 entries.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
name
string <= 256 characters

Human-readable policy name

enabled
boolean
Default: true

When false, the policy is ignored during evaluation

object (PolicySelector)

Axis-based selector. A policy matches a request when ALL provided axes match. Omit an axis to match all values on that axis.

ruleIds
Array of strings <= 500 items

Ordered list of rule IDs this policy contributes. At most 500 entries. Only rules that are globally Enabled are evaluated.

Responses

Request samples

Content type
application/json
{
  • "name": "LTL Rules",
  • "enabled": true,
  • "selector": {
    },
  • "ruleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "selector": {
    },
  • "ruleIds": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Get a packing policy

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "selector": {
    },
  • "ruleIds": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Update a packing policy

Optimistic-concurrency update. Include the current version in the body. If the stored version differs, the response is 409 with the current policy in the body so you can refresh and retry.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string <= 256 characters

Human-readable policy name

enabled
boolean
Default: true

When false, the policy is ignored during evaluation

object (PolicySelector)

Axis-based selector. A policy matches a request when ALL provided axes match. Omit an axis to match all values on that axis.

ruleIds
Array of strings <= 500 items

Ordered list of rule IDs this policy contributes. At most 500 entries. Only rules that are globally Enabled are evaluated.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "selector": {
    },
  • "ruleIds": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "enabled": true,
  • "selector": {
    },
  • "ruleIds": [
    ],
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string"
}

Disable a packing policy

Soft-deletes the policy by setting enabled: false. The policy remains queryable for audit purposes. To permanently remove a rule reference, update the policy's ruleIds list instead.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{}

Simulate policy evaluation

Runs the full policy pipeline against a sample request and returns the activated rule set plus three diagnostic columns, without persisting anything or affecting live traffic metrics.

Column 1 — Pipeline: which PipelineConfig was resolved and how (resolvedVia values: orgPointer, fallbackOldest, autoCreated).

Column 2 — Policies: every enabled policy, whether it matched, and — for non-matching policies — which selector axes failed (customers, modes, sites).

Column 3 — Per-level breakdown: for each container level in the resolved pipeline, which rules fired and which were skipped, with skip reasons (e.g. ApplicableLevels=[pallet]).

When no policies are enabled, the response includes fallbackBanner: "all tenant rules activate (fallback)" — making fallback mode explicit.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
required
object (PackRequest)

Pack request to simulate against

object

Optional context hints for the simulation

Responses

Request samples

Content type
application/json
{
  • "request": {
    },
  • "hints": {
    }
}

Response samples

Content type
application/json
{
  • "matchedPolicyIds": [
    ],
  • "activatedRuleIds": [
    ],
  • "diagnostics": [
    ],
  • "fingerprint": "string",
  • "shortCircuited": true,
  • "shortCircuitReason": "no_policies_registered",
  • "fallbackBanner": "string",
  • "pipeline": {
    },
  • "policies": [
    ],
  • "levels": {
    }
}

Lint packing policy configuration

Scans the organization's packing policies, rules, and pipeline configuration for dead config, stranded rules, and other issues. Read-only — no side effects.

Pass ?pipelineConfigId={id} to scope level-membership findings to a single named pipeline. Without this parameter, findings are computed against the union of all org pipelines and the default pipeline. Org-level signals (lint.zero_enabled_policies_fallback, lint.policy_references_missing_rule, etc.) are unaffected by the filter.

lint.rule_level_not_in_any_pipeline is scope-dependent: without the filter it means the level is absent from every pipeline in the org; with ?pipelineConfigId= it means the level is absent from that specific pipeline (it may exist in other pipelines). The finding message names the scope so the distinction is machine-readable.

An unknown or cross-org pipelineConfigId returns 404 with error code pipeline.not_found.

Changed in PR6 (2026-06-10): ?pipelineConfigId is now wired; previously the parameter was accepted but had no effect.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
pipelineConfigId
string

Scope level-membership findings to this named pipeline config. Must belong to the authenticated organization.

Responses

Response samples

Content type
application/json
{
  • "findings": [
    ],
  • "summary": {
    }
}

Pipeline Config

Pipeline configuration lifecycle — named configs, create-from-template, set default, and delete

Get the default pipeline config (legacy)

Returns the organization's resolved default PipelineConfig. If no configs exist, one is created automatically with the standard defaults ([carton, pallet, equipment], algorithm fpFast).

This is the legacy single-config endpoint. Use GET /api/v1/settings/pipeline-configs to list all named configs with the provenance-true default badge.

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "orgId": "string",
  • "name": "Default",
  • "containerLevels": [
    ],
  • "algorithm": "fpFast",
  • "assignmentStrategy": "greedy",
  • "allowMultipleBoxes": true,
  • "useCasePacks": false,
  • "loadingMode": "string",
  • "allowPalletStacking": false,
  • "respectTiHi": true,
  • "timeBudgetSeconds": 0,
  • "liquidFillRate": 0.1,
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update the default pipeline config (legacy)

Edits the default pipeline config. Requires the admin role within your organization (API key returns 403).

Include the current version for optimistic concurrency. If the update would orphan rules (remove a level that existing rules target), the response is 409 with code pipeline.orphans_rules listing the affected rules. To proceed, re-send the request with confirmOrphanedRuleDisable: true in the body — orphaned rules are disabled with an audit note.

This is the legacy single-config endpoint. Use PATCH /api/v1/settings/pipeline-configs/{id} to edit a named config by ID.

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
version
required
integer

Current stored version; request is rejected if it differs

name
string
Array of objects (LevelConfig)

Ordered level list. Only carton, pallet, and equipment are accepted.

algorithm
string
assignmentStrategy
string
allowMultipleBoxes
boolean
useCasePacks
boolean
loadingMode
string
allowPalletStacking
boolean
respectTiHi
boolean
timeBudgetSeconds
integer
liquidFillRate
number <double>
confirmOrphanedRuleDisable
boolean
Default: false

Set to true to confirm that rules fully orphaned by a level-removing edit should be disabled (with an audit note). Without this field (or when false), the request returns 409 with code pipeline.orphans_rules when orphans would be created.

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "name": "string",
  • "containerLevels": [
    ],
  • "algorithm": "string",
  • "assignmentStrategy": "string",
  • "allowMultipleBoxes": true,
  • "useCasePacks": true,
  • "loadingMode": "string",
  • "allowPalletStacking": true,
  • "respectTiHi": true,
  • "timeBudgetSeconds": 0,
  • "liquidFillRate": 0.1,
  • "confirmOrphanedRuleDisable": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "containerLevels": [
    ],
  • "algorithm": "string",
  • "assignmentStrategy": "string",
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "disabledRuleIds": [
    ],
  • "warnings": [
    ],
  • "disableFailures": [
    ]
}

List all pipeline configs

Returns all named pipeline configs for the organization, plus the ID of the current default. The default badge is provenance-true: it reflects org.DefaultPipelineConfigId, not sort order.

This endpoint is read-only. It does not auto-create a config when the list is empty — the legacy GET /api/v1/settings/pipeline-config retains that behavior.

Added in PR6 (2026-06-10).

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
{
  • "defaultPipelineConfigId": "abc123",
  • "configs": [
    ]
}

Create a pipeline config

Creates a named pipeline config for the organization. Requires the admin role (API key returns 403).

Pass either template (one of parcel-only, palletize, full) or containerLevels — not both. Template definitions:

Template Levels
parcel-only [carton]
palletize [carton, pallet]
full [carton, pallet, equipment]

The supported vocabulary is carton, pallet, and equipment. Submitting any other level value — including innerpack — returns 400 with code pipeline.unsupported_level.

Added in PR6 (2026-06-10).

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
string

Display name for the new config

template
string
Enum: "parcel-only" "palletize" "full"

Built-in topology template.

  • parcel-only → [carton]
  • palletize → [carton, pallet]
  • full → [carton, pallet, equipment]
Array of objects (LevelConfig)

Custom ordered level list (bottom-up). Each entry is { "level": "<name>" }. Only carton, pallet, and equipment are accepted; any other value returns 400 with code pipeline.unsupported_level.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Parcel Only",
  • "template": "parcel-only"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "orgId": "string",
  • "name": "Default",
  • "containerLevels": [
    ],
  • "algorithm": "fpFast",
  • "assignmentStrategy": "greedy",
  • "allowMultipleBoxes": true,
  • "useCasePacks": false,
  • "loadingMode": "string",
  • "allowPalletStacking": false,
  • "respectTiHi": true,
  • "timeBudgetSeconds": 0,
  • "liquidFillRate": 0.1,
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update a pipeline config by ID

Edits a named pipeline config. Requires the admin role (API key returns 403).

Include the current version for optimistic concurrency. Level-removing edits that would orphan rules return 409 with code pipeline.orphans_rules; re-send with confirmOrphanedRuleDisable: true in the body to proceed.

Added in PR6 (2026-06-10).

Authorizations:
BearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
version
required
integer

Current stored version; request is rejected if it differs

name
string
Array of objects (LevelConfig)

Ordered level list. Only carton, pallet, and equipment are accepted.

algorithm
string
assignmentStrategy
string
allowMultipleBoxes
boolean
useCasePacks
boolean
loadingMode
string
allowPalletStacking
boolean
respectTiHi
boolean
timeBudgetSeconds
integer
liquidFillRate
number <double>
confirmOrphanedRuleDisable
boolean
Default: false

Set to true to confirm that rules fully orphaned by a level-removing edit should be disabled (with an audit note). Without this field (or when false), the request returns 409 with code pipeline.orphans_rules when orphans would be created.

Responses

Request samples

Content type
application/json
{
  • "version": 0,
  • "name": "string",
  • "containerLevels": [
    ],
  • "algorithm": "string",
  • "assignmentStrategy": "string",
  • "allowMultipleBoxes": true,
  • "useCasePacks": true,
  • "loadingMode": "string",
  • "allowPalletStacking": true,
  • "respectTiHi": true,
  • "timeBudgetSeconds": 0,
  • "liquidFillRate": 0.1,
  • "confirmOrphanedRuleDisable": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "containerLevels": [
    ],
  • "algorithm": "string",
  • "assignmentStrategy": "string",
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "disabledRuleIds": [
    ],
  • "warnings": [
    ],
  • "disableFailures": [
    ]
}

Delete a pipeline config

Deletes a named pipeline config. Requires the admin role (API key returns 403).

Blocked when the config is the current default — set another config as default first (POST .../set-default). Returns 409 with code pipeline.delete_default_blocked.

Blocked when the config is the only config for the org — it is necessarily the fallback default. Returns 409 with pipeline.delete_default_blocked.

When deletion would orphan rules (the config's levels are not covered by any remaining pipeline), the response is 409 with code pipeline.delete_orphans_rules listing the affected rules. Re-send with ?confirmOrphanedRuleDisable=true to proceed — fully orphaned rules are disabled with an audit note; partially orphaned rules (covered by another pipeline) receive a warning.

Added in PR6 (2026-06-10).

Authorizations:
BearerAuth
path Parameters
id
required
string
query Parameters
confirmOrphanedRuleDisable
boolean

Pass true to confirm disabling rules fully orphaned by this deletion. Idempotent.

Responses

Response samples

Content type
application/json
{
  • "deleted": "string",
  • "disabledRuleIds": [
    ],
  • "warnings": [
    ],
  • "disableFailures": [
    ]
}

Set the default pipeline config

Sets the organization's explicit default pipeline. Requires the admin role (API key returns 403). Idempotent — setting the already-default config returns 200 with no change.

After this call, GET /api/v1/packing-policies/simulate will show resolvedVia: "orgPointer" and the chosen config's levels.

The target config must exist and belong to the authenticated org. A nonexistent or cross-org ID returns 404 with code pipeline.not_found.

Added in PR6 (2026-06-10).

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "defaultPipelineConfigId": "def456"
}