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.
| Category | Actions |
|---|---|
routing | assign-location, assign-default-location, override-dispatcher, rate-and-assign, assign-service, override-carrier, clear-service |
fulfillment | release, unrelease, mark-fulfilled, mark-shipped, cancel-orders |
labels | void-label, reprint-documents |
inventory | allocate, pick |
data | apply-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 field | Type | Description |
|---|---|---|
type | string | The action type |
ok | boolean | Whether the step succeeded |
skipped | boolean | Set on a retry for a step the original run already applied; it is not run again |
error | string | Failure reason, present when ok is false |
output | object | Handler output, for example the document URL from reprint-documents |
warnings | array | Non-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
/api/v1/operations/actionsReturns 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:
| Field | Type | Description |
|---|---|---|
type | assign-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 | |
label | string | |
description | string | |
category | routing | fulfillment | labels | inventory | data | |
destructive | boolean | Requires an explicit confirmation before running |
requiresCapability | carrier_service_assignment | label_voiding | packing_slip_generation | Plan capability checked per order. A missing capability fails that order step and is never a 403. |
params | OperationActionParam[] |
{
"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
}
]
}
]
}
/api/v1/operations/actionsList the operations terminal action catalog
https://api-test.orderly-hub.com/api/v1/operations/actionsPreflight an action pipeline against orders
/api/v1/operations/preflightReports, 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
| Field | Type | Description |
|---|---|---|
order_ids | array | |
actions | array |
{
"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:
| Field | Type | Description |
|---|---|---|
error | INVALID_ACTION_PARAMS | |
message | string | |
details | array |
{
"error": "INVALID_ACTION_PARAMS",
"message": "string",
"details": [
{
"index": 0,
"type": "string",
"message": "string"
}
]
}
/api/v1/operations/preflightPreflight an action pipeline against orders
https://api-test.orderly-hub.com/api/v1/operations/preflightRun an action pipeline against orders and log the run
/api/v1/operations/runEach 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
| Field | Type | Description |
|---|---|---|
order_ids | array | |
actions | array |
{
"order_ids": [
"string"
],
"actions": [
{
"type": "string",
"params": {}
}
]
}
Responses
201 Run executed. Failures are reported per order and step in results.
OperationRun object:
| Field | Type | Description |
|---|---|---|
id | string | |
organizationId | string | |
actions | array | |
orderIds | array | |
results | OperationRunOrderResult[] | |
total | integer | |
succeeded | integer | |
failed | integer | |
status | completed | partial | failed | |
retryOfRunId | string | |
createdBy | string | |
createdAt | string | |
completedAt | string |
{
"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:
| Field | Type | Description |
|---|---|---|
error | INVALID_ACTION_PARAMS | |
message | string | |
details | array |
{
"error": "INVALID_ACTION_PARAMS",
"message": "string",
"details": [
{
"index": 0,
"type": "string",
"message": "string"
}
]
}
/api/v1/operations/runRun an action pipeline against orders and log the run
https://api-test.orderly-hub.com/api/v1/operations/runList operation runs (history)
/api/v1/operations/runsParameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | no | integer | |
limit | query | no | integer |
Responses
200 Paginated run list
/api/v1/operations/runsList operation runs (history)
https://api-test.orderly-hub.com/api/v1/operations/runsGet an operation run
/api/v1/operations/runs/{id}Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Responses
200 Run detail
404 Run not found
/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
/api/v1/operations/runs/{id}/retryCreates 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
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Responses
201 Retry run executed
400 No failed orders to retry
404 Run not found
/api/v1/operations/runs/{id}/retryRe-run only the failed orders of a run
https://api-test.orderly-hub.com/api/v1/operations/runs//retry