Generic Pick In API (Shipments, Voids, and Backorders)

Generic Pick In API (Shipments, Voids, and Backorders)

Purpose: Use the generic Pick In API to confirm shipments, void pick slips, or confirm partial shipments of backorders. This API is part of the integration with a warehouse management system, and enables you to complete the fulfillment processing after using Pick Out Processing to send pick slips to the warehouse management system. The Pick In API provides details on whether the warehouse management system was successful in shipping the requested quantity of each detail line on the pick slip.

Voiding retail pickup, delivery, or special ship-for-pickup orders: If the Cancel Reason (Pick In) (L86) system control value specifies a cancel reason, then when you void a pick slip for a retail pickup, delivery, or special ship-for-pickup order through the generic pick in API, the system automatically cancels the order line using that cancel reason and sends a status update to Order Broker. Voiding a pick slip for a regular ship-for-pickup order cancels the order in Order Broker, but not the order in Order Management System. See the Cancel Reason (Pick In) (L86) system control value for a discussion.

Note: To prevent sending incorrect shipment updates to Order Broker, do not use the void/keep reservation or partial backorder transaction types for retail pickup, delivery, or ship-for-pickup orders. See Pick In Void/Keep Reservation and Pick In Partial Backorders for information on these types of transactions, and see Retail Pickup (including Ship-for-Pickup) or Delivery Orders and Ship-for-Pickup Orders for background on these types of orders.

In this chapter:

• Pick In Process Overview

- Pick In Shipment Confirmation

- Pick In Void

- Pick In Void/Unreserve

- Pick In Void/Keep Reservation

- Pick In Partial Backorders

- Evaluating Inventory Availability and Performing Reservation during PIck In Processing

• Sample Pick In XML Messages

- Sample Shipment Confirmation Message

- Sample Void Message

- Sample Void/Unreserve Message

- Sample Void/Keep Reservation Message

- Sample Partial Backorder Message

• Troubleshooting the Pick In API

• Pick In Setup

• CWPickIn XML Message

For more information: See Working with Pick Invoice Errors (WPIE).

Pick In Process Overview

Overview: The Pick In API uses the CWPickIn message to process updates from a warehouse management system indicating the current status of pick slips previously sent through the Generic Pick In API (Shipments, Voids, and Backorders).

Transactions: The Pick In API can process a:

• shipment confirmation when the entire pick slip has been shipped and can bill. See Pick In Shipment Confirmation.

• void when the items cannot ship on the current pick slip, but the items can remain reserved and eligible to print when you generate new pick slips. See Pick In Void.

• void/unreserve when the items on the pick slip cannot be shipped and should be unreserved, then canceled. See Pick In Void/Unreserve.

• void/keep reservation when one or more of the units printed on the pick slip have shipped, but others cannot be shipped and should remain reserved. In this situation, the system:

- Generates a new pick slip for the quantity listed as shipped for each pick detail line and keeps reserved any printed quantity that is not listed as shipped.

- If the auto_bill flag in the CWPickIn message is set to Y, the system automatically bills the replacement pick slip that includes the shipped items; otherwise, the replacement pick slip bills when you receive a subsequent CWPickIn message or confirm shipment by any other means.

- Voids the original pick slip referenced in the message.

- Performs pick slip preparation for any reserved items that were not included on the new pick slip.

• partial backorder when one or more of the units printed on the pick slip have shipped, but others cannot be shipped and should be unreserved, then canceled. In this situation, the system:

- Generates a trigger for a replacement pick slip XML message that includes just the shipped items, and unreserves the unshipped units on the original pick slip. The system also creates a record in the Void Auths table for the amount of the items that were unreserved.

See Pick In Partial Backorders.

Pick slip preparation: If the Pick In API unreserves or cancels an order line, the system removes any pick slip preparation from the order and then reevaluates the order for pick slip preparation; see Preparing Orders for Pick Slip Generation.

Pick In Shipment Confirmation

The confirmation message (transaction_type C) confirms shipment of the entire pick slip, so it is not necessary to include the pick detail lines; however, if the message does include pick detail line information, the system ignores that information and confirms the entire pick slip anyway.

