Dispatchers

Dispatchers are automated routing rules that assign orders from source bridges to destination bridges based on conditions. They evaluate order data against conditions and create dispatch assignments. Tasks then pick up those assignments and handle the actual push to the destination.

Key concepts:

Source bridges — one or more bridges whose orders the dispatcher watches.
Destination bridge — the single bridge orders are assigned to.
Conditions — rules evaluated against order fields using operators like equals, contains, in_set, etc.
Match mode — all (every condition must pass) or any (at least one must pass).
Triggers — events that cause evaluation: order_created, order_updated, shipment_created, or manual.

List Dispatchers

GET/api/v1/dispatchers

List all dispatchers for the organization.

Requireddispatchers:read

Returns a paginated list of dispatchers ordered by priority (descending) then name.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`sourceBridgeId`	string (UUID)	Filter to dispatchers that include this source bridge
`destinationBridgeId`	string (UUID)	Filter by destination bridge
`isActive`	string	Filter by active status: `true` or `false`


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

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org-uuid",
      "name": "Route Shopify to ERP",
      "description": "Sends all domestic Shopify orders to the ERP bridge",
      "sourceBridgeIds": ["aaa-uuid", "bbb-uuid"],
      "destinationBridgeId": "ccc-uuid",
      "destinationConfig": {},
      "conditions": [
        { "field": "shipping_country", "operator": "equals", "value": "US" }
      ],
      "matchMode": "all",
      "triggerOn": ["order_created"],
      "isActive": true,
      "priority": 10,
      "ordersAssigned": 1284,
      "lastAssignedAt": "2026-04-07T18:30:00.000Z",
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-04-07T18:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Get Dispatcher

GET/api/v1/dispatchers/:id

Retrieve a single dispatcher by ID.

Requireddispatchers:read

Returns the full dispatcher object including source bridge IDs and conditions.


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

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org-uuid",
    "name": "Route Shopify to ERP",
    "description": "Sends all domestic Shopify orders to the ERP bridge",
    "sourceBridgeIds": ["aaa-uuid", "bbb-uuid"],
    "destinationBridgeId": "ccc-uuid",
    "destinationConfig": {},
    "conditions": [
      { "field": "shipping_country", "operator": "equals", "value": "US" }
    ],
    "matchMode": "all",
    "triggerOn": ["order_created"],
    "isActive": true,
    "priority": 10,
    "ordersAssigned": 1284,
    "lastAssignedAt": "2026-04-07T18:30:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-07T18:30:00.000Z"
  }
}

Create Dispatcher

POST/api/v1/dispatchers

Create a new dispatcher routing rule.

Requireddispatchers:write

Creates a new dispatcher. Source and destination bridges must belong to the organization and must be different from each other. Any in_set / not_in_set conditions must reference condition sets that exist in the organization.

Returns 409 if a dispatcher with the same name already exists.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name (1-100 chars)
`description`	string	No	Description (max 500 chars)
`sourceBridgeIds`	string[]	Yes	UUIDs of source bridges (min 1)
`destinationBridgeId`	string	Yes	UUID of the destination bridge
`destinationConfig`	object	No	Extra config passed to the destination (default: `{}`)
`conditions`	Condition[]	Yes	Array of conditions (1-50). See below.
`matchMode`	string	No	`all` or `any` (default: `all`)
`triggerOn`	string[]	No	Trigger events (default: `["order_created"]`). Values: `order_created`, `order_updated`, `shipment_created`, `manual`
`isActive`	boolean	No	Whether the dispatcher is active (default: `true`)
`priority`	number	No	Priority 0-1000, higher runs first (default: `0`)

Condition Object

A condition is either a simple condition or a set condition:

Simple condition:

Field	Type	Description
`field`	string	Order field path to evaluate (1-200 chars)
`operator`	string	One of: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `in`, `not_in`, `exists`, `not_exists`, `regex`
`value`	mixed	Comparison value: string, number, boolean, string[], or number[]

Set condition (for large value lists like zip codes):

