Operations

Operations are the command center for bulk order management. Create an operation workspace, add orders, assign rates, override carriers or dispatch bridges, then execute everything in one batch. Every change is tracked in a full undo-able history.

Operations follow a lifecycle: draft -> pending -> executing -> completed (or failed, cancelled, paused).

Operation Types

List Operation Types

GET/api/v1/operations/types

List all available operation types.

Requiredoperations:read

Returns the registry of active operation types that can be applied to items within an operation.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/types" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "assign-rate",
      "name": "Assign Rate",
      "description": "Assign a quoted shipping rate to selected items",
      "icon": "tag",
      "category": "shipping",
      "configSchema": {},
      "supportsBulk": true,
      "supportsUndo": true,
      "maxBatchSize": 500,
      "requiresConfirmation": false,
      "requiredPermissions": ["operations:write"],
      "isActive": true,
      "isSystem": true,
      "sortOrder": 1,
      "createdAt": "2026-01-10T00:00:00Z",
      "updatedAt": "2026-01-10T00:00:00Z"
    }
  ]
}

Get Operation Type

GET/api/v1/operations/types/:id

Retrieve a single operation type by ID.

Requiredoperations:read

Returns the details of one operation type. Only returns active types.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/types/assign-rate" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "assign-rate",
    "name": "Assign Rate",
    "description": "Assign a quoted shipping rate to selected items",
    "icon": "tag",
    "category": "shipping",
    "configSchema": {},
    "supportsBulk": true,
    "supportsUndo": true,
    "maxBatchSize": 500,
    "requiresConfirmation": false,
    "requiredPermissions": ["operations:write"],
    "isActive": true,
    "isSystem": true,
    "sortOrder": 1,
    "createdAt": "2026-01-10T00:00:00Z",
    "updatedAt": "2026-01-10T00:00:00Z"
  }
}

Operations CRUD

List Operations

GET/api/v1/operations

List all operations with filtering and pagination.

Requiredoperations:read

Returns a paginated list of operations for the current organization, sorted by most recently updated.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `draft`, `pending`, `executing`, `paused`, `completed`, `cancelled`, `failed`


curl -X GET "https://api.orderly-hub.com/api/v1/operations?status=draft&limit=50" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org-uuid",
      "name": "Friday Batch Ship",
      "description": "All pending orders for Friday dispatch",
      "status": "draft",
      "itemCount": 142,
      "pendingCount": 142,
      "processingCount": 0,
      "completedCount": 0,
      "failedCount": 0,
      "skippedCount": 0,
      "totalEstimatedCost": 1284.50,
      "currency": "USD",
      "createdBy": "user-uuid",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "totalPages": 1,
    "hasMore": false
  }
}

Create Operation

POST/api/v1/operations

Create a new operation workspace in draft status.

Requiredoperations:write

Creates a new operation in draft status. Add orders to it using the items endpoints, configure actions, then execute.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Operation name (1-255 characters)
`description`	string	No	Description (max 1000 characters)


curl -X POST "https://api.orderly-hub.com/api/v1/operations" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Friday Batch Ship",
    "description": "All pending orders for Friday dispatch"
  }'

Response (201)


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org-uuid",
    "name": "Friday Batch Ship",
    "description": "All pending orders for Friday dispatch",
    "status": "draft",
    "itemCount": 0,
    "pendingCount": 0,
    "processingCount": 0,
    "completedCount": 0,
    "failedCount": 0,
    "skippedCount": 0,
    "currency": "USD",
    "createdBy": "user-uuid",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
}

Update Operation

PATCH/api/v1/operations/:id

Update an operation's name, description, or status.

Requiredoperations:write

Updates an operation. Cannot update operations in executing or completed status (except to set status to cancelled).

Request Body

Field	Type	Required	Description
`name`	string	No	New name (1-255 characters)
`description`	string	No	New description (max 1000 characters)
`status`	string	No	New status: `draft`, `pending`, `executing`, `paused`, `completed`, `cancelled`, `failed`


curl -X PATCH "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Friday Batch Ship - Updated",
    "status": "cancelled"
  }'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Friday Batch Ship - Updated",
    "status": "cancelled",
    "...": "..."
  }
}

Delete Operation

DELETE/api/v1/operations/:id

Delete a draft operation.

Requiredoperations:write

Permanently deletes an operation. Only operations in draft status can be deleted. Returns 409 if the operation is in any other status.


curl -X DELETE "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Get Operation

GET/api/v1/operations/:id

Retrieve a single operation by ID.

