Skip to main content
Although the Order Routing UI is the easiest way to configure routing resources, some configurations and testing can be performed via API. The Order Routing APIs are grouped into four topics for supporting data lists, filters, groups, and routing. The schemas and request templates are available in the API documentation, but this guide provides a supplemental walkthrough to explain how to use these calls.

​
Data Lists

Custom data lists are used to create filters, allowing them to fine-tune which cases the filter should be applied for. For instance, if a particular location group cannot fulfill particular product UPCs then a custom data list could be created containing those UPCs. A filter could be applied to the group with that data list applied to the “Item UPC” attribute. This would result in the order being assigned to the group only if the UPC of the order item was not in the list. The supported Data List operations are:

​
How Data Lists Work

A data list must be one of three types: String, Number, or Location. This is the type of values that will populate the list, determined by the dataType parameter.  The individual name:value pairs that populate the list are configured in the entries array. This array always identifies the note (or name) and value of the entry. This value is always input as a string regardless of the list type. For example, a String data list may be set as the following when creating or editing a data list: 
"dataType": "STRING",
  "entries": [
        {
            "notes": "Glassware Department",
            "stringValue": "Glassware"
        },
        {
            "notes": "Picture Frame Department",
            "stringValue": "PictureFrame"
        },
        {
            "notes": "Fragile Wood Department",
            "stringValue": "Fragile Wood"
        }
  ]
A Number data list may be set as the following: 
"dataType": "NUMBER",
  "entries": [
        {
            "notes": "Austin Labor Rate",
            "stringValue": "1.75"
        },
        {
            "notes": "Dallas Labor Rate",
            "stringValue": "1.79"
        }
  ]
And a Location data list may be set as the following: 
"dataType": "LOCATION",
  "entries": [
        {
            "notes": "Location Code 1",
            "stringValue": "5201"
        },
        {
            "notes": "Location Code 2",
            "stringValue": "5202"
        },
        {
            "notes": "Location Code 3",
            "stringValue": "5203"
        }
  ]

​
Routing Filters

In Order Routing, filters are used to “filter out” fulfillers within a location group being routed to that do not match certain criteria. For example, a filter can be created so that orders can only be assigned or viewed if a fulfiller is located within 100 miles of the customer. Multiple filters can be applied to a group to further narrow the list of fulfillers. For example, two filters can be created so that the order can be only assigned or viewed if the fulfiller is located within 100 miles of the customer and the order total price is less than $1,000. With the Order Routing APIs, filters can be created based on custom data as well as managed by retrieving existing filter information and deleting a filter. The supported Filter operations are:

​
Location Groups

Although location groups may be created and managed by the dedicated Location Group API, the Order Routing application also contains API extensions for adjusting groups specifically in the context of calculating routing. The supported Group operations are: Locations can be added and removed via these operations, but the API is also used to set the sort options, filters, and failover/restart behaviors.

​
Routing Candidates and Suggestions

The Routing API operations include different methods of testing your routing configuration and gathering routing data: The Suggest Candidates operation is a resource used to filter fulfillment locations based on inventory and order routing rules. Rather than determine exactly where the shipment would be routed to if it were fulfilled immediately, the API returns a list of all eligible locations (candidates). The call works for all routing types and supports both partial and full cases in which locations have inventory. The Suggest Routing (or Routing Suggestion) operation is used o answer the question, “Where exactly would this order be assigned if I were to create it now?” The response is the best routing assignment scenario, depending on the current inventory and routing filters or rules that are in place. The API will attempt to only return a single location assignment per item, if it can, in order to provide the most efficient order routing suggestion. In both cases, the call does not assign the order to any location yet. Instead, it reports the selections that may be made by Order Routing if the order were actually being assigned. This makes the APIs useful for testing routing scenarios.

​
Comparison of Responses

