Merchandise Locator API

Merchandise Locator API

Purpose: Use the merchandise locator integration to request current availability information about an item/SKU in retail stores within a geographic search area or in external warehouses.

Request both shipment available as well as pickup locations? The message version specified in the Locate Properties File controls whether the merchandise locator search determines whether the item is available for shipment as well as obtaining locations where the customer can pick up the order:

• If the message version is set to 5.0 or higher, for integration with release 5.0 or higher of Locate, the merchandise locator search finds locations where the item is available for pickup, as well as indicating whether the item is available for shipment from a location. With this setting, your search specifies the requested quantity, and CWSerenade uses the ProductAvailability request and response to communicate with Locate.

• Otherwise, if the message version is set to 3.0 or 3.1, the merchandise locator search finds locations that can support pickup, but does not determine whether there are any locations that can ship the item.

Does not create orders: The merchandise locator search is an inquiry only, and does not create or update an order. See the Order Broker Integration for information on submitting a brokered backorder, store pickup, or ship-to-store order to Locate.

For more information: See:

• Locate Order Broker Integration Overview for background on integration between Locate and CWSerenade

• Locate/CWSerenade Configuration (Order Broker) for required setup in CWSerenade

• the Locate Operations Guide (version 5.0 or higher) or Integrator’s Guide (version 3.0 or 3.1) for details on the LocateItems request and response messages or the ProductAvailability request and response messages, your options in configuring merchandise locator searching, and details on logging and troubleshooting in Locate

In this topic:

• Merchandise Locator Process Overview

• Searching for Pickup Locations Only (Message Version 3.0 or 3.1)

• Searching for Pickup Locations and Shipment Availability (Message Version 5.0+)

• Merchandise Locator for Different Types of Items

• Merchandise Locator Troubleshooting

• Sample LocateItems Messages (Message Version 3.0 or 3.1)

• Sample ProductAvailability Messages (Message Version 5.0+)

• Merchandise Locator Search Window (Searching for an Item)

• Merchandise Locator Search Results Screen

• Display Merchandise Locator Search Result Screen

Merchandise Locator Process Overview

Searching for Pickup Locations Only (Message Version 3.0 or 3.1)

Overview: A typical process of inquiring on locations where an item is available for pickup is described below.

Used when? This process applies when the message version specified in the Locate Properties File is 3.0 or 3.1 for integration with those releases of Locate.

1.	A customer wants to know if an item/SKU is available for pickup at a nearby store. You select the item/SKU for merchandise locator inquiry. This option is available in order entry, order maintenance, and at the Display Item Availability Screen.
2.	You advance to the Merchandise Locator Search Window (Searching for an Item), where you provide or confirm the customer’s geographic location, and the radius to search within (for example, search all stores within 25 miles of the customer’s home). Note: The Order Broker supports merchandise locator searches only in the U.S. and Canada.
3.	In the background, the MERCH_LOC integration layer process: • Generates the LocateItems request message and sends it to an external system such as Locate. Locate checks the availability of the item in stores that stock the item/SKU within the search area. • Receives the LocateItems response returned by Locate. This message lists the item/SKU’s current or estimated availability in each searched location that stocks the item.
4.	You advance to the Merchandise Locator Search Results Screen, displaying the item/SKU’s availability in each of the locations, including information on any open purchase orders.

How does Locate select the locations to include? Only store locations flagged as Pickup available can be included in the search results. Also, Locate uses any probability rules you have set up to determine whether to include locations in the results, and the available quantity to indicate. For example, you might set up a probability rule for certain locations indicating to exclude them if the available quantity falls below 5 units, or to reduce the available quantity returned in the response message by 10%.

What information does Locate return for each location? For each location included in the search results, Locate indicates:

• the available quantity, next purchase order date, and next purchase order quantity

• the name, address, and phone number of the location.

• the distance from the search address:

• locations are sorted in ascending order by distance (closest location listed first)

• locations that are not flagged to Use Proximity Locator are listed without a distance

