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 runs the 3D bin-packing algorithm against the containers you supply and returns a direct result. It does NOT load your organization's PipelineConfig. The response includes results (carton-level), palletResults, trailerResults, firedRules, containerTree, and assignmentStrategy depending on which container levels you supply. For large item quantities, /pack may return 202 Accepted with a job ID — poll GET /api/v1/jobs/{jobId} to retrieve the result.

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 policy-governed multi-level packing or cost comparison across shipping modes.

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.

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.

Async execution for large requests: requests with a large item quantity may return 202 Accepted instead of 200 OK. The 202 body includes a jobId and statusUrl. Poll GET /api/v1/jobs/{jobId} until status is completed, then read the full PackResponse from the result field. Clients that only handle 200 will silently miss packing results on large requests.

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" "liquidFill"

Packing algorithm: "fpFast" (default), "fpLayer", "liquidFill". Default is "fpFast" because it 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",
  • "assignmentStrategy": "greedy",
  • "results": [
    ],
  • "palletResults": null,
  • "trailerResults": null,
  • "firedRules": [ ],
  • "containerTree": null
}

Get async pack job status and result

Poll this endpoint after receiving a 202 from POST /api/v1/pack. When status is completed, the full PackResponse is available in the result field. When status is failed, inspect error for details.

Job records expire after a short TTL. Retrieve the result promptly after completed status is observed.

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
jobId
required
string
Example: j_1f7d3adf97f84e639ab891fd245386cf

Job ID returned in the 202 response from POST /api/v1/pack

Responses

Response samples

Content type
application/json
{
  • "jobId": "j_1f7d3adf97f84e639ab891fd245386cf",
  • "status": "completed",
  • "totalUnits": 5000,
  • "result": {
    }
}

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": "b_aded25bf1234",
  • "status": "submitted",
  • "totalOrders": 1,
  • "statusUrl": "/api/v1/batch/b_aded25bf1234"
}

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
sku
string <= 128 characters

Top-level SKU for the item. Stored and indexed separately from externalIds. Use GET /api/v1/items/lookup?type=sku&value=... to look up by SKU.

object

Typed external identifiers for the item. Only the documented keys are persisted — unknown keys are rejected with 400. For arbitrary key-value data, use customAttributes instead.

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> [ 0 .. 1200 ]

Length in inches. Maximum 1,200 in.

width
required
number <double> [ 0 .. 1200 ]

Width in inches. Maximum 1,200 in.

height
required
number <double> [ 0 .. 1200 ]

Height in inches. Maximum 1,200 in.

dimensionUnit
string <= 64 characters
weight
required
number <double> [ 0 .. 500000 ]

Weight in lbs. Maximum 500,000 lb.

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",
  • "sku": "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

Search across item ID, name, and description. Results are bounded by cursor-based pagination; page size is capped at 100 rows. Walk the cursor to scan the full set — a single page does not cover all items in large catalogs.

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",
  • "sku": "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",
  • "sku": "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 or SKU

Resolve an item by one of its identifiers. The type parameter is case-insensitive.

Accepted type values: sku, gtin, upc, ean, vendorPartNumber, customerPartNumber.

sku resolves against the top-level sku field on the item record. The other types resolve against the corresponding key in externalIds.

Authorizations:
ApiKeyAuthBearerAuth
query Parameters
type
required
string
Enum: "sku" "gtin" "upc" "ean" "vendorPartNumber" "customerPartNumber"
Example: type=gtin

Identifier type to look up (case-insensitive)

value
required
string
Example: value=00012345678905

Identifier value to match

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "sku": "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",
  • "subType": "string",
  • "material": "string",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "outerLength": 0.1,
  • "outerWidth": 0.1,
  • "outerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "usedAtLevels": [
    ],
  • "orgId": "string",
  • "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. Value is case-sensitive — use the exact enum casing (Box, Pallet, Equipment). An unrecognized value returns 400.

search
string

Search by container ID or name. Results are bounded by cursor-based pagination. Walk the cursor to scan the full set.

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",
  • "subType": "string",
  • "material": "string",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "outerLength": 0.1,
  • "outerWidth": 0.1,
  • "outerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "usedAtLevels": [
    ],
  • "orgId": "string",
  • "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",
  • "subType": "string",
  • "material": "string",
  • "innerLength": 0.1,
  • "innerWidth": 0.1,
  • "innerHeight": 0.1,
  • "outerLength": 0.1,
  • "outerWidth": 0.1,
  • "outerHeight": 0.1,
  • "weightMaxGross": 0.1,
  • "weightTare": 0.1,
  • "isDynamic": true,
  • "isActive": true,
  • "usedAtLevels": [
    ],
  • "orgId": "string",
  • "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