The Candidates API will return a candidateSuggestions collection of locations and their location data that the shipment could potentially be routed to, based on inventory and routing rules. That decisioning logic is included in the response in addition to the location information. 
[
  {
    "tenantID": 00000,
    "siteID": 11111,
    "environmentID": 1,
    "created": 1618581253685,
    "updated": 1618581253685,
    "creatorUsername": null,
    "updaterUsername": null,
    "suggestionID": 1001001,
    "orderID": 10,
    "externalResponseID": null,
    "events": [
      {
        "type": "NEW_REQUEST",
        "name": null,
        "causeID": 97,
        "errors": null,
        "request": {
          "items": [
            {
              "orderItemID": 00000,
              "partNumber": null,
              "sku": null,
              "quantity": 2,
              "customItemData": null,
              "itemDependency": null,
              "backorderable": true,
              "upc": "exampleItem"
            }
          ],
          "orderType": "DIRECTSHIP",
          "environmentID": 1,
          "shippingAddress": {
            "addressID": 01110,
            "addressLine1": "10 Example St",
            "city": "Test City",
            "countryCode": "US",
            "customerID": 10001,
            "latitude": 011111111110,
            "longitude": 100000000001,
            "phone": "9720001111",
            "postalCode": "750011",
            "state": "TX"
          },
          "isExpress": true,
          "pickupLocationCode": null,
          "locationCodeWhiteList": [
            "location1",
            "location2",
            "location3"
          ],
          "exclusionListLocationCode": [
            "blacklistedLocation"
          ],
          "inventoryRequestType": "ANY",
          "externalResponseID": null,
          "orderID": 10,
          "total": 123,
          "fraud": null,
          "customData": null,
          "bundlingStrategy": "ITEM_DEPENDENCY",
          "numShipmentsNotInRequest": 0
        }
      },
      {
        "type": "ROUTE_SELECTED",
        "name": "route.ordertype.directship",
        "causeID": 227,
        "errors": null,
        "tenantID": 00000,
        "siteID": 11111,
        "environmentID": 1,
        "orderType": "DIRECTSHIP",
        "route": "route.ordertype.directship:227",
        "active": true,
        "groups": [
          "{groupID=100, name=Default, rank=1, isDefaultGroup=false, useRetailerExclusionList=true, afterActionPartial=GroupAfterAction(actionID=1453, name=null, failoverAction=QUANTITY_SPLIT_ASSIGN_IF_FULFILLED, restartAttempt=START_AT_BEGINNING), afterActionNone=GroupAfterAction(actionID=1452, name=null, failoverAction=LINE_ITEM_SPLIT_ASSIGN_IF_FULFILLED, restartAttempt=START_AT_BEGINNING), description=, active=true, fulfillmentLimit=null}"
        ]
      },
      {
        "type": "INVENTORY_REQUEST",
        "name": null,
        "causeID": null,
        "errors": [],
        "request": {
          "locationCode": null,
          "userID": null,
          "pageSize": null,
          "pageNum": null,
          "sortBy": null,
          "type": "ANY",
          "items": [
            {
              "partNumber": null,
              "upc": "exampleItem",
              "sku": "exampleItem",
              "quantity": 2
            }
          ],
          "requestLocation": {
            "unit": "MILES",
            "radius": null,
            "postalCode": "12345",
            "latitude": null,
            "longitude": null,
            "countryCode": "US",
            "locationCode": null
          },
          "limit": 1000,
          "locationWhitelist": [
            "location1",
            "location2",
            "location3"
          ],
          "locationPriorityList": null,
          "locationBlacklist": null,
          "ignoreSafetyStock": false,
          "includeNegativeInventory": null,
          "directShip": true,
          "transferEnabled": null,
          "pickup": null,
          "includeInAggregateExport": null,
          "includeInLocationExport": null,
          "excludeBlockedAssignment": true,
          "includeAttributes": false,
          "sortByEnum": null,
          "tags": null
        },
        "tenantID": 00000,
        "siteID": 11111,
        "environmentID": 1,
        "orderID": 10,
        "responseTimeMillis": 140,
        "response": [
          {
            "success": null,
            "messages": null,
            "numResults": null,
            "locationName": "Store One",
            "locationCode": "location1",
            "tenantID": 00000,
            "onHand": 33,
            "available": 28,
            "allocated": 5,
            "pending": 0,
            "partNumber": null,
            "upc": "exampleItem",
            "sku": "exampleItem",
            "blockAssignment": false,
            "ltd": 0,
            "floor": 0,
            "safetyStock": 0,
            "distance": 711.8406819306866,
            "directShip": true,
            "transferEnabled": true,
            "pickup": true,
            "countryCode": "US",
            "currencyID": null,
            "retailPrice": null,
            "inventoryLocatorName": null,
            "attributes": null,
            "taggedInventory": null
          },
          {
            "success": null,
            "messages": null,
            "numResults": null,
            "locationName": "Location Two",
            "locationCode": "location2",
            "tenantID": 00000,
            "onHand": 242,
            "available": 206,
            "allocated": 36,
            "pending": 0,
            "partNumber": null,
            "upc": "exampleItem",
            "sku": "exampleItem",
            "blockAssignment": false,
            "ltd": 0,
            "floor": 10,
            "safetyStock": 0,
            "distance": 1559.822496185389,
            "directShip": true,
            "transferEnabled": true,
            "pickup": true,
            "countryCode": "US",
            "currencyID": null,
            "retailPrice": null,
            "inventoryLocatorName": null,
            "attributes": null,
            "taggedInventory": null
          }
        ]
      },
      {
        "type": "GROUP",
        "name": "Default",
        "causeID": 676,
        "errors": null,
        "group": "{groupID=100, name=Default, rank=1, isDefaultGroup=false, useRetailerExclusionList=true, afterActionPartial=GroupAfterAction(actionID=1453, name=null, failoverAction=QUANTITY_SPLIT_ASSIGN_IF_FULFILLED, restartAttempt=START_AT_BEGINNING), afterActionNone=GroupAfterAction(actionID=1452, name=null, failoverAction=LINE_ITEM_SPLIT_ASSIGN_IF_FULFILLED, restartAttempt=START_AT_BEGINNING), description=, active=true, fulfillmentLimit=null}",
        "locations": [
          {
            "location": {
              "locationID": 33333,
              "locationCode": "Location One",
              "name": "location1",
              "tenantID": 00000,
              "express": false,
              "active": true,
              "postalCode": "29681-2913",
              "countryCode": "US",
              "latitude": 34.7335,
              "longitude": -82.2496,
              "directShip": true,
              "transferEnabled": true,
              "pickup": true,
              "state": "SC",
              "created": 1600361525000,
              "updated": 1611240378000,
              "formattedAddress": ", SC 29681-2913\\nUS",
              "addressAsOneLine": ", SC 29681-2913, US"
            },
            "group": null,
            "distance": "711.8406819306866 mi",
            "rank": 2,
            "maxLTDValueInInventory": 0,
            "inventoryCollection": [
              {
                "partNumber": null,
                "attributes": [],
                "ltd": 0,
                "floor": 0,
                "safetyStock": 0,
                "onHand": 33,
                "available": 28,
                "upc": "exampleItem",
                "sku": "exampleItem"
              }
            ]
          },
          {
            "location": {
              "locationID": 44444,
              "locationCode": "location2",
              "name": "Location Two",
              "tenantID": 00000,
              "express": false,
              "active": true,
              "postalCode": "78758",
              "countryCode": "US",
              "latitude": 30.3867,
              "longitude": -97.7083,
              "directShip": true,
              "transferEnabled": true,
              "pickup": true,
              "state": "TX",
              "created": 1596425613000,
              "updated": 1616679718000,
              "formattedAddress": ", TX 78758\\nUS",
              "addressAsOneLine": ", TX 78758, US"
            },
            "group": null,
            "distance": "1559.822496185389 mi",
            "rank": 1,
            "maxLTDValueInInventory": 0,
            "inventoryCollection": [
              {
                "partNumber": null,
                "attributes": [],
                "ltd": 0,
                "floor": 10,
                "safetyStock": 0,
                "onHand": 242,
                "available": 206,
                "upc": "exampleItem",
                "sku": "exampleItem"
              }
            ]
          }
        ]
      },
      {
        "type": "GROUP_SORT",
        "name": "Default",
        "causeID": 676,
        "errors": [],
        "sorts": [],
        "inputLocations": [
          "location1",
          "location2"
        ],
        "outputLocations": [
          "location2",
          "location1"
        ]
      },
      {
        "type": "FOUND_FULL_ORDER_LOCATION",
        "name": "Location Two",
        "causeID": 81960,
        "errors": null
      },
      {
        "type": "RESPONSE",
        "name": null,
        "causeID": null,
        "errors": null,
        "externalResponseID": null,
        "response": {
          "assignmentSuggestions": {
            "1": [
              {
                "orderItemID": 1,
                "locationID": 44444,
                "locationCode": "location2",
                "quantity": 2
              }
            ]
          },
          "stateChangeSuggestions": {
          },
          "availableLocations": [],
          "responseID": null,
          "externalResponseID": null,
          "suggestionLog": null
        }
      }
    ],
    "persisted": true,
    "pathString": "/29195/47906/1"
  }
]
The Suggestion API will return the collection of suggested location assignments OR state changes for each order item, based on current inventory and routing rules. There is one entry for each order item – in the example, one order item receives a suggested fulfillment location while the other order item could not be fulfilled by any location and thus the suggestion is to cancel the item instead. 
{
  "assignmentSuggestions": {
    "11111111": [
      {
        "orderItemID": 11111111,
        "locationID": 000000,
        "quantity": 1
      }
    ]
  },
  "stateChangeSuggestions": {
    "00000000": {
      "orderItemID": 00000000,
      "stateChange": "CANCEL",
      "quantity": 1
    }
  },
  "availableLocations": [],
  "responseID": 354608901,
  "externalResponseID": null,
  "suggestionLog": null
}
The pickupLocationID refers to the pickup location’s identifier within OMS, while the pickupExternalStoreID is used in eCommerce+OMS integrations to specify a location with eCommerce. If both are provided for the call and they do not match, then priority is placed on the pickupLocationID. The request is made using the OMS identifier as the reference location.