Field	Type	Description
`field`	string	Order field path to evaluate
`operator`	string	`in_set` or `not_in_set`
`setId`	string	UUID of the condition set


curl -X POST "https://api.orderly-hub.com/api/v1/dispatchers" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Route domestic Shopify to ERP",
    "description": "Assigns US orders from Shopify to the NetSuite bridge",
    "sourceBridgeIds": ["aaa-uuid"],
    "destinationBridgeId": "bbb-uuid",
    "conditions": [
      { "field": "shipping_country", "operator": "equals", "value": "US" },
      { "field": "shipping_zip", "operator": "in_set", "setId": "zipcode-set-uuid" }
    ],
    "matchMode": "all",
    "triggerOn": ["order_created", "order_updated"],
    "isActive": true,
    "priority": 10
  }'

Response (201)


{
  "data": {
    "id": "new-dispatcher-uuid",
    "organizationId": "org-uuid",
    "name": "Route domestic Shopify to ERP",
    "description": "Assigns US orders from Shopify to the NetSuite bridge",
    "sourceBridgeIds": ["aaa-uuid"],
    "destinationBridgeId": "bbb-uuid",
    "destinationConfig": {},
    "conditions": [
      { "field": "shipping_country", "operator": "equals", "value": "US" },
      { "field": "shipping_zip", "operator": "in_set", "setId": "zipcode-set-uuid" }
    ],
    "matchMode": "all",
    "triggerOn": ["order_created", "order_updated"],
    "isActive": true,
    "priority": 10,
    "ordersAssigned": 0,
    "createdAt": "2026-04-08T12:00:00.000Z",
    "updatedAt": "2026-04-08T12:00:00.000Z"
  }
}

Update Dispatcher

PATCH/api/v1/dispatchers/:id

Update a dispatcher's configuration.

Requireddispatchers:write

Partially updates a dispatcher. Only include the fields you want to change. If sourceBridgeIds is provided, the entire set of sources is replaced. Condition set references are validated when conditions is updated.

Request Body

All fields are optional:

Field	Type	Description
`name`	string	Display name (1-100 chars)
`description`	string	Description (max 500 chars)
`sourceBridgeIds`	string[]	Replaces all source bridges
`conditions`	Condition[]	Replaces all conditions (1-50)
`matchMode`	string	`all` or `any`
`triggerOn`	string[]	Trigger events
`isActive`	boolean	Enable or disable the dispatcher
`priority`	number	Priority 0-1000
`destinationConfig`	object	Extra config for the destination


curl -X PATCH "https://api.orderly-hub.com/api/v1/dispatchers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false,
    "priority": 50
  }'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org-uuid",
    "name": "Route domestic Shopify to ERP",
    "sourceBridgeIds": ["aaa-uuid"],
    "destinationBridgeId": "bbb-uuid",
    "destinationConfig": {},
    "conditions": [
      { "field": "shipping_country", "operator": "equals", "value": "US" }
    ],
    "matchMode": "all",
    "triggerOn": ["order_created"],
    "isActive": false,
    "priority": 50,
    "ordersAssigned": 1284,
    "lastAssignedAt": "2026-04-07T18:30:00.000Z",
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-04-08T14:00:00.000Z"
  }
}

Delete Dispatcher

DELETE/api/v1/dispatchers/:id

Delete a dispatcher.

Requireddispatchers:write

Permanently deletes a dispatcher. Returns 409 if the dispatcher has pending or processing assignments — complete or cancel them first.


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

Response


{
  "success": true
}

Get Dispatch Assignments

GET/api/v1/dispatchers/:id/assignments

List dispatch assignments for a specific dispatcher.

Requireddispatchers:read

Returns a paginated list of assignments created by this dispatcher, ordered by most recent first.

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: `pending`, `processing`, `completed`, `failed`, `skipped`