See the Merchandise Locator Search Results Screen and the Sample LocateItems Messages (Message Version 3.0 or 3.1) for more information.

Searching for Pickup Locations and Shipment Availability (Message Version 5.0+)

Overview: A typical process of inquiring on locations where an item is available for pickup, as well as whether the item is available for shipment from a location, is described below.

Used when? This process applies when the message version specified in the Locate Properties File is 5.0 or higher.

1.	A customer wants to know if an item/SKU is available for pickup at a nearby store or available for shipment from a store location. You select the item/SKU for merchandise locator inquiry. This option is available in order entry, order maintenance, and at the Display Item Availability Screen.
2.	You advance to the Merchandise Locator Search Window (Searching for an Item), where you provide or confirm the customer’s geographic location, the requested quantity of the item, and the radius to search within (for example, search all stores within 25 miles of the customer’s home). Note: The Order Broker supports merchandise locator searches only in the U.S. and Canada.
3.	In the background, the MERCH_LOC process: • Generates the ProductAvailability request message and sends it to Locate. Locate checks the availability of the item in stores that stock the item/SKU within the search area, as well as whether the item is available for shipment at any store locations within the same search area. • Receives the ProductAvailability response returned by Locate. This message lists: • the item/SKU’s current or estimated availability in each searched location that stocks the item for pickup • an indicator of whether the requested quantity of the item/SKU is available for shipment within the search area
4.	You advance to the Merchandise Locator Search Results Screen, displaying the item/SKU’s availability for pickup in each of the locations, including information on any open purchase orders. The screen also indicates whether the requested quantity of the item/SKU is available for delivery from a store within the same search area.

How does Locate select the locations to include?

• Locations eligible to fulfill pickup orders:

• Only store locations flagged as Pickup available can be included in the search results displayed at the Merchandise Locator Search Results Screen.

• Locate uses any probability rules you have set up to determine whether to include locations in the results, and the available quantity to indicate. For example, you might set up a probability rule for certain locations indicating to exclude them if the available quantity falls below 5 units, or to reduce the available quantity returned in the response message by 10%.

Results displayed: For each location included in the search results as eligible for a pickup order, the Merchandise Locator Search Results Screen indicates:

• the available quantity, next purchase order date, and next purchase order quantity

• the name, address, and phone number of the location

• the distance from the search address:

• locations are sorted in ascending order by distance (closest location listed first)

• locations that are not flagged to Use Proximity Locator are listed without a distance

Note:

• Any locations associated in Locate with your CWSerenade system are excluded from the results, regardless of whether there is a corresponding warehouse record in CWSerenade.

• If a location that stocks the item and is within the search radius is flagged in Locate as Backorder Available, it is returned in the search results even if it does not have the item available. In this case, the Pickup avail qty listed can be blank, or can be a negative quantity.

• If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity.

• Locations eligible to fulfill delivery orders: Only store locations flagged as Shipping available are eligible to fulfill a delivery order. Also, Locate:

• uses any probability rules you have set up to determine whether to include locations in the results, and the available quantity. For example, you might set up a probability rule for certain locations indicating to exclude them if the available quantity falls below 5 units, or to reduce the available quantity indicated in the response message by 10%.

• does not exclude locations flagged as Backorder available, even if the available quantity in the location is less than the requested quantity.

• restricts eligible locations to a fulfillment zone based on the search address, if configured in Locate.

• excludes locations associated with CWSerenade’s system in Locate, if the Disallow shopping within same system option is selected for the CWSerenade system in Locate.

• excludes locations that have already been assigned the Maximum Daily Orders, if Use Maximum Order Limits preference is selected in Locate.

Results displayed: If the results indicate that one or more locations could deliver the requested quantity, the Merchandise Locator Search Results Screen indicates Delivery From Store Is Available; otherwise, the screen indicates Delivery From Store Is Not Available.

Note: The delivery evaluation uses the same search radius as the pickup evaluation. To determine whether the item can be shipped without restricting the results to locations within driving distance of the customer, retry the search with a higher search radius.

