OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

Get Routing Candidates

The Candidates API is a reference used to filter fulfillment locations based on inventory and order routing rules. Rather than determine exactly where the order 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. It is particularly useful with STH orders in order to calculate the estimated arrival time of a shipment.

In the case of clients using inventory replenishment, STST (or TISPU) orders routed through OMS must generate transfer orders properly based on managed inventory replenishment relationships. Calling this Candidates API will provide locations with products in quantities replenishable to the requested location.

Note that this call is made to the order routing application. Contact Kibo if assistance is needed with authentication keys or accessing this API.

Version1.0
Callhttp://integration.shopatron.com/order-routing/api/v1/routing/candidates
Supported FormatsJSON
HTTP MethodPOST

An example use of the Candidates API follows below, or view the sample Postman Collection.

Example

The example case searches for candidates that apply to an order with the following properties:

  • STH order set to be picked up at Location ID 010101
  • Fulfilled by Manufacturer 00000 and Retailer 11111

This guide will demonstrate how to put together each section of the request to retrieve candidates.

Required Parameters

The following are required for all instances of this call.

ParameterTypeDescription
manufacturerIDintegerA unique identifier for the manufacturer.
fulfillerIDintegerA unique identifier for the fulfiller.
catalogIDintegerThe catalog number for the manufacturer.
productIdentifierMappingenumThe part number, UPC, and/or SKU configuration used to identify the product (“PART_NUMBER_ONLY”, “UPC_ONLY”, “SKU_ONLY”, “PART_NUMBER_AND_UPC”, “PART_NUMBER_AND_SKU”, “UPC_AND_SKU”, or “PART_NUMBER_AND_UPC_AND_SKU”).
routeTypeenumThe fulfillment type that the order has been assigned to (“STH”, “CERTIFIED”, “EXPRESS”, “PREORDER”, “WFA”, “STSA”, or “TRANSFER”).
itemsobjectThe items included in the order.

The items object is made up of the following parameters:

ParameterTypeDescription
partNumberstringThe part number for the product, an identifier unique to the manufacturer.
UPCstringThe Universal Product Code for this product.
SKUstringThe Stock Keeping Unit code for this product.
quantityintegerThe number of items in the order.
customItemDataobjectCustom information provided for the order (e.g. a map of key-value pairs). Value entries may contain integers, decimals, booleans, or strings.

Optional Parameters

Other possible parameters can be provided to specify other details about the route. These variables are:

ParameterTypeDescription
pickupLocationIDintegerThe unique identifier for the location where the order will be picked up.
pickupExternalStoreIDstringAn external identifier for the location where the order will be picked up.
shippingAddressobjectThe street address that the order will be shipped to.

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.

The shippingAddress object is made up of the following parameters:

ParameterTypeDescription
addressLine1stringThe first line of the street address.
citystringThe city that the street address is located in.
countryCodestringThe code indicating the country that the address is location in (e.g. US, AD, etc.).
phonestringThe phone number of the location.
postalCodestringThe postal code or zip code of the address.
statestringThe state that the street address is located in (e.g. TX, CO).
latitudedecimalThe latitudinal value of the location.
longitudedecimalThe longitudinal value of the location.

The Full Request

This is the entire request that will retrieve routing candidates.

"manufacturerID":00000,
"fulfillerID":11111,
"catalogID":0,
"productIdentifierMapping":"PART_NUMBER_ONLY",
"pickupLocationID":010101,
"routeType":"STH",
"shippingAddress":{
   "addressLine1":"123 Main St.",
   "city":"Dallas",
   "countryCode":"US",
   "phone":"0001111234",
   "postalCode":"95448",
   "state":"TX",
   "latitude":32.7791,
   "longitude":-97.0404
},
"items":[
 {
   "partNumber":"TestItem",
   "upc":"TestItem",
   "sku":"TestItem",
   "quantity":1,
   "customItemData":{
   "customDataKey1":100,
   "customDataKey2":"customString",
   "customDataKey3":true,
   …
 }
 }
]

The Full Response

This response is the collection of locations that the order could potentially be routed to, based on inventory and routing rules. No action will be taken as a result of this call, as it merely a reference list. This example has two candidates.

{
    "candidateSuggestions": [
        {
            "locationID": 22222,
            "externalStoreID": "120021",
            "locationName": "22222",
            "addressLine1": "200 Test Drive",
            "addressLine2": null,
            "addressLine3": null,
            "city": "Dallas",
            "state": "TX",
            "countryCode": "US",
            "postalCode": "75201",
            "phone": null,
            "distance": "408.33899379799998996531940065324306488037109375 mi",
            "latitude": null,
            "longitude": null,
            "localSalesTax": null,
            "express": true,
            "pickupEnabled": false,
            "restockEnabled": false,
            "shippingLocation": true,
            "taxableLocation": null,
            "inventory": [
                {
                    "partNumber": "LoadTestingPart1",
                    "available": 99996,
                    "sku": "LoadTestingPart1",
                    "upc": "LoadTestingPart1"
                }
            ]
        },
        {
            "locationID": 33333,
            "externalStoreID": "210012",
            "locationName": "33333",
            "addressLine1": "111 Example Rd",
            "addressLine2": null,
            "addressLine3": null,
            "city": "Dallas",
            "state": "TX",
            "countryCode": "CA",
            "postalCode": "75201",
            "phone": null,
            "distance": "457.7500223600000026635825634002685546875 mi",
            "latitude": null,
            "longitude": null,
            "localSalesTax": null,
            "express": true,
            "pickupEnabled": false,
            "restockEnabled": false,
            "shippingLocation": true,
            "taxableLocation": null,
            "inventory": [
                {
                    "partNumber": "LoadTestingPart1",
                    "available": 99992,
                    "sku": "LoadTestingPart1",
                    "upc": "LoadTestingPart1"
                }
            ]
        }
    ]
}