Skip to main content

Operations

Bulk order operations and execution

All endpoints require a bearer token (oh_... API key or user JWT) and are served under https://api.orderly-hub.com. Use the Try it consoles to run a request against the Preview (test) server.

Actions​

GET /api/v1/operations/actions returns 24 actions in five categories. Each action lists its parameters; a parameter's type tells a client which control to render, help is a one-line hint, default is the value applied when the parameter is omitted, and dependsOn on a field-value parameter names the sibling parameter whose chosen option decides the control.

CategoryActions
routingassign-location, assign-default-location, override-dispatcher, rate-and-assign, assign-service, override-carrier, clear-service
fulfillmentrelease, unrelease, mark-fulfilled, mark-shipped, cancel-orders
labelsvoid-label, reprint-documents
inventoryallocate, pick
dataapply-tag, remove-tag, clear-tags, add-note, set-priority, set-ship-date, bulk-edit-field, edit-line-items

An action with requiresCapability is checked against the organization's plan for each order. A missing capability fails that order's step; it never returns a 403. Actions with destructive: true should be confirmed by the user before a run.

Boolean defaults: includeSlip on reprint-documents is true; acknowledgeWarnings on release and overwrite on assign-default-location are false.

maxCents on rate-and-assign is a price ceiling in minor units of your billing currency (for example 1500 = 15.00). Quotes are compared after conversion to that currency.

On bulk-edit-field, an empty string clears a field that can be cleared, the same as null.

edit-line-items is refused for an order that is fulfilled, has a purchased label, or holds reserved, allocated, picked, or committed inventory. The routing actions rate-and-assign, assign-service, and override-carrier are refused for a cancelled order or one with a purchased label.

Invalid action params on preflight and run return 400 with the error code INVALID_ACTION_PARAMS and a details array of { index, type, message }.

Preflight​

POST /api/v1/operations/preflight takes the same body as run and changes nothing. It checks the steps in pipeline order, so a fulfillment location set by an earlier assign-location, assign-default-location, or bulk-edit-field on fulfillment_location_id counts for a later release or routing step.

Run results​

results holds one entry per targeted order, each with an ordered steps array. Steps run in order and stop at the first failure for that order. Each step's changes are saved before the next step runs, so later steps see them.

Step fieldTypeDescription
typestringThe action type
okbooleanWhether the step succeeded
skippedbooleanSet on a retry for a step the original run already applied; it is not run again
errorstringFailure reason, present when ok is false
outputobjectHandler output, for example the document URL from reprint-documents
warningsarrayNon-fatal problems on a step that still succeeded. Each entry is { level: "warning", message, timestamp }
{
"type": "cancel-orders",
"ok": true,
"warnings": [
{ "level": "warning", "message": "Reservation release failed", "timestamp": "2026-11-08T12:00:00.000Z" }
]
}

Retries​

POST /api/v1/operations/runs/{id}/retry creates a linked run for the failed orders only. Each order resumes at its first failed step; the steps before it appear with "ok": true, "skipped": true. The retry run records the full actions list.

List the operations terminal action catalog​

GET/api/v1/operations/actions

Returns the 24 actions an operation pipeline can apply, grouped by category. Each entry describes its parameters so a client can render the controls.

Responses​

200 Action catalog

OperationActionDef[] object:

FieldTypeDescription
typeassign-location | assign-default-location | override-dispatcher | rate-and-assign | assign-service | override-carrier | clear-service | release | unrelease | mark-fulfilled | mark-shipped | cancel-orders | void-label | reprint-documents | allocate | pick | apply-tag | remove-tag | clear-tags | add-note | set-priority | set-ship-date | bulk-edit-field | edit-line-items
labelstring
descriptionstring
categoryrouting | fulfillment | labels | inventory | data
destructivebooleanRequires an explicit confirmation before running
requiresCapabilitycarrier_service_assignment | label_voiding | packing_slip_generationPlan capability checked per order. A missing capability fails that order step and is never a 403.
paramsOperationActionParam[]
{
"data": [
{
"type": "assign-location",
"label": "string",
"description": "string",
"category": "routing",
"destructive": true,
"requiresCapability": "carrier_service_assignment",
"params": [
{
"name": "includeSlip",
"label": "Include packing slip",
"type": "text",
"required": true,
"options": [
{
"value": "string",
"label": "string"
}
],
"placeholder": "string",
"help": "string",
"min": 0,
"max": 0,
"step": 0,
"dependsOn": "string",
"default": true
}
]
}
]
}
GET/api/v1/operations/actions