For more information: See the Merchandise Locator Search Results Screen and the Sample ProductAvailability Messages (Message Version 5.0+) for more information on the search results.

ProductAvailability request not used when creating a pickup order: Unlike the merchandise locator search described here, when you create a pickup order in order entry by selecting the Store Pickup option, CWSerenade uses the LocateItems request message to search for store locations where the customer can pick up the order, regardless of the version specified in the Locate Properties File.

Merchandise Locator for Different Types of Items

Merchandise locator searches are not useful for the following types of items:

• membership item

• subscription item

• component of a set (although you can include the set master item)

• continuity item master (although you can include the continuity components)

Also, an item must have its Locate eligible flag selected in order to be eligible for a merchandise locator search. Typically, you would use this flag to exclude inappropriate items, such as gift certificates or gift cards, or any other items that are not available in external store locations.

Note: The restriction against set components applies only if the item is added to the order as a component of a set. If you enter the item as a separate order line, merchandise locator searching is still available.

Merchandise Locator Troubleshooting

Problem	Possible Explanation or Solution
A location that stocks the requested item is not listed at the Merchandise Locator Search Results Screen	The location might: • not have the Pickup available flag selected in Locate • be excluded because of probability rules • be outside of the search radius
The merchandise locator request message is producing invalid XML	Check that text fields included in the message, such as the item or SKU description, do not include any special characters. For example, the carat (^) and the pipe symbol (¦) are not valid characters in an XML message.
The Merchandise Locator Search Results Screen displays the error: Availability information is not accessible at this time	Could occur because: • communications between CWSerenade and Locate are not active • Locate could not identify the search location based on the information sent in the search request (for example, it has no record of the provided zip code). See the Locate Operations Guide for more information. • None of the locations within the search area have the item/SKU in stock. You can select Search again to change the search location or distance to search within. • None of the locations within the search area stock the item/SKU. You can select Search again to change the search location or distance to search within. • The customer address information provided in the merchandise locator request was invalid or incomplete. This could occur if, for example, you entered a Canadian address, but the database used to identify customer locations in Locate includes only U.S. addresses.
The Merchandise Locator Search Results Screen displays the error Item/Sku not Merchandise Locator eligible	The item’s Locate eligible flag is unselected, so Locate would not be able to identify the item.
The Merchandise Locator Search Results Screen displays the error FAILED: 1002 - Invalid item (system product), item (ROBOT ) does not exi	The selected item is Locate eligible, but has not yet been created in Locate.
The Merchandise Locator Search Results Screen does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date	This situation can occur if there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available): for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity.
The Merchandise Locator Search Results Screen lists a location with no quantity, or with a negative quantity	This situation can occur if a location that stocks the item and is within the search radius is flagged in Locate as Backorder Available.

Sample LocateItems Messages (Message Version 3.0 or 3.1)

Sample LocateItems request and response messages are provided below, along with notes on the information included in each message. For complete documentation on these messages, see the Locate Integrator’s Guide. CWSerenade generates the LocateItems request for a merchandise locator search if the version specified in the Locate Properties File is lower than 3.0 or 3.1.

Logged where? CWSerenade does not log these messages; however, they are available for review in Locate’s XML log file. See the Locate Integrator’s Guide for more information.

Note: The APP.log file includes entries for the CWMerchLocRequest and CWMerchLocResponse messages; however, these messages are used only to support processing the LocateItems request and response messages and the merchandise locator API, and are not themselves generic API messages.

Sample LocateItems Request Message

The information in this message includes:

• version: from the Locate Properties File

• destination: from the Locate Account (K49) system control value

• item_id: always indicates the CWSerenade item and SKU code, regardless of the setting of the Locate Product Code ID (K66) system control value

• fulfillment_type: always set to PICKUP, so that Locate returns locations in the search results only if they are flagged as Pickup Available.

• location_cd: from the Locate Default Location (K51) system control value

• system_cd: from the Locate System (Serenade) (K50) system control value