Carton details: Optionally, the message can include carton details for the shipped pick detail lines. In this case, the system tracks this information in the Carton Contents table, and it is available for review at the Display Package Information Screen. The pick detail line number for each carton detail must match a shipped pick detail number.

Sample message: See Sample Shipment Confirmation Message.

Order transaction history: The system writes an order transaction history message that details the shipment information:

Type	Transaction Note	Amount	User
SHIPMENT	Pick# 9999 Mtr 12.50 Wgt 5.02	12.50	your default user
SHIPMENT	Via 2 T# 9121825213907179818238	12.50	your default user

Pick In Void

The void message (transaction_type V) voids the pick slip but leaves all the detail lines in reserved status. The order lines are then eligible to be printed on another pick slip when you use pick slip generation.

It is not necessary to include any other information in a void message.

Sample message: See Sample Void Message.

Order transaction history: The system writes an order transaction history message indicating the pick slip was voided:

Type	Transaction Note	User
VOID/REPRINT	Pick (9999) was voided.	your default user

Pick In Void/Unreserve

The void/unreserve message (transaction_type U) voids the pick slip and unreserves on the detail lines that were printed. You can then cancel the order.

It is not necessary to include any other information in a void/unreserve message.

You can also process a void/unreserve through the partial backorder transaction type; if all of the pick detail lines included in a partial backorder message have a qty_shipped of 0, the Pick In API unreserves all the order lines included on the pick slip and changes the status of the pick slip to VOID. See the Pick In Void for processing details.

Evaluating inventory availability and performing reservation: When the Reserve within PICK_IN Processing (L79) system control value is selected, and the transaction_type is U or B with a qty_shipped of 0 for the line, the system performs an inventory availability evaluation and reservation attempt when it voids and unreserves the line. See Evaluating Inventory Availability and Performing Reservation during PIck In Processing for processing details.

Sample message: See Sample Void/Unreserve Message.

Order transaction history: The system writes an order transaction history message indicating the pick was voided and unreserved. If the Reserve within PICK_IN Processing (L79) system control value is selected and one or more lines on the pick was eligible for re-reservation, the system writes an order transaction history message indicating each line that was re-reserved in a warehouse:

Type	Transaction Note	User
VOID/REPRINT	Pick 9999 was voided and unreserved.	your default user
UNRESERVED	Order Line 2 unrsv’d w/BO qty of 1.	your default user
UNRESERVED	Order Line 1 unrsv’d w/BO qty of 1.	your default user
MAINT	Order Line 1 re-reserved in warehouse 8	PICK_IN

Pick In Void/Keep Reservation

The void/keep reservation message (transaction_type R) generates a new pick slip for the quantity listed as shipped for each pick detail line and keeps reserved any printed quantity that is not listed as shipped. The system voids the original pick slip referenced in the message. The system performs pick slip preparation for any reserved items that were not included on the new pick slip; see Preparing Orders for Pick Slip Generation.

This transaction type requires every line on the pick to include a qty_shipped so that Order Management System knows how many units are still reserved on the line. For example, if pick line number 3 is associated with 4 units, and the qty_shipped is 1, the system generates a new pick slip for 1 unit and keeps reserved the other 3 units:

If a pick line is not included in the message or does not include a qty_shipped, the system assumes the full quantity of the line shipped and will be included on the new pick slip.

Immediate billing: If the auto_bill flag is Y, then the system automatically bills the new pick slip; otherwise, the system does not bill the new pick slip until it receives a shipment confirmation.

Order transaction history: The system writes an order transaction history message indicating the pick was reprinted:

Type	Transaction Note	User
VOID/REPRINT	Pick 3734 reprinted as pick 3736.	your default user

Pick In Partial Backorders

The partial backorder message (transaction_type B) generates a new pick slip for the quantity listed as shipped for each pick detail line and unreserves any printed quantity that is not listed as shipped.

If the entire quantity of the pick detail line is unavailable, then the PickDetail element should indicate a qty_shipped of 0:

Indicating the shipped quantities for a partial backorder: The CWPickIn message for a partial backorder needs to indicate the shipped quantity for each pick detail line. For example, the pick slip included the following details:

• line 1: 2 units printed, 2 units shipped