Requiredoperations:read

Returns the full operation object including all counts and timestamps.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org-uuid",
    "name": "Friday Batch Ship",
    "description": "All pending orders for Friday dispatch",
    "status": "completed",
    "itemCount": 142,
    "pendingCount": 0,
    "processingCount": 0,
    "completedCount": 140,
    "failedCount": 2,
    "skippedCount": 0,
    "totalEstimatedCost": 1284.50,
    "currency": "USD",
    "createdBy": "user-uuid",
    "startedAt": "2026-01-15T14:00:00Z",
    "completedAt": "2026-01-15T14:02:30Z",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T14:02:30Z"
  }
}

Operation Items

List Operation Items

GET/api/v1/operations/:id/items

List items in an operation with expanded order and rate data.

Requiredoperations:read

Returns a paginated list of items in the operation. Each item includes the linked order, assigned rate snapshot, override carrier account, and override dispatch bridge.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50, max: 100)
`status`	string	Filter by item status: `pending`, `processing`, `completed`, `failed`, `skipped`
`hasRate`	string	Filter by rate assignment: `true` or `false`


curl -X GET "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/items?status=pending&hasRate=false&limit=100" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "item-uuid",
      "organizationId": "org-uuid",
      "operationId": "550e8400-e29b-41d4-a716-446655440000",
      "orderId": "order-uuid",
      "status": "pending",
      "rateSnapshotId": null,
      "overrideCarrierAccountId": null,
      "overrideDispatchBridgeId": null,
      "pendingActions": [],
      "appliedActions": [],
      "retryCount": 0,
      "createdAt": "2026-01-15T10:35:00Z",
      "updatedAt": "2026-01-15T10:35:00Z",
      "order": {
        "id": "order-uuid",
        "externalId": "ext_123",
        "orderNumber": "1001",
        "customerEmail": "jane@example.com",
        "customerName": "Jane Doe",
        "totalPrice": 49.99,
        "currency": "USD",
        "status": "pending"
      },
      "rateSnapshot": null,
      "overrideCarrierAccount": null,
      "overrideDispatchBridge": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 142,
    "totalPages": 2,
    "hasMore": true
  }
}

Add Orders to Operation

POST/api/v1/operations/:id/items

Add orders to an operation.

Requiredoperations:write

Adds one or more orders to a draft operation. Duplicate order IDs are silently ignored. Returns 409 if the operation is not in draft status.

Request Body

Field	Type	Required	Description
`orderIds`	string[]	Yes	Array of order UUIDs to add (1-500 items)


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/items" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderIds": [
      "660e8400-e29b-41d4-a716-446655440000",
      "770e8400-e29b-41d4-a716-446655440000",
      "880e8400-e29b-41d4-a716-446655440000"
    ]
  }'

Response (201)


{
  "data": {
    "added": 3,
    "items": [
      {
        "id": "item-uuid-1",
        "operationId": "550e8400-e29b-41d4-a716-446655440000",
        "orderId": "660e8400-e29b-41d4-a716-446655440000",
        "status": "pending",
        "...": "..."
      }
    ]
  }
}

Update Operation Item

PATCH/api/v1/operations/:id/items/:itemId

Update a single operation item.

Requiredoperations:write

Updates an individual item within a draft operation. Use this to assign a rate, override the carrier account or dispatch bridge, or change the item status.

Request Body

Field	Type	Required	Description
`rateSnapshotId`	string \| null	No	Rate snapshot UUID to assign (or `null` to clear)
`overrideCarrierAccountId`	string \| null	No	Carrier account UUID to override (or `null` to clear)
`overrideDispatchBridgeId`	string \| null	No	Dispatch bridge UUID to override (or `null` to clear)
`status`	string	No	Item status: `pending`, `processing`, `completed`, `failed`, `skipped`


curl -X PATCH "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/items/item-uuid" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rateSnapshotId": "rate-snapshot-uuid",
    "overrideCarrierAccountId": "carrier-account-uuid"
  }'

Response


{
  "data": {
    "id": "item-uuid",
    "operationId": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "order-uuid",
    "status": "pending",
    "rateSnapshotId": "rate-snapshot-uuid",
    "overrideCarrierAccountId": "carrier-account-uuid",
    "overrideDispatchBridgeId": null,
    "pendingActions": [],
    "appliedActions": [],
    "retryCount": 0,
    "createdAt": "2026-01-15T10:35:00Z",
    "updatedAt": "2026-01-15T11:00:00Z"
  }
}

Remove Operation Item

