Split Rules

Split rules define how orders are automatically divided into multiple sub-orders based on line item attributes, such as warehouse location, fulfillment type, or product category. Rules use either condition-based matching or field grouping to determine how line items are distributed across child orders.

List Split Rules

GET/api/v1/split-rules

List all split rules for the organization.

Requiredorders:read

Returns a paginated list of split rules 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)
`isActive`	string	Filter by active status: `true` or `false`
`bridgeId`	string	Filter by associated bridge ID


curl -X GET "https://api.orderly-hub.com/api/v1/split-rules?isActive=true" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organizationId": "uuid",
      "name": "Split by warehouse",
      "description": "Routes items to warehouse-specific child orders",
      "method": "field_group",
      "conditionGroups": [],
      "groupField": "line_items.warehouse_code",
      "bridgeId": "uuid",
      "isActive": true,
      "priority": 10,
      "ordersSplit": 142,
      "lastSplitAt": "2026-03-15T14:30:00Z",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-15T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1, "hasMore": false }
}

Get Split Rule

GET/api/v1/split-rules/:id

Get a single split rule by ID.

Requiredorders:read

Returns the full details of a specific split rule including its condition groups or grouping field configuration.

Path Parameters

Parameter	Type	Description
`id`	string	Split rule UUID


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

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "uuid",
    "name": "Split by warehouse",
    "description": "Routes items to warehouse-specific child orders",
    "method": "field_group",
    "conditionGroups": [],
    "groupField": "line_items.warehouse_code",
    "bridgeId": "uuid",
    "isActive": true,
    "priority": 10,
    "ordersSplit": 142,
    "lastSplitAt": "2026-03-15T14:30:00Z",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-03-15T14:30:00Z"
  }
}

Create Split Rule

POST/api/v1/split-rules

Create a new order split rule.

Requiredorders:write

Creates a new split rule. Rules are evaluated in priority order (higher priority runs first). Use method: "condition" for condition-based splitting or method: "field_group" to group line items by a shared field value.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`description`	string	No	Description of the rule
`method`	string	Yes	Split method: `condition` or `field_group`
`conditionGroups`	object[]	No	Condition groups (required for `condition` method)
`groupField`	string	No	Dot-notation field path (required for `field_group` method)
`bridgeId`	string	No	Limit to orders from a specific bridge
`isActive`	boolean	No	Whether the rule is active (default: `true`)
`priority`	number	No	Execution priority (higher runs first, default: 0)


curl -X POST "https://api.orderly-hub.com/api/v1/split-rules" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Split by warehouse",
    "method": "field_group",
    "groupField": "line_items.warehouse_code",
    "priority": 10,
    "isActive": true
  }'

Update Split Rule

PATCH/api/v1/split-rules/:id

Update a split rule's configuration.

Requiredorders:write

Updates a split rule. Changes take effect for new orders processed after the update.


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

Delete Split Rule

DELETE/api/v1/split-rules/:id

Delete a split rule.

Requiredorders:write

Permanently deletes a split rule. Orders that were previously split by this rule are not affected.


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

Response


{
  "success": true
}

Test Split Rule

POST/api/v1/split-rules/:id/test

Dry-run a split rule against an existing order to preview the result.

Requiredorders:read

Tests a saved split rule against a real order without actually creating child orders. Returns a preview of how the order’s line items would be grouped if the rule were applied.

Path Parameters

Parameter	Type	Description
`id`	string	Split rule UUID

Request Body

Field	Type	Required	Description
`orderId`	string	Yes	The order UUID to test the rule against


curl -X POST "https://api.orderly-hub.com/api/v1/split-rules/550e8400-e29b-41d4-a716-446655440000/test" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "660e8400-e29b-41d4-a716-446655440000"
  }'

Response


{
  "data": {
    "wouldSplit": true,
    "reason": "Would split into 3 groups",
    "groups": [
      {
        "label": "WH-EAST",
        "itemCount": 2,
        "items": [
          { "sku": "WIDGET-A", "warehouse_code": "WH-EAST" },
          { "sku": "WIDGET-B", "warehouse_code": "WH-EAST" }
        ]
      },
      {
        "label": "WH-WEST",
        "itemCount": 1,
        "items": [
          { "sku": "GADGET-C", "warehouse_code": "WH-WEST" }
        ]
      }
    ]
  }
}

No-Split Response

When all items fall into a single group:


{
  "data": {
    "wouldSplit": false,
    "reason": "All items in one group, no split needed",
    "groups": []
  }
}