• line 2: 5 units printed, 3 units shipped

• line 3: 10 units printed, 0 units shipped

The CWPickIn message in this case should indicate the shipped quantity for each of the above detail lines, even if the shipped quantity is zero. When the system receives the message including this information, it compares the shipped quantity with the printed quantity of each line and processes the updates accordingly. If a detail line is not included, the system assumes the entire line shipped.

Evaluating inventory availability and performing reservation: When the Reserve within PICK_IN Processing (L79) system control value is selected, and the transaction_type is U or B with a qty_shipped of 0 for the line, the system performs an inventory availability evaluation and reservation attempt when it voids and unreserves a line. See Evaluating Inventory Availability and Performing Reservation during PIck In Processing for processing details.

Sample message: See Sample Partial Backorder Message.

Type	Transaction Note	User
UNRESERVED	Order Line 2 unrsv’d w/BO qty of 1.	your default user
UNRESERVED	Order Line 1 unrsv’d w/BO qty of 1.	your default user
MAINT	Order Line 1 re-reserved in warehouse 8	PICK_IN
VOID/REPRINT	Pick 3553 reprinted as pick 3555.	your default user

What if all the pick lines on a partial backorder message have a quantity of zero? If the transaction type indicated in the CWPickIn message is partial backorder (transaction_type B), but all of the pick detail lines included in the message have a qty_shipped of 0, the Pick In API unreserves all the order lines included on the pick slip and changes the status of the pick slip to VOID. See Pick In Void for processing details.

Partial backorders of set items: Set items are included on pick slips as:

• a set master item: the non-inventory item representing the set as a whole. The set master item is always reserved and bears the price of the entire set.

• multiple component items: the actual inventoried items that make up the set.

To correctly process a partial backorder for a set item, the CWPickIn message must include the shipped quantity of the set master item. The Pick In API uses the shipped quantity of the set master item to determine the quantity shipped for each component item. Set component items are treated differently for partial backorders in that you do not need to indicate a shipped quantity for components:

Example:

Your set item SET1 includes:

• 1 unit of COMPONENT1

• 2 units of COMPONENT2

You print a pick slip for 3 units of SET1, so the pick slip includes:

• 3 units of SET1

• 3 units of COMPONENT1

• 6 units of COMPONENT2

The CWPickIn message indicates a shipment quantity of 2 units of SET1.

The system bills:

• 2 units of SET1

• 2 units of COMPONENT1

• 4 units of COMPONENT2

And the system unreserves the remaining units:

• 1 unit of SET1

• 1 unit of COMPONENT1

• 2 units of COMPONENT2

Should the CWPickIn message include the set components? The simplest way to confirm shipment of a partial backorder of set items is to include just the set master and not the components in the CWPickIn message, as the system automatically bills the correct number of units of each component item based on the shipped quantity of the set master. If you prefer to include the component items as well as the set master item, it is important that the shipped quantities of each component item match the component quantity specified for the set multiplied by the shipped quantity for the set master. In the above example, if the CWPickIn message indicated a shipment quantity of each unit of the set master and the 2 components, this would produce an error, since 2 units of COMPONENT2 are required to complete shipment of 1 unit of the set.

Evaluating Inventory Availability and Performing Reservation during PIck In Processing

If the Reserve within PICK_IN Processing (L79) system control value is selected, the Pick In API performs an inventory availability evaluation and reservation attempt when it voids and unreserves a line.

The Pick In API performs the inventory availability evaluation and reservation attempt when:

• the transaction_type is U Void and Unreserve, or

• the transaction_type is B Full or Partial Backorder and the qty_shipped for the line is 0.

The system:

• If a warehouse list is defined, uses the list to determine which allocatable warehouses to evaluate. The system starts with the first warehouse in the list and skips the warehouse that it is currently unreserved from. The system continues going through the list until it finds a warehouse that has sufficient inventory to cover the entire quantity requested.

• If a warehouse list is not defined, evaluates all allocatable warehouses other than the one it just unreserved from.

If the system determines that there is another warehouse that has sufficient available stock to meet the entire quantity that was just unreserved, the system:

• performs an immediate reservation in that other warehouse.

• writes an order transaction history message that details the line # and the new reservation warehouse:

Type	Transaction Note	User
VOID/REPRINT	Pick 9999 was voided and unreserved.	your default user
UNRESERVED	Order Line 2 unrsv’d w/BO qty of 1.	your default user
UNRESERVED	Order Line 1 unrsv’d w/BO qty of 1.	your default user
MAINT	Order Line 1 re-reserved in warehouse 8	PICK_IN

If the system does not find a single warehouse that can cover the entire quantity that was unreserved, the system backorders the line against the warehouse that it was just unreserved from.

Note:

• The system will not reserve a single line out of multiple warehouses as part of this evaluation.

• The system evaluates each line on the pick individually. Because of this, each line could reserve out of a different warehouse based on an item's availability if there are more than 2 allocatable warehouses to evaluate.

• If auto_bill is set to Y, the system creates a new pick to be billed for the lines that were shipped. The system does not include the re-reserved lines on this pick.

Excluded from inventory availability evaluation and reservation: The system does not perform the inventory availability evaluation and reservation attempt in the following scenarios.

• An override warehouse is defined for the item.

• The line is a set master item or set component item.

• If the order has a Broker Type of Retail Pickup or Delivery.

• The order has an order type that matches the order type in the Order Type for Special Orders (L15) system control value.

• The User 1 field for the item contains the text SPECIAL.

Sample Pick In XML Messages

Sample messages presented below:

• Sample Shipment Confirmation Message

• Sample Void Message

• Sample Void/Unreserve Message

• Sample Void/Keep Reservation Message

• Sample Partial Backorder Message

Sample Shipment Confirmation Message

See Pick In Shipment Confirmation for an overview.

</CartonDetails>

</CartonHeader>

</CartonHeaders>

</CWPickIn>

</Message>

Sample Void Message

See Pick In Void for an overview.

</Message>

Sample Void/Unreserve Message

See Pick In Void/Unreserve for an overview.

</Message>

Sample Void/Keep Reservation Message

See Pick In Void/Keep Reservation for an overview.

</PickDetails>

</CartonDetails>

</CartonHeader>

</CartonHeaders>

</CWPickIn>

</Message>

Sample Partial Backorder Message

See Pick In Partial Backorders for an overview.

</PickDetails>

</CartonDetails>

</CartonHeader>

</CartonHeaders>

</CWPickIn>

</Message>

Troubleshooting the Pick In API

If the Pick In API fails to process the expected updates, check:

• Is there an error listed at the Work with Pick Invoice Errors Screen?

• Are the background jobs running? See Operating the Background Jobs for more information.

• Did the contents of the message contain the required information? You can check the MQ Log for message contents.

Invalid XML? The Pick In API fails to process the CWPickIn XML Message and returns an Invalid XML Message response if the:

• company exceeds 3 positions or is not a valid company

• pick_control number exceeds 7 positions

• pick_line_nbr in the PickDetail element or the pick_line_nbr in the CartonDetail element exceed 5 positions

• qty_shipped exceeds 5 positions

• carton_nbr exceeds 3 positions

• meter_charges exceed 5.2 positions

• weight exceeds 5.2 positions

• qty_packed exceeds 5 positions

Did a partial backorder message act as a confirmation? The partial backorder message type must indicate the shipped quantity of each pick detail line, or the Pick In API assumes that the entire quantity of the detail line has shipped. Also, if a pick detail line is not included, the Pick In API assumes that the entire quantity of the detail line has shipped. See the Pick In Process Overview for more information.

Can you add additional carton contents after shipment confirmation? If the BILL_ASYNC job has not yet processed the shipment and created the invoice, then if you receive subsequent Pick In messages listing additional cartons for shipment, the system creates Carton Contents records for these cartons. Once the shipment has billed, you can no longer create additional Carton Contents records.

Pick In Setup

User setup: The CWPickIn API uses your default user to log activity in the Order Transaction History table. The secured feature settings of this user ID control the ability of warehouse management system processes, such as the receipt in process, to process various updates; also, the system uses this user ID to track activities such as Order Transaction History made through the warehouse management system integration.