DELETE/api/v1/operations/:id/items/:itemId

Remove a single item from a draft operation.

Requiredoperations:write

Removes an item from a draft operation. Returns 409 if the operation is not in draft status.


curl -X DELETE "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/items/item-uuid" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Bulk Remove Items

POST/api/v1/operations/:id/items/bulk-remove

Remove multiple items from a draft operation in one request.

Requiredoperations:write

Removes multiple items from a draft operation by their item IDs. Returns 409 if the operation is not in draft status.

Request Body

Field	Type	Required	Description
`itemIds`	string[]	Yes	Array of operation item UUIDs to remove (1-500 items)


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/items/bulk-remove" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": [
      "item-uuid-1",
      "item-uuid-2",
      "item-uuid-3"
    ]
  }'

Response


{
  "success": true,
  "removed": 3
}

Actions

Apply Action to Items

POST/api/v1/operations/:id/actions/apply

Apply an action (assign rate, override carrier, override dispatcher) to selected items.

Requiredoperations:write

Applies a bulk action to one or more items within a draft operation. The action type must correspond to a registered operation type. Supported built-in action types:

assign-rate — Assign a rate snapshot to selected items. Requires config.rateSnapshotId.
override-carrier — Override the carrier account for selected items. Requires config.carrierAccountId.
override-dispatcher — Override the dispatch bridge for selected items. Requires config.bridgeId.

Request Body

Field	Type	Required	Description
`itemIds`	string[]	Yes	Array of operation item UUIDs (1-500 items)
`action`	object	Yes	The action to apply
`action.type`	string	Yes	Action type (e.g., `assign-rate`, `override-carrier`, `override-dispatcher`)
`action.config`	object	Yes	Action configuration (varies by type)

Action Config by Type

assign-rate

Config Field	Type	Description
`rateSnapshotId`	string	UUID of the rate snapshot to assign

override-carrier

Config Field	Type	Description
`carrierAccountId`	string	UUID of the carrier account

override-dispatcher

Config Field	Type	Description
`bridgeId`	string	UUID of the dispatch bridge


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/actions/apply" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["item-uuid-1", "item-uuid-2"],
    "action": {
      "type": "override-carrier",
      "config": {
        "carrierAccountId": "carrier-account-uuid"
      }
    }
  }'

Response


{
  "success": true,
  "applied": 2,
  "action": {
    "type": "override-carrier",
    "config": {
      "carrierAccountId": "carrier-account-uuid"
    }
  }
}

History & Undo

Get Operation History

GET/api/v1/operations/:id/history

Get the action history for an operation.

Requiredoperations:read

Returns the last 50 history entries for an operation, sorted by most recent first. Each entry records what action was taken, which items were affected, and whether the action can be undone.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/history" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "history-uuid",
      "organizationId": "org-uuid",
      "operationId": "550e8400-e29b-41d4-a716-446655440000",
      "action": "action_applied",
      "affectedItemIds": ["item-uuid-1", "item-uuid-2"],
      "affectedOrderIds": ["order-uuid-1", "order-uuid-2"],
      "previousState": { "items": ["..."] },
      "newState": { "action": { "type": "override-carrier", "config": {} } },
      "isUndoable": true,
      "isUndone": false,
      "performedBy": "user-uuid",
      "performedAt": "2026-01-15T11:00:00Z"
    }
  ]
}

Undo History Action

POST/api/v1/operations/:id/undo/:historyId

Undo a specific history action.

Requiredoperations:write

Reverses a specific history entry by its ID. Only works on draft operations. The history entry must be undoable (isUndoable: true) and not already undone (isUndone: false).


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/undo/history-uuid" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Execution

Execute Operation

POST/api/v1/operations/:id/execute

Execute all pending items in the operation.

Requiredoperations:execute

Executes an operation. The operation must be in draft or pending status and must have at least one item. Operations with more than 50 items are automatically queued for async execution via QStash.

Use dryRun: true to preview the execution without actually running it. You can also pass actions to apply to all pending items right before execution starts.

Request Body

Field	Type	Required	Description
`dryRun`	boolean	No	If `true`, returns a preview without executing (default: `false`)
`actions`	array	No	Actions to apply to all pending items before execution
`actions[].type`	string	Yes	Action type
`actions[].config`	object	Yes	Action configuration


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/execute" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dryRun": false,
    "actions": [
      {
        "type": "override-carrier",
        "config": { "carrierAccountId": "carrier-uuid" }
      }
    ]
  }'

Dry Run Response