Create a new order. If a line references an itemId, that item must exist in the Item Master — an unknown itemId returns 400 with error code order.unknown_item. Lines without an itemId must include inline dimensions (length, width, height, weight).

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)

Nested address shape used for shipTo and shipFrom. Street-level fields live inside the address object — flat top-level fields such as addressLine1 and postalCode are not accepted and are silently dropped if sent.

object (AddressParty)

Nested address shape used for shipTo and shipFrom. Street-level fields live inside the address object — flat top-level fields such as addressLine1 and postalCode are not accepted and are silently dropped if sent.

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. An unrecognized value returns 400. The filter is applied per page — walk the full cursor to ensure all matching orders are retrieved when using a small limit.

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

Partially update an order. version is required — omitting it or sending a stale value both return 409 Conflict.

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)

Nested address shape used for shipTo and shipFrom. Street-level fields live inside the address object — flat top-level fields such as addressLine1 and postalCode are not accepted and are silently dropped if sent.

object (AddressParty)

Nested address shape used for shipTo and shipFrom. Street-level fields live inside the address object — flat top-level fields such as addressLine1 and postalCode are not accepted and are silently dropped if sent.

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. Max file size: 5 MB.

Column contract:

Column Required Notes
sourceOrderId Yes Groups rows into orders — one order per distinct value
quantity Yes The column quantityOrdered is accepted as an alias
sku No Item SKU for the line
itemId No Item Master ID (alternative to sku)

One order is created per distinct sourceOrderId in the file. Rows that share a sourceOrderId become lines on the same order.

Re-importing a file with an existing sourceOrderId upserts that order (updates lines). The sourceSystem column is not required.

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

Polymorphic — body shape selects the path:

Path 1 — order fulfillment (UNGATED): supply orderIds to create a packing shipment in Draft/Created status. Items are resolved from the Item Master. This path is available to all authenticated organizations.

Path 2 — standalone carrier create+execute (EARLY ACCESS): supply carrierId, parcels, shipFrom, shipTo, and serviceCode (no orderIds). FractalPack creates the shipment record and buys the label in a single call, returning the unified Shipment with an execution node (tracking number, piece document URLs). Label bytes are never returned inline — retrieve documents via the URLs in execution.documents[].url.

The standalone path requires the carrier-execution-enabled AppConfig flag (default off) and the carrier-execution entitlement on your organization. When the flag is off, the standalone path returns 404. When the org lacks the entitlement, it returns 403.

Changed in Phase U (2026-06-24): this endpoint is now served through the public gateway (api.fractalpack.com). Previously, carrier execution was only reachable through the ShippingApi internal path. Entitlement enforcement has been re-homed from ShippingApi to this endpoint; the entitlement key is carrier-execution (unchanged from P1/P2).

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
One of
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
Example
{
  • "orderIds": [
    ],
  • "mode": "Parcel",
  • "serviceLevel": "Standard"
}

Response samples

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

Cancel or void a shipment

Polymorphic behavior — gating depends on shipment state:

  • Non-executed shipment (execution is null): cancels the local record. Ungated — requires authentication only. Status transitions to Cancelled.

  • Executed shipment (execution is present, shipment was tendered to a carrier): voids the carrier label via the carrier's void API, then cancels the local record. Early access — requires the carrier-execution-enabled AppConfig flag (default off) and the carrier-execution entitlement.

Updated in: Phase U PR2 (2026-06-24)

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": {
    },
  • "execution": {
    },
  • "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": {
    },
  • "execution": {
    },
  • "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": {
    },
  • "execution": {
    },
  • "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": {
    },
  • "execution": {
    },
  • "version": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Execute (buy a label for) an existing shipment

Early access — requires the carrier-execution-enabled AppConfig flag (default off) and the carrier-execution entitlement.

Tenders an existing shipment to a carrier and returns the unified Shipment with an execution node populated. The shipment must be in Ready or Rated status; any other status returns 400.

FractalPack calls the carrier's label API service-to-service, persists the result (tracking number, document URLs) onto the shipment record, and transitions status to Tendered. Label bytes are never returned inline — retrieve documents via the URLs in execution.documents[].url.

The carrier, service code, and parcel list may optionally be overridden in the request body. When omitted, FractalPack uses the carrier and parcels already associated with the shipment's rate plan.

Concurrency: if two requests race to execute the same shipment, exactly one succeeds with 200; the other receives 409 Conflict.

Added in: Phase U PR2 (2026-06-24, flagged off, early access only)

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string

Shipment ID (shp_*) to execute.