List the operations terminal action catalog

https://api-test.orderly-hub.com/api/v1/operations/actions

Preflight an action pipeline against orders​

POST/api/v1/operations/preflight

Reports, without changing anything, which orders each step would be blocked on and why. Steps are checked in pipeline order, so a fulfillment location set by an earlier assign-location, assign-default-location, or bulk edit of fulfillment_location_id counts for later steps.

Request body​

FieldTypeDescription
order_idsarray
actionsarray
{
"order_ids": [
"string"
],
"actions": [
{
"type": "string",
"params": {}
}
]
}

Responses​

200 Preflight report

400 One or more actions have invalid params. The error code is INVALID_ACTION_PARAMS and details lists each failure.

Response fields:

FieldTypeDescription
errorINVALID_ACTION_PARAMS
messagestring
detailsarray
{
"error": "INVALID_ACTION_PARAMS",
"message": "string",
"details": [
{
"index": 0,
"type": "string",
"message": "string"
}
]
}
POST/api/v1/operations/preflight

Preflight an action pipeline against orders

https://api-test.orderly-hub.com/api/v1/operations/preflight

Run an action pipeline against orders and log the run​

POST/api/v1/operations/run

Each order runs the steps in order. A step's changes are saved before the next step runs, so later steps see them. An order stops at its first failed step.

Request body​

FieldTypeDescription
order_idsarray
actionsarray
{
"order_ids": [
"string"
],
"actions": [
{
"type": "string",
"params": {}
}
]
}

Responses​

201 Run executed. Failures are reported per order and step in results.

OperationRun object:

FieldTypeDescription
idstring
organizationIdstring
actionsarray
orderIdsarray
resultsOperationRunOrderResult[]
totalinteger
succeededinteger
failedinteger
statuscompleted | partial | failed
retryOfRunIdstring
createdBystring
createdAtstring
completedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "550e8400-e29b-41d4-a716-446655440000",
"actions": [
{
"type": "string",
"params": {}
}
],
"orderIds": [
"string"
],
"results": [
{
"orderId": "550e8400-e29b-41d4-a716-446655440000",
"orderNumber": "string",
"ok": true,
"steps": [
{
"type": "string",
"ok": true,
"skipped": true,
"error": "string",
"output": {},
"warnings": [
{
"level": "warning",
"message": "string",
"timestamp": "string"
}
]
}
]
}
],
"total": 0,
"succeeded": 0,
"failed": 0,
"status": "completed",
"retryOfRunId": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "string",
"createdAt": "2026-07-23T12:00:00Z",
"completedAt": "2026-07-23T12:00:00Z"
}
}

400 One or more actions have invalid params. The error code is INVALID_ACTION_PARAMS and details lists each failure.

Response fields:

FieldTypeDescription
errorINVALID_ACTION_PARAMS
messagestring
detailsarray
{
"error": "INVALID_ACTION_PARAMS",
"message": "string",
"details": [
{
"index": 0,
"type": "string",
"message": "string"
}
]
}
POST/api/v1/operations/run

Run an action pipeline against orders and log the run

https://api-test.orderly-hub.com/api/v1/operations/run

List operation runs (history)​

GET/api/v1/operations/runs

Parameters​

NameInRequiredTypeDescription
pagequerynointeger
limitquerynointeger

Responses​

200 Paginated run list

GET/api/v1/operations/runs

List operation runs (history)

https://api-test.orderly-hub.com/api/v1/operations/runs

Get an operation run​

GET/api/v1/operations/runs/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Run detail

404 Run not found

GET/api/v1/operations/runs/{id}

Get an operation run

https://api-test.orderly-hub.com/api/v1/operations/runs/

Re-run only the failed orders of a run​

POST/api/v1/operations/runs/{id}/retry

Creates a linked run for the failed orders. Each order resumes at its first failed step; earlier steps are recorded with skipped true and are not run again. The new run records the full action list.

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

201 Retry run executed

400 No failed orders to retry

404 Run not found

POST/api/v1/operations/runs/{id}/retry

Re-run only the failed orders of a run

https://api-test.orderly-hub.com/api/v1/operations/runs//retry