• address information: from the address information entered at the Merchandise Locator Search Window (Searching for an Item)

• distance: from the distance entered in the Search within field at the Merchandise Locator Search Window (Searching for an Item)

• unit: from the Merchandise Locator Distance Measurement (I39) system control value

<?xml version='1.0' encoding='UTF-8'?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://microsretail.com/Locate" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Body>

<location_request_message>

<message_header xaction_type="INSERT" xaction_response="" message_type="">

<source>CWSerenade</source>

<destination>LOCATE21</destination>

</message_header>

<message_body>

<items>

</items>

<store_location location_cd="2" system_cd="6"/>

</address>

<range>

</range>

</message_body>

</location_request_message>

</LocateItems>

</SOAP-ENV:Body>

Sample LocateItems Response Message

The information in the response includes:

• version: the version specified in the request message

• item_id: the item and SKU specified in the request message

• location_cd: the code identifying the location, as set up in Locate

• system_cd: the code identifying the location’s system, as set up in Locate

• distance: the total miles or kilometers (depending on the setting of the Merchandise Locator Distance Measurement (I39) system control value) between the address entered at the Merchandise Locator Search Window (Searching for an Item) and the address of the location. See the Dist for more information.

• distance unit: the distance unit (M or K) passed in the request message.

• available_qty: see the Pickup avail qty field for more information.

• next_po_qty: see the Open PO qty field for more information.

• po_dt: see the Next PO date field for more information.

• fulfillment_type:

• PICKUP = the location is flagged in Locate as Pickup Available, but not as Shipping available;

• OTHER = the location is flagged in Locate as both Pickup Available and either Shipping Available or Transfer Available

Note: If the location is not flagged as Pickup Available, it is not eligible for inclusion in the response message to CWSerenade.

• location name and address: the information entered in Locate for the location

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<location_response_message>

<message_header xaction_type="INFO" xaction_response="OK">

<source>Server</source>

<destination>CWSerenade</destination>

</message_header>

<message_body request_id="65073">

<items>

<locations_lu location_cd="694" system_cd="cws_11_doc" distance="41.45" distance_unit="M" available_qty="250" next_po_qty="0" po_dt="" fulfillment_type="OTHER" />

<locations_lu location_cd="9991" system_cd="cws_11_doc" distance="0" distance_unit="M" available_qty="123" next_po_qty="456" po_dt="2009-11-15" fulfillment_type="PICKUP" />

<locations_lu location_cd="1" system_cd="cws_11_doc" distance="37.21" distance_unit="M" available_qty="100" next_po_qty="0" po_dt="" fulfillment_type="PICKUP" />

</item>

</items>

<locationname>CWReading</locationname>

<address1>10 Example Street</address1>

<city>Reading</city>

</address>

</location>

<locationname>CWNatick</locationname>

<address1>24 Prime Park Way</address1>

<city>Natick</city>

</address>

</location>

<locationname>CWBoston</locationname>

<address1>53 Chauncy Street</address1>

<city>Cambridge</city>

</address>

</location>

</locations>

</message_body>

</location_response_message>

</LocateItemsResponse>

</soap:Body>

</soap:Envelope>

Sample ProductAvailability Messages (Message Version 5.0+)

Sample Product Availability request and response messages are provided below, along with notes on the information included in each message. CWSerenade generates the Product Availability request for a merchandise locator search if the version specified in the Locate Properties File is 5.0 or higher.

For complete documentation on these messages, see the Locate Operations Guide.

Logged where? CWSerenade does not log these messages; however, they are available for review in Locate’s XML log file. See the Locate Operations Guide for more information.

Not used when creating a pickup order: When you create a pickup order in order entry by selecting the Store Pickup option, CWSerenade uses the LocateItems request message to search for store locations where the customer can pick up the order, regardless of the version specified in the Locate Properties File.

Sample Product Availability Request Message

The information in this message includes:

• version: from the Locate Properties File

• destination: from the Locate Account (K49) system control value