​
Suggestion API Shipment Grouping

The Suggestion API can also group shipments within locations, which provides greater flexibility in managing shipments depending on your business needs. This is supported for both Ship to Home and STH Consolidation transfer shipments, and is accomplished with additional grouping fields on the suggestion response:
  • The order item data includes a shipmentGroup identifier to specify the group for that item, alongside any data that you want to copy onto the resulting shipment line item. 
  • An assignmentSuggestionShipmentGroups object defines all shipment groups that appear in the response with their identifier and associated location code, as well as any data that you want to copy onto the order.
The system then generates shipments by combining line items first by their group and then by location. Any items without a set group will be grouped by location and shipment type. To enable this behavior, implement the Suggest Routing (After) API Extension. Use this extension to modify the suggestion response to include these grouping fields and any data attributes you want to include, such as in the example below. 
{
  "assignmentSuggestions": {
    "1": [
      {
        "orderItemID": 1,
        "locationCode": "USWH1",
        "quantity": 1,
        "route": "DIRECTSHIP",
        "futureDate": null,
        "shipmentGroup": null,
        "data": {
          "suggestionItem1": [
            "SuggestionItemData1"
          ]
        }
      }
    ],
    "2": [
      {
        "orderItemID": 2,
        "locationCode": "USWH1",
        "quantity": 1,
        "route": "DIRECTSHIP",
        "futureDate": null,
        "shipmentGroup": "group1",
        "data": {
          "suggestionItem2": [
            "SuggestionItemData2USWH1"
          ]
        }
      }
    ]
  },
  "assignmentSuggestionShipmentGroups": [
    {
      "locationID": 1,
      "id": "group1",
      "locationCode": "USWH1",
      "data": {
        "suggestionGroup1": [
          "SuggestionGroupData1"
        ],
        "rootOrder": "rootOrderGroupDataOverride"
      }
    }
  ],
  "availableLocations": [],
  "emptyResponse": false,
  "futureAssignmentSuggestions": {},
  "route": "DIRECTSHIP",
  "stateChangeSuggestions": {},
  "data": {
    "rootSuggestion1": [
      "RootSuggestionData1"
    ],
    "rootOrder": "rootOrderDataOverride"
  },
  "attributes": [
    {
      "attributeFQN": "Tenant~OR-ReturnAttribute",
      "attributeValues": [
        "new order attribute from or arc"
      ]
    },
    {
      "attributeFQN": "tenant~test3",
      "attributeValues": [
        123456
      ]
    }
  ]
}