Request Body schema: application/json
optional
carrierId
string <= 128 characters

Override the carrier. Defaults to the shipment's rated carrier.

serviceCode
string <= 64 characters

Override the service code.

labelFormat
string <= 16 characters
Default: "PDF"

Label output format.

Array of objects (ShipmentParcel)

Override the parcel list. Defaults to the shipment's pack plan parcels.

Array of objects (AccessorialRequest)

Override accessorial service requests.

Responses

Request samples

Content type
application/json
{
  • "carrierId": "fedex",
  • "serviceCode": "FEDEX_GROUND",
  • "labelFormat": "ZPLII"
}

Response samples

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

Get current tracking status for an executed shipment

Early access — requires the carrier-execution-enabled AppConfig flag (default off) and the carrier-execution entitlement. Metered usage.

Returns the current carrier tracking status and event history for a shipment that has been executed (tendered to a carrier). FractalPack resolves the carrier tracking number from the shipment record and proxies the carrier's tracking response.

Returns 404 when the shipment has not been executed (execution is null).

Pilot carriers: FedEx, UPS, and USPS.

Added in: Phase U PR2 (2026-06-24, flagged off, early access only)

Authorizations:
ApiKeyAuthBearerAuth
path Parameters
shipmentId
required
string

Shipment ID (shp_*) of an executed shipment.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "trackingNumber": "449044304137821",
  • "status": "InTransit",
  • "events": [
    ],
  • "estimatedDeliveryDate": "2026-06-27T00:00:00Z",
  • "errorMessage": null
}

Carriers

Carrier capabilities — address validation and carrier-level operations.

Early access: address validation requires the carrier-execution-enabled feature flag (default off) and the carrier-execution entitlement. Contact your account manager to request access.

Validate and normalize a street address

Validates and normalizes a street address against a carrier's address-validation service. Returns a carrier-standardized form of the address and suggestions when the input is ambiguous.

Ungated: requires authentication and a connected carrier account only — no feature flag or entitlement check. This is a pre-purchase utility (no carrier spend, no label produced).

Pilot carriers: FedEx, UPS, and USPS.

Added in: Phase U PR2 (2026-06-24)

Authorizations:
ApiKeyAuthBearerAuth
Request Body schema: application/json
required
carrierId
required
string

Carrier to validate against. Pilot carriers — fedex, ups, usps.

required
object (ShipmentAddress)

Postal address for a shipment origin or destination.

Responses

Request samples

Content type
application/json
{
  • "carrierId": "fedex",
  • "address": {
    }
}

Response samples

Content type
application/json
Example
{
  • "isValid": true,
  • "normalizedAddress": {
    },
  • "suggestions": [ ],
  • "errorMessage": null
}

Rules

Packing rules engine

List all packing rules

Authorizations:
ApiKeyAuthBearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a packing rule

Create a packing rule. Validation enforced at create time:

  • name is required and must be non-empty — omitting it or sending an empty string returns 400.
  • Condition leaf objects use the key attribute (not field). An unknown key is rejected with 400.
  • attribute must be non-empty — an empty string returns 400.
  • operator is required on condition leaf objects — omitting it returns 400.
  • value must be a string — numeric values return 400.

For PUT /api/v1/rules/{id}: the id in the request body must match the path id, or the request returns 400. The PUT enforces optimistic concurrency — send the current version; a stale version returns 409.

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

Replace a rule. The id in the request body must match the path id — a mismatch returns 400. Include the current version for optimistic concurrency; a stale or missing version returns 409.

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.

Data sources. By default the plan runs against the organization's stored warehouse and inventory. For a self-contained request (e.g. a WMS integrating without pre-provisioning), supply locations and/or inventory inline — each is resolved independently: present → used, omitted → stored fallback, [] → explicit empty. The response is the same either way and includes a quantity-aware fill-rate summary.

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

Optional inline warehouse locations for a self-contained request. When present, wave planning runs against this set instead of the organization's stored warehouse. When omitted, falls back to stored data. An explicit empty array [] means "no locations" (degenerate plan) — distinct from omitting the field. Resolved independently of inventory. Maximum 5,000 locations per request; for larger sets use stored data or the bulk-ingestion API.

Array of objects <= 20000 items

Optional inline inventory records for a self-contained request. When present, the quantity-aware allocation pool is built from this set instead of the organization's stored inventory. When omitted, falls back to stored data. An explicit empty array [] means "no stock" (everything short). Resolved independently of locations. Duplicate (sku, locationId) records resolve last-wins. Maximum 20,000 records per request; for larger sets use stored data or the bulk-ingestion API.

Responses

Request samples

Content type
application/json
Example
{
  • "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"
}