• location code: from the Locate Default Location (K51) system control value

• system code: from the Locate System (Serenade) (K50) system control value

• type: the request includes both a fulfillment_type with a type of DELIVERY, and a fulfillment_type with a type of PICKUP

• range_distance: from the distance entered in the Search within field at the Merchandise Locator Search Window (Searching for an Item)

• range_unit: from the Merchandise Locator Distance Measurement (I39) system control value

• item ID: always indicates the CWSerenade item and SKU code, regardless of the setting of the Locate Product Code ID (K66) system control value

• qty: the Search quantity entered at the Merchandise Locator Search Window (Searching for an Item)

• address information: from the address information entered at the Merchandise Locator Search Window (Searching for an Item)

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">

<S:Body>

<ns2:ProductAvailability xmlns:ns2="http://microsretail.com/Locate">

<ns2:product_availability_request_message>

<message_header xaction_type="INSERT" xaction_response="" message_type="">

<source>CWSerenade</source>

<destination>LOCATE</destination>

</message_header>

<message_body>

<requesting_location location_cd="1" system_cd="6" />

<fulfillment_types>

<fulfillment_type type="DELIVERY" range_distance="10" range_unit="M" />

<fulfillment_type type="PICKUP" range_distance="10" range_unit="M" />

</fulfillment_types>

<items>

</items>

</address>

</message_body>

</ns2:product_availability_request_message>

</ns2:ProductAvailability>

</S:Body>

</S:Envelope>

Sample Product Availability Response Message

The information in the response includes:

• version: the version specified in the request message

• for the fulfillment_type with a type of DELIVERY:

• response_cd: set to 0 if the requested quantity of the item is available for delivery within the search radius; otherwise, set to 1011

• response_description: set to Success if the requested quantity of the item is available for delivery within the search radius; otherwise, set to Product not available within search criteria

• item ID: the item and SKU specified in the request message

If the full requested quantity is available for delivery, the Merchandise Locator Search Results Screen indicates Delivery From Store Is Available; otherwise, the screen indicates Delivery From Store Is Not Available.

• for the fulfillment_type with a type of PICKUP:

• response_cd: set to 0 if the requested quantity of the item is available for pickup within the search radius; otherwise, set to 1011

• response_description: set to Success if the requested quantity of the item is available for pickup within the search radius; otherwise, set to Product not available within search criteria

• item ID: the item and SKU specified in the request message

• location_cd: the code identifying the location, as set up in Locate

• system_cd: the code identifying the location’s system, as set up in Locate

• distance_unit: set to M if the distance unit specified was miles; otherwise, set to K

• available_qty: see the Pickup avail qty field for more information.

• next_po_qty: see the Open PO qty field for more information.

• po_dt: see the Next PO date field for more information.

• location: for each location included in the response, the name and address is included. The Display Merchandise Locator Search Result Screen displays much of the location name and address included in the message.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:ProductAvailabilityResponse xmlns:ns2="http://microsretail.com/Locate">

<product_availability_response_message>

<message_header xaction_response="OK" xaction_type="INFO">

<source>LOCATE</source>

<destination>CWSerenade</destination>

</message_header>

<message_body>

<fulfillment_types>

<fulfillment_type type="DELIVERY" response_cd="0" response_description="Success">

<items>

</items>

</fulfillment_type>

<fulfillment_type type="PICKUP" response_cd="0" response_description="Success">

<items>

<locations_lu location_cd="28" system_cd="cws" distance="0.0" distance_unit="M" available_qty="25" next_po_qty="0" po_dt="" />

<locations_lu location_cd="9101112" system_cd="STC" distance="0.0" distance_unit="M" available_qty="910" next_po_qty="0" po_dt="" />

</item>

</items>

</fulfillment_type>

</fulfillment_types>

<locationname>test inherit location type settings</locationname>

<address1>Example Street</address1>

<city>Westborough</city>

</address>

</location>

<locationname>Westborough Store</locationname>

<address1>1234 Example Street</address1>

<address2>Address2</address2>