​
Reverse Logistics Suggestions

The Order Routing API can also suggest the best return and disposition locations when the Reverse Logistics feature is enabled and configured with routing logic. This is similar to the routing candidate suggestions above, but occurs during the return process and takes into account the item’s return reason and condition.  Use the Reverse Logistics Suggestions API to perform your own calls and test behavior. If you want to view a log of the routing, append ?returnSuggestionLog=true to the endpoint.

​
Return Suggestion

To retrieve a return location suggestion, include the return reason in the item details with an order type of “return” and the customer’s shipping address that the items will be sent back from. 
{
  "orderType": "RETURN",
  "shippingAddress": {
    "addressID": 1000,
    "addressLine1": "123 Example Lane,",
    "city": "Austin",
    "countryCode": "US",
    "latitude": 30.384204,
    "longitude": -97.70392,
    "postalCode": "78758",
    "state": "TX"
  },
  "items": [
    {
      "orderItemID": 1,
      "quantity": 1,
      "productTitle": "product 1",
      "taxable": true,
      "tags": {},
      "returnReason": "Damaged",
      "upc": "sp_01"
    }
  ],
  "total": 304
}
The return response identifies the best location in the Return route for the item. 
{
  "reverseLogisticsSuggestions": {
  "WarehouseLocationCode001": {
      "locationID": 12345,
      "locationCode": "WarehouseLocationCode001",
      "route": "RETURN",
      "items": [
        {
          "orderItemID": 1,
          "quantity": 1,
          "returnReason": "Damaged",
          "dispositionCondition": null
        }
      ]
    }
  },
  "stateChangeSuggestions": {},
  "responseID": 22903197,
  "externalResponseID": null,
  "suggestionLog": null,
  "route": "RETURN"
}