CWPickOut: Typically, you would use the CWPickIn API together with the CWPickOut API in order to facilitate communication between Order Management System and the warehouse management system. For example, the warehouse management system generates pick slips based on the information received in the CWPickOut message; also, when you receive a warehouse backorder confirmation in the CWPickIn message, this generates a new CWPickOut message to the warehouse management system. See Pick Out Processing for more information on processing and setup.

CWPickIn Web Service

The CWPickIn web service allows an external system to post the CWPickIn XML Message directly to Order Management System and receive responses without the need of any queues.

Web service authentication? Use the Working with Web Service Authentication (WWSA) menu option to define a valid user for basic web service authentication.

Using the CWPickIn RESTful web service: You POST inbound CWPickIn messages to the web service’s URL, or endpoint, of the RESTful service. The individual URL for the CWPickIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWPickIn, where server:port identifies the application server where the RESTful service is located and CWPickIn is the name of the web service to call.

Using the CWPickIn SOAP-based web service: The CWPickIn web service’s .wsdl (Web Services Definition Language) file, which is located on your application server, controls the function of the CWPickIn web service. You send the inbound messages to the URL, or endpoint, specified in this wsdl.

You need to embed each inbound message in the SOAP (Simple Object Access Protocol) message tags in order for the CWPickIn web service to receive and process it correctly.

The endpoint specified in the CWPickIn.wsdl file is where you need to post messages. The endpoint uses the following format: http://server:port:8080/CWDirectCPService/services/CWPickIn, where server:port identifies the application server where the wsdl is located and CWPickIn is the name of the web service to call.

Sample CWPickIn message in SOAP envelope: The SOAP-based CWPickIn web service requires that inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.

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

<soapenv:Header/>

<soapenv:Body>

<dom:performAction type="xsd:string"><![CDATA[

</CartonDetails>

</CartonHeader>

</CartonHeaders>

</CWPickIn>

</Message>

]]></dom:performAction>

</soapenv:Body>

</soapenv:Envelope>

CWPickIn XML Message

For more information: See Generic Pick In API (Shipments, Voids, and Backorders).