<address3>Address3</address3>

<address4>Address4</address4>

<city>Westborough</city>

<email>example@sample_email.com</email>

</address>

</location>

</locations>

</message_body>

</product_availability_response_message>

</ns2:ProductAvailabilityResponse>

</soap:Body>

</soap:Envelope>

Merchandise Locator Search Window (Searching for an Item)

Purpose: Use this window to check availability for an item across external locations, such as retail stores, typically through Locate. To search, you need to specify the customer’s location, either by city and state or postal code, and the search radius. When the message version specified in the Locate Properties File is set to 5.0 or higher, indicating integration with release 5.0 or higher of Locate, you also need to specify a search quantity.

Address defaults: If you advance to this window in order entry or order maintenance, the customer’s address information defaults. Also, if you have overridden the address information in order entry or order maintenance, the system continues to default the override information until you are working with a different customer. For example, if you perform a search using the customer’s work address for an item/SKU, and then select another item/SKU for a search while working with the same order, the customer’s work address defaults.

How to display this window: Select Merch locator for an item at the:

• Work with Order Lines Screen (Adding Items to the Order)

• SKU Scan Screen

• Scan Order Lines Screen

• Display Item Availability Screen

Note: This option is available only if:

• The Use Merchandise Locator (I38) system control value is selected. Otherwise, the screen displays an error message: Merchandise Locator is not enabled. Also, merchandise locator searching is not available for all items; see Merchandise Locator for Different Types of Items for a listing of items that are not eligible.

• You have not already selected a quantity of the item to add to the current order at the Display Item Availability Screen in order entry. Otherwise, the screen displays an error message: Option not allowed since item already selected.

Important: The Locate Order Broker supports merchandise locator searches only within the U.S. and Canada.

The merchandise locator search is an inquiry only, and does not create or update an order. See the Order Broker Integration for information on submitting a brokered backorder, store pickup, or ship-to-store order to Locate.

Field	Description
Item	The item selected at the previous screen. The SKU information, if any, is to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, three 4-position fields; display-only.
Item description	The description of the item. Even if the item has SKUs, the item description is displayed. Alphanumeric, 40 positions; display-only.
Note: If you advanced to this window from order entry or order maintenance, the customer’s address information defaults.
Postal code	The customer’s U.S. zip or Canadian postal code, to serve as the central point for the search radius. For example, if the Search within field is set to 25 miles, the search includes stores within 25 miles of this postal code. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Note: Your entry in this field is not validated against the Zip/City/State table. Alphanumeric, 10 positions; required if you do not enter a city and state.
Address	The customer’s street address, to serve as the central point for the search radius. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 32 positions; optional.
City	The customer’s city, to serve as the central point for the search radius. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 25 positions; required if you do not enter a postal code.
State	The customer’s U.S. state or Canadian province, to identify the location of the city. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 2 positions; required if do not enter a postal code.
Country	The customer’s country. The country defaults from the customer address if you advanced to this window from order entry or order maintenance; otherwise, it defaults from the Default Country for Customer Address (B17) system control value. Defined in and validated against the Country table; see Setting Up the Country Table (WCTY) for more information. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 2 positions; required.
Search quantity	The requested quantity of the item. Defaults to 1. Note: Included only if the Locate Properties File specifies a message version of 5.0 or higher. Numeric, 7 positions; required.
Search within	Indicates the search radius, in miles or kilometers, to search within for the selected item. The search radius defaults from the Default Search Within Radius (I40) system control value, but you can override it. Note: • The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. • The distance unit of measure (miles or kilometers) specified with the Merchandise Locator Distance Measurement (I39) system control value is displayed to the right. • Typically, a search for a delivery location can use a broader search radius than a search for a pickup location, which is generally within driving distance. To see if the item is available for delivery as opposed to pickup, you might search twice, specifying a different search radius when determining if the item is available for delivery. Numeric, 5 positions; required.

Completing this window:

• If they have not already defaulted, indicate the postal code or the city and state to serve as the central point for the search radius.