​
Disposition Suggestion

To retrieve a disposition location suggestion, include the disposition condition in the item details with an order type of “disposition.” 
{
    "items": [
        {
            "orderItemID": 3,
            "partNumber": null,
            "sku": null,
            "quantity": 3,
            "upc": "987654321",
            "dispositionCondition": "Good"
        },
        {
            "orderItemID": 4,
            "partNumber": null,
            "sku": null,
            "quantity": 2,
            "upc": "123456789",
            "dispositionCondition": "Good"
        }
    ],
    "orderType": "DISPOSITION",
    "environmentID": 1,
    "shippingAddress": {
        "addressID": null,
        "customerID": null,
        "addressLine1": "1234 EXAMPLE DR",
        "phone": "1234567890",
        "city": "DENTON",
        "state": "TX",
        "postalCode": "76210-3469",
        "countryCode": "US",
        "latitude": 33.143186,
        "longitude": -97.088337
    },
    "isExpress": false,
    "pickupLocationCode": null,
    "locationCodeWhiteList": null,
    "exclusionListLocationCode": null,
    "inventoryRequestType": null,
    "externalResponseID": null,
    "orderID": 1234,
    "returnID": 5678,
    "total": 23.68,
    "fraud": null,
    "customData": null,
    "bundlingStrategy": "ITEM_DEPENDENCY",
    "numShipmentsNotInRequest": 0
}
The disposition response identifies the best location in the Disposition route for each item. In the below example, one location is suggested for all returned items. 
{
    "reverseLogisticsSuggestions": {
        "DispositionHub": {
            "locationID": 12345,
	    "locationCode": "DispositionHub",
	    "route": "DISPOSITION",
	    "items": [
		{
		    "orderItemID": 3,
		    "quantity": 3,
		    "returnReason": null,
		    "dispositionCondition": "Bad"
		},
		{
		    "orderItemID": 4,
		    "quantity": 2,
		    "returnReason": null,
		    "dispositionCondition": "Refurbished"
		}
	    ]
	}
    },
    "stateChangeSuggestions": {},
    "responseID": 22863308,
    "externalResponseID": "1888e73221c3e70001d4123600004626",
    "suggestionLog": null,
    "route": "DISPOSITION"
}