Attribute Name	Type	Length	Comments
Message One Message element is required.
source	alpha		Informational.
target	alpha		Informational.
type	alpha		CWPICKIN
CWPickIn One CWPickIn element is required.
company	numeric	3	The company number that generated the pick slip. Required.
pick_control	numeric	7	A unique number to identify the pick slip to be confirmed or voided. Must be a valid pick slip whose status makes it eligible for confirmation or void processing. Required.
date_sent	numeric	8	MMDDYYYY format. Informational only for logging and troubleshooting purposes. Optional.
time_sent	numeric	6	HHMMSS format. If the time specified here is invalid, the current time defaults to the Carton Contents and Manifest Upload Audit record. Optional.
transaction_type	alpha	1	Valid values are: B = Pick In Partial Backorders. C = Pick In Shipment Confirmation R = Pick In Void/Keep Reservation; available in release 4.7 or higher of Order Management System U = Pick In Void/Unreserve V = Pick In Void Required. Note: The transaction_type setting is not case-sensitive.
auto_bill	alpha	1	Valid values are: Y = Void the pick slip, generate a new pick slip for the shipped quantities, and automatically bill the new pick slip. N or blank = Void the pick slip, generate a new pick slip for the shipped quantities, but do not automatically bill the new pick slip. Optional. The auto_bill setting is considered only when the transaction_type is B or R. For these transaction types, if the auto_bill setting is anything other than Y, the system does not automatically bill the new pick slip it generates. Note: The auto_bill setting is not case-sensitive.
PickDetail One or more PickDetail elements are required for a transaction_type of B or R, but are not used for any other transaction type. There should be a PickDetail element for each detail line on the pick slip, each indicating the pick line number and quantity shipped.
pick_line_nbr	numeric	5	Identifies the item printed on the pick slip. Must be a valid pick detail line number for the pick slip. Required.
qty_shipped	numeric	5	The quantity that shipped. For transaction_type R, a blank qty_shipped (that is, qty_shipped="") indicates the item fully shipped; otherwise a qty_shipped of 0 or a blank setting indicates that the pick line is fully backordered. The qty_shipped cannot exceed the printed quantity.
svc_card_nbr	alpha	20	The number assigned by the external system to the stored value card item associated with the pick slip. When Order Management System receives a shipment confirmation (transaction_type = C) CWPickIn message that contains a stored value card number, the system creates a record in the Billing SVC Data Queue table and sends the information to billing. See Billing a Stored Value Card for the updates that take place. Note: Using the svc_card_nbr tag in the CWPickIn message allows you to assign a number to a stored value card item using an external system; Order Management System still creates an SVC download trigger to generate an activation request for the card. If your external system assigns a number to the card and also activates and fulfills the card, you must change activation processing with the external system to dismiss any activations that are received for stored value cards that have already been activated by remote fulfillment. Available in: 2.0 (release 2.5 of Order Management System).
CartonHeader Optionally, the message can include one or more CartonHeader elements. The system updates the Order Transaction History, Carton Contents, and Manifest Upload Audit tables only if the transaction_type is B, R, or C. Some of the information included in this element is displayed at the Display Order History Screen and the Display Package Information Screen. If the CWPickIn message does not include the CartonHeader element, then the system defaults some of the information to the tables and screens described below. For example, if the CWPickIn does not include any carton information, then the Display Package Information Screen displays just the actual date and time when the Pick In API processed the updates as the scan date and scan time.
carton_nbr	numeric	3	A unique number to identify each carton used to ship the pick slip, as defined in the Pick Control Label table. Defaults to 1 if not passed. The # of Pick Control Labels (D47) system control value controls the number of label records created for each pick control number; however, you can use Printing Additional Pick Labels (PAPL) to print additional pick control labels. If a label number is passed that does not exist in the Pick Control Label table, the system processes it and creates the corresponding order transaction history and carton contents. The system deletes the label numbers in the Pick Control Label table once the labels are confirmed.
ship_date	numeric	8	MMDDYYYY format. Optional. If a valid date is passed, it updates: • Order Transaction History records (with the exception of the invoice creation record, which is created by billing) • Pack date in the Carton Contents table • Scan date in the Manifest Upload Audit table If no shipment date is passed or the date is invalid (that is, if the month is not from 1 to 12 or the day exceeds the number of days in the stated month), the system uses the current date to update the above tables.
ship_time	numeric	6	HHMMSS format. Optional. If a valid time is passed, it updates: • Pack time in the Carton Contents table • Scan time in the Manifest Upload Audit table If no ship_time is passed or if it is invalid, the current time defaults.
meter_charges	numeric	5.2	The meter charges for the shipment. Optional. This is the Amount displayed at the Display Order History Screen and it also updates the Manifest Upload Audit table.
weight	numeric	5.2	The total weight of the shipment. Optional. Updates the Manifest Upload Audit table.
tracking_nbr	alpha	30	The tracking number for the shipment. Displays on the Display Order History Screen for the shipment record. Creates a link on the Display Package Information Screen to the ship via’s web site for shipment tracking, and is included in the shipment confirmation email. If the tracking number exceeds 30 positions, it is truncated. Optional.
ship_via	numeric	2	Identifies the shipper. Validated against the Ship Via table. Optional, but if the message includes a tracking number but not a ship via code, the tracking link at the Display Package Information Screen will not work.
packer	alpha	10	The user ID of the person who packed the shipment. This information is not validated against any table. Optional and informational only.
CartonDetail One or more CartonDetail elements are optional and the quantities are not validated against the pick slip record. The system updates the Carton Contents table, available for review at the Display Package Information Screen, if the transaction_type is B, R, or C.
carton_line_nbr	numeric	5	Identifies the line number on the carton. Informational only; not validated or stored in any table. Optional.
pick_line_nbr	numeric	5	Indicates the item shipped in the carton. Must be a valid pick line number shipping on the pick slip. Used only for B or C transaction types. Required to track carton contents.
qty_packed	numeric	5	The quantity of the item packed in the carton. Not validated against in the quantity of the item shipping on the pick slip. Used only for B or C transaction types.

Working with PO Receipt Errors (WPRE)

Contents

SCVs

Search

Glossary

Reports

Solutions

XML

Index

Working with Pick Invoice Errors (WPIE)

WH13_04 OROMS 17.0 2018 OTN