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.
| Version | 2.0 |
| Production URL | https://{tenantId}-translation.mozu.com/api/v1/routing/candidates |
| Sandbox URL | https://{tenantId}-translation.mozu.com/api/v1/routing/candidates |
| Supported Formats | JSON |
| HTTP Method | POST |
| Schema | https://integration.shopatron.com/api/v1/routing/candidates.json |
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.
| Parameter | Type | Description |
| manufacturerID | integer | A unique identifier for the manufacturer. |
| fulfillerID | integer | A unique identifier for the fulfiller. |
| catalogID | integer | The catalog number for the manufacturer. |
| productIdentifierMapping | enum | The 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"). |
| routeType | enum | The fulfillment type that the order has been assigned to ("STH", "CERTIFIED", "EXPRESS", "PREORDER", "WFA", "STSA", or "TRANSFER"). |
| items | object | The items included in the order. |
The items object is made up of the following parameters:
| Parameter | Type | Description |
| partNumber | string | The part number for the product, an identifier unique to the manufacturer. |
| UPC | string | The Universal Product Code for this product. |
| SKU | string | The Stock Keeping Unit code for this product. |
| quantity | integer | The number of items in the order. |
| customItemData | object | Custom 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:
| Parameter | Type | Description |
| inventoryRequestType | string | Allows the returned locations to be filtered based on inventory levels (ALL, PARTIAL, ANY, ALL_STORES). See below for more details. |
| pickupLocationID | integer | The unique identifier for the location where the order will be picked up. |
| pickupExternalStoreID | string | An external identifier for the location where the order will be picked up. |
| shippingAddress | object | The street address that the order will be shipped to. |
The effects of the inventoryRequestType values are:
| Value | Description |
| ALL | Returns locations that have the full quantity available for all of the products in the request. |
| PARTIAL | Returns locations that have the full quantity available for at least one of the products in the request. |
| ANY | Returns locations that have any quantity available for any of the products in the request. |
| ALL_STORES | Returns all stores that are part of the location network and their inventory levels, even if they have no current inventory available for a product in the request. |
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:
| Parameter | Type | Description |
| addressLine1 | string | The first line of the street address. |
| city | string | The city that the street address is located in. |
| countryCode | string | The code indicating the country that the address is location in (e.g. US, AD, etc.). |
| phone | string | The phone number of the location. |
| postalCode | string | The postal code or zip code of the address. |
| state | string | The state that the street address is located in (e.g. TX, CO). |
| latitude | decimal | The latitudinal value of the location. |
| longitude | decimal | The 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"
}
]
}
]
}