curl -X GET "https://api.orderly-hub.com/api/v1/dispatchers/550e8400-e29b-41d4-a716-446655440000/assignments?status=failed&limit=10" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "assignment-uuid",
      "organizationId": "org-uuid",
      "dispatcherId": "550e8400-e29b-41d4-a716-446655440000",
      "orderId": "order-uuid",
      "destinationBridgeId": "dest-bridge-uuid",
      "status": "failed",
      "taskExecutionId": "task-exec-uuid",
      "processedAt": "2026-04-07T18:32:00.000Z",
      "errorMessage": "Destination bridge returned 503",
      "retryCount": 3,
      "metadata": { "trigger": "order_created" },
      "assignedAt": "2026-04-07T18:30:00.000Z",
      "createdAt": "2026-04-07T18:30:00.000Z",
      "updatedAt": "2026-04-07T18:32:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasMore": false
  }
}

Evaluate Dispatchers for an Order

POST/api/v1/dispatchers/evaluate/:orderId

Manually evaluate all active dispatchers against a specific order.

Requireddispatchers:write

Runs all active dispatchers against the given order and creates assignments for any that match. Useful for testing dispatchers or re-evaluating an order that was missed.

The evaluation trigger is recorded as manual.


curl -X POST "https://api.orderly-hub.com/api/v1/dispatchers/evaluate/order-uuid" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "orderId": "order-uuid",
    "assignmentsCreated": 2,
    "assignments": [
      {
        "id": "assignment-uuid-1",
        "organizationId": "org-uuid",
        "dispatcherId": "dispatcher-1-uuid",
        "orderId": "order-uuid",
        "destinationBridgeId": "dest-bridge-uuid-a",
        "status": "pending",
        "retryCount": 0,
        "metadata": { "trigger": "manual" },
        "assignedAt": "2026-04-08T14:00:00.000Z",
        "createdAt": "2026-04-08T14:00:00.000Z",
        "updatedAt": "2026-04-08T14:00:00.000Z"
      }
    ]
  }
}

Process Pending Assignments

POST/api/v1/dispatchers/assignments/process

Process pending dispatch assignments via QStash.

Requireddispatchers:write

Fans out pending assignments to destination bridges for processing via QStash. Optionally filter by bridge or limit the batch size. The body is optional — omit it to process all pending assignments.

Request Body (optional)

Field	Type	Description
`bridgeId`	string	Only process assignments for this destination bridge
`limit`	number	Maximum number of assignments to process


curl -X POST "https://api.orderly-hub.com/api/v1/dispatchers/assignments/process" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bridgeId": "dest-bridge-uuid",
    "limit": 50
  }'

Response


{
  "data": {
    "processed": 50,
    "queued": 50,
    "errors": 0
  }
}

Retry Failed Assignments

POST/api/v1/dispatchers/assignments/retry

Reset failed assignments back to pending so they can be reprocessed.

Requireddispatchers:write

Resets failed assignments to pending status with retryCount set to 0 so they get picked up again by the next process cycle. Optionally target specific assignment IDs, or omit to retry all failed assignments in the organization.

Request Body

Field	Type	Required	Description
`assignmentIds`	string[]	No	Specific assignment IDs to retry. If omitted, retries all failed assignments.


curl -X POST "https://api.orderly-hub.com/api/v1/dispatchers/assignments/retry" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "assignmentIds": ["assignment-uuid-1", "assignment-uuid-2"]
  }'

Response


{
  "data": {
    "reset": 2
  }
}

Bulk Assign Orders

POST/api/v1/dispatchers/:id/assign

Manually assign orders to a dispatcher, bypassing condition evaluation.

Requireddispatchers:write

Directly assigns a batch of orders to a dispatcher’s destination bridge without evaluating conditions. Orders already assigned to the same destination bridge are silently skipped. Maximum 200 orders per request.

Request Body

Field	Type	Required	Description
`orderIds`	string[]	Yes	Array of order UUIDs to assign (1-200)


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

Response


{
  "data": {
    "assigned": 2,
    "skipped": 1
  }
}

assigned is the number of new assignments created. skipped is the number of orders that were already assigned to the same destination bridge.