{
  "dryRun": true,
  "operation": { "id": "...", "name": "...", "status": "draft", "..." : "..." },
  "preview": {
    "totalItems": 142,
    "pendingItems": 142,
    "estimatedCost": 1284.50
  }
}

Sync Execution Response

For operations with 50 or fewer items (or when async queueing is unavailable):


{
  "success": true,
  "operationId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "itemCount": 12,
  "completedCount": 11,
  "failedCount": 1,
  "skippedCount": 0,
  "logs": ["..."]
}

Async Execution Response

For operations with more than 50 items:


{
  "success": true,
  "operationId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "executing",
  "itemCount": 142,
  "async": true,
  "message": "Operation queued for async execution"
}

Get Execution Progress

GET/api/v1/operations/:id/progress

Get real-time execution progress for an operation.

Requiredoperations:read

Returns the current execution progress including counts for each item status. Poll this endpoint to track async execution.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/progress" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "operationId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "executing",
    "itemCount": 142,
    "pendingCount": 38,
    "processingCount": 2,
    "completedCount": 100,
    "failedCount": 2,
    "skippedCount": 0,
    "startedAt": "2026-01-15T14:00:00Z",
    "completedAt": null
  }
}

Rate Shopping

Rate Shop for Operation

POST/api/v1/operations/:id/rate-shop

Batch-quote carrier rates for all items in the operation.

Requiredoperations:write

Fetches shipping rates for all items in a draft operation. Optionally auto-assigns the best rate based on the selected strategy. Only works on draft operations.

Request Body

Field	Type	Required	Description
`strategy`	string	No	Rate selection strategy: `cheapest`, `fastest`, or `best-value` (default: `cheapest`)
`autoAssign`	boolean	No	If `true`, automatically assign the best rate to each item (default: `false`)
`carrierAccountIds`	string[]	No	Limit rate quotes to specific carrier account UUIDs


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/rate-shop" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "cheapest",
    "autoAssign": true,
    "carrierAccountIds": [
      "carrier-account-uuid-1",
      "carrier-account-uuid-2"
    ]
  }'

Response


{
  "data": {
    "...": "Rate shopping results"
  }
}

AI Rules

Evaluate AI Rules

POST/api/v1/operations/evaluate-rules

Evaluate AI automation rules against a set of orders.

Requiredoperations:write

Runs the AI automation rule engine against a set of orders. Returns recommended actions for each order based on configured rules. Useful for previewing what the AI would do before creating an operation.

Request Body

Field	Type	Required	Description
`orderIds`	string[]	Yes	Array of order UUIDs to evaluate (1-1000 items)


curl -X POST "https://api.orderly-hub.com/api/v1/operations/evaluate-rules" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderIds": [
      "660e8400-e29b-41d4-a716-446655440000",
      "770e8400-e29b-41d4-a716-446655440000"
    ]
  }'

Response


{
  "data": {
    "...": "Rule evaluation results"
  }
}

Insights

Get Operation Insights

GET/api/v1/operations/:id/insights

Get AI-powered insights and recommendations for an operation.

Requiredoperations:read

Analyzes the operation and generates actionable insights. V1 uses rule-based detection (e.g., identifying items that could use a cheaper carrier, flagging outlier shipping costs, suggesting consolidation). Each insight includes a suggested action that can be applied via the apply endpoint.


curl -X GET "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/insights" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "...": "Insight results with suggested actions"
  }
}

Apply Insight

POST/api/v1/operations/:id/insights/:insightId/apply

Apply a suggested action from an insight to affected items.

Requiredoperations:write

Takes an insight’s suggested action and applies it to the specified items. The action is appended to each item’s pendingActions array for execution. Only works on draft operations.

Request Body

Field	Type	Required	Description
`itemIds`	string[]	Yes	Array of operation item UUIDs to apply the insight to
`action`	object	Yes	The action to apply
`action.type`	string	Yes	Action type
`action.config`	object	No	Action configuration


curl -X POST "https://api.orderly-hub.com/api/v1/operations/550e8400-e29b-41d4-a716-446655440000/insights/insight-uuid/apply" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "itemIds": ["item-uuid-1", "item-uuid-2"],
    "action": {
      "type": "override-carrier",
      "config": {
        "carrierAccountId": "cheaper-carrier-uuid"
      }
    }
  }'

Response


{
  "success": true,
  "appliedCount": 2,
  "action": {
    "type": "override-carrier",
    "config": {
      "carrierAccountId": "cheaper-carrier-uuid"
    }
  }
}