• Optionally, override the Search quantity if you are integrating with Locate 5.0 or higher.

• Optionally, override the Search within radius to a different distance.

• Click OK. The system generates the:

• LocateItems request message if the Locate Properties File specifies version 3.0 or 3.1. See Sample LocateItems Messages (Message Version 3.0 or 3.1) for more information.

• ProductAvailability request message if the Locate Properties File specifies a version of 5.0 or higher. See Sample ProductAvailability Messages (Message Version 5.0+) for more information.

When the system receives the response message, you advance to the Merchandise Locator Search Results Screen.

Merchandise Locator Search Results Screen

Purpose: Use this screen to review an item’s availability in external locations. You can also use this screen to review more information about an external location.

How to display this screen: Complete the Merchandise Locator Search Window (Searching for an Item) and click OK.

Troubleshooting: See Merchandise Locator Troubleshooting.

For more information: See the Sample LocateItems Messages (Message Version 3.0 or 3.1) or the Sample ProductAvailability Messages (Message Version 5.0+) for examples of the actual response messages used to populate the information on this screen.

Note: You cannot submit an order to Locate through this screen. See the Order Broker Integration for information on submitting a brokered backorder, store pickup, or ship-to-store order to Locate.

Field	Description
Locations closest to	The address information provided at the Merchandise Locator Search Window (Searching for an Item). This information could be just a postal code or a city and state, or could include additional information such as the street address. The information is truncated if it exceeds the space allowed on this screen. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Alphanumeric, 55 positions; display-only.
Radius	The Search within radius selected at the Merchandise Locator Search Window (Searching for an Item). The setting of the Merchandise Locator Distance Measurement (I39) (miles or kilometers) is to the right. The search radius applies only to locations that use proximity rules. You might set up Locate so that proximity rules apply to stores only and not warehouses. Numeric, 5 positions; display-only.
Location types	Always set to All (both stores and warehouses). Note: Not included if the Locate Properties File specifies a message version of 5.0 or higher. Alphanumeric, 3 positions; display-only.
Item	The item selected for search. The SKU information, if any, is to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, three 4-position fields; display-only.
Item description	The description of the item. Even if the item has SKUs, the item description is displayed. Alphanumeric, 40 positions; display-only.
Delivery availability (unlabeled field to the right of the item description)	If the results indicate that one or more locations could deliver the requested quantity, the Merchandise Locator Search Results Screen indicates Delivery From Store Is Available; otherwise, the screen indicates Delivery From Store Is Not Available.
Each location in the search results where the customer could pick up the item is displayed below. Locations are sorted by distance (nearest to farthest away).
Dist	The number of miles or kilometers, based on the Merchandise Locator Distance Measurement (I39), from the search location. This distance might be approximate, depending on the actual criteria used to search (for example, postal code or city), and does not represent an actual driving distance. No distance is displayed if the location is not set up in Locate to use proximity rules. In this situation, the location is always considered to be within the specified search radius. The distance is rounded down when determining whether to include the location in the search results. For example, if the Search radius is 10 miles, and the location is 10.84 miles away, the location is included in the results. Numeric, 7 positions with a 2-place decimal.
Location	The description and address of the location where the item/SKU is available, and can include: • description • city • state • postal code • country This information is provided directly from Locate, and is not derived from the Store Cross Reference table in CWSerenade. Note: Searching the locations displayed on the screen based on location name is not currently implemented. Description: alphanumeric, 40 positions; display-only. City: alphanumeric, 25 positions; display-only. State: alphanumeric, 2 positions; display-only. Postal code: alphanumeric, 10 positions; display-only. Country: alphanumeric, 3 positions; display-only.
Pickup avail qty	The quantity of the item/SKU reported in the response message as available for pickup in this location. Depending on your settings within Locate, this quantity may be approximate, or calculated based on probability rules. Note: • If a location that stocks the item and is within the search radius is flagged in Locate as Backorder Available, it is returned in the search results even if it does not have the item available. In this case, the Pickup avail qty listed can be blank, or can be a negative quantity. • If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 7 positions; display-only.
Open PO qty	The quantity of the item/SKU reported on open purchase orders for this location; depends on how the external system calculates the open PO quantity. Note: If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 7 positions; display-only.
Next PO date	The date when the next purchase order for this item/SKU is due to be received at this location; depends on how the externals system calculates the next PO date. Note: If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 6 positions (MM/DD/YY format); display-only.

Option	Procedure
Display a location	Select Display for a location to advance to the Display Merchandise Locator Search Result Screen.
Search again	Select Search again to return to the Merchandise Locator Search Window (Searching for an Item).

Display Merchandise Locator Search Result Screen

Purpose: Use this screen to review additional details about a location where the customer might be able to pick up the item. You cannot make any changes on this screen.

Note: The address components, such as postal code, country, and phone number, are provided by external systems and might not be formatted or validated at this screen the same way as they are for data stored in CWSerenade.

How to display this screen: Select Display for a location at the Merchandise Locator Search Results Screen.

Field	Description
Item	The item selected for search. The SKU information, if any, is to the right. Item code: alphanumeric, 12 positions; display-only. SKU: alphanumeric, three 4-position fields; display-only.
Description	The description of the item. Even if the item has SKUs, the item description is displayed. Alphanumeric, 40 positions; display-only.
Loc type	Always set to All (both stores and warehouses). Note: Not included if the Locate Properties File specifies a message version of 5.0 or higher. Alphanumeric, 3 positions; display-only.
Distance	The number of miles or kilometers, based on the Merchandise Locator Distance Measurement (I39), from the search location. This distance might be approximate, depending on the actual criteria used to search (for example, postal code or city), and does not represent an actual driving distance. The setting of the Merchandise Locator Distance Measurement (I39) (miles or kilometers) is to the right. The distance displayed is .00 if the location is not set up in Locate to use proximity rules. In this situation, the location is always considered to be within the specified search radius. Numeric, 7 positions with a 2-place decimal.
Location	The description and address of the location where the item/SKU is available, consisting of: • description (the Name from Locate) • street address (up to four lines) • city • state • postal code • country • phone number (does not include the extension or the fax number) This information is provided directly from Locate, and is not derived from the Store Cross Reference table in CWSerenade. Description: alphanumeric, 40 positions; display-only. Street: alphanumeric, 40 positions each; display-only. City: alphanumeric, 25 positions; display-only. State: alphanumeric, 2 positions; display-only. Postal code: alphanumeric, 10 positions; display-only. Country: alphanumeric, 3 positions; display-only. Phone number: alphanumeric, 14 positions; display-only.
Available	The quantity of the item/SKU reported in the response message as available for pickup in this location. Depending on your settings within Locate, this quantity may be approximate, or calculated based on probability rules. Note: • If a location that stocks the item and is within the search radius is flagged in Locate as Backorder Available, it is returned in the search results even if it does not have the item available. In this case, the Pickup avail qty listed can be blank, or can be a negative quantity. • If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 7 positions; display-only.
Open PO	The quantity of the item/SKU reported on open purchase orders for this location; depends on how the external system calculates the open PO quantity. If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 7 positions; display-only.
Next PO	The date when the next purchase order for this item/SKU is due to be received at this location; depends on how the externals system calculates the next PO date. If there are locations that stock the item and are within the search radius, but none have the full requested quantity available (and are not flagged as Backorder Available), the Merchandise Locator Search Results Screen displays the locations, but does not indicate the Dist, Pickup avail qty, Open PO qty, or Next PO date. This situation could occur if, for example, the customer requests 5 units, and none of the locations have more than 4 units available. To display the full information for the displayed locations, search again with a lower Search quantity. Numeric, 6 positions (MM/DD/YY format); display-only.

Order Broker Aging Report

Contents

SCVs

Search

Glossary

Reports

Database

Solutions

XML

Index

Stored Value Card Integration

LO01_03 Serenade 5.0 March 2015