Purchase Order Receipt In API

Purchase Order Receipt In API

Purpose: Use the Purchase Order Receipt In API to process PO receipts received from another system, such as a warehouse management system. The Purchase Order Receipt In API provides details on whether the warehouse management system was successful in receiving the requested quantity of each detail line on the PO. This API uses the PO Receipt In XML Message (CWReceiptIn) to process PO receipts from another system.

Note: This API is part of the integration with a warehouse management system, and enables you to receive a PO after using the Generic Outbound Purchase Order API to send POs to the warehouse management system. However, you do not need to use the Generic Outbound Purchase Order API to use the Purchase Order Receipt In API.

Transactions: The PO Receipt In API can process the receipt of one PO line into a single location. You can receive the entire PO line, or receive a partial quantity of the PO line. If you wish to receive the PO line into more than one location, you must send a separate PO Receipt In XML Message (CWReceiptIn) for each location.

Example: You wish to receive the following PO as indicated:

PO line #	Qty	Receipt Whs	Receipt Location	Results
1	50	1	A010101	In this situation, you will need to send 3 separate CWReceiptIn messages: • one message for the receipt of 50 units on PO line 1 to warehouse 1, location A010101. • one message for the receipt of 150 units on PO line 1 to warehouse 1, location B010101. • one message for the receipt of 500 units on PO line 2 to warehouse 1, location A020202.
1	150	1	B010101
2	500	1	A020202

PO Receipt In information flow: This flowchart explains how PO receipt information is uploaded into Order Management System.

In this chapter:

• Purchase Order Receipt In Process

- Determining the Purchase Order to Receive

- Determining the Item and SKU to Receive

- Determining the Quantity to Receive

- Determining the Receipt Warehouse and Location

- Successful PO Receipts

- Failed PO Receipts

• Options Not Supported in the PO Receipt In Process

• Troubleshooting the Purchase Order Receipt In API

• Order Management System Setup for the Purchase Order Receipt In API

• Purchase Order Receipt In: Sample XML Messages

• PO Receipt In XML Message (CWReceiptIn)

• PO Receipt Errors

For more information: See Working with PO Receipt Errors (WPRE).

Purchase Order Receipt In Process

1.	The warehouse management system receives a partial or full receipt of a PO or PO line.
2.	For each PO line received, the warehouse management system sends a PO Receipt In XML Message (CWReceiptIn) to Order Management System via the CWReceiptIn Web Service. Note: A separate PO Receipt In XML Message (CWReceiptIn) must be sent to Order Management System for each PO line received.
3.	The CWReceiptIn Web Service determines if the PO Receipt In XML Message (CWReceiptIn) is a valid XML message; see Invalid XML?.
4.	If the PO Receipt In XML Message (CWReceiptIn) is a valid XML message, Order Management System receives the PO Receipt In XML Message (CWReceiptIn) from the warehouse management system, and: • Determines the PO to receive; see Determining the Purchase Order to Receive. • Determines the item/SKU to receive; see Determining the Item and SKU to Receive. • Determines the quantity of the item/SKU to receive; see Determining the Quantity to Receive. • Determines the location and warehouse where the item/SKU should be placed; see Determining the Receipt Warehouse and Location.
5.	If Order Management System successfully processes the PO Receipt In XML Message (CWReceiptIn), the system updates the PO and the inventory information in the location and warehouse where the item/SKU was placed. See Successful PO Receipts. If Order Management System cannot successfully process the PO Receipt In XML Message (CWReceiptIn), the system places the message in an error status. See Failed PO Receipts.

Determining the Purchase Order to Receive

Order Management System uses the company and po_nbr in the PO Receipt In XML Message (CWReceiptIn) to determine the purchase order to receive.

Validation: The system performs the following validation for the company and po_nbr in the PO Receipt In XML Message (CWReceiptIn).

In order to receive a PO line on a PO, the PO must be in an Open or Docked status. In addition, the PO line specified must also be in an Open status.

You cannot receive a PO through the Purchase Order Receipt In API that is in a Cancelled, Held, Suspended, or Closed status.

Errors: See General PO Receipt In Errors for a list of general errors that can occur when processing the PO Receipt In XML Message (CWReceiptIn).

Determining the Item and SKU to Receive

Order Management System uses the following hierarchy to determine the item and SKU to receive on the PO.

1. PO Line Sequence Number

2. Item and SKU

3. Vendor Item

4. Short SKU

5. UPC Type and UPC Code

6. Retail Reference Number

See Item to Receive Hierarchy for more information on the validation that occurs when determining the item and SKU to receive on the PO.

Note: In order to receive a full or partial PO line, the PO line must be in an Open status.

Errors: See Errors Related to Resolving the Item and SKU for a list of errors that can occur when the system tries to determine the item and SKU to receive on the PO.

If More than One PO Line Matches the Item to Receive

If you do not use the PO Line Sequence Number to identify the item and SKU to receive on the PO, it is possible that the system will find more than one PO line that matches the item to receive. In this situation, the system receives against the first open PO line in numeric order whose Quantity due is equal to or greater than the quantity passed in the PO Receipt In XML Message (CWReceiptIn).

If the Quantity due for all of the matching open PO lines is less than the quantity passed in the PO Receipt In XML Message (CWReceiptIn), the system places the message in an error status. The system will not receive across PO lines.

Example: The system matches the following PO lines to the item and SKU to receive.

PO line #	Qty Due	Receipt Qty	Results
1	100	115	The system uses PO line 2 as the PO line to receive since it is the first PO line in numeric order whose Quantity due is greater than the quantity passed in the PO Receipt In XML Message (CWReceiptIn).
2	125
3	150

See Determining the Quantity to Receive for more information on how the system determines the quantity to receive.

Receiving a Non-Inventory Item that Does Not Exist in the Item Table

The system allows you to create a PO line for an item that does not exist in the Item table. For example, you might wish to use this feature for items that you do not stock in inventory, such as cleaning or office supplies.

In order to receive a non-inventory item that does not exist in the Item table:

• Your default user must have authority to the Receipt of Non-inventory Item (A19) secured feature. Note: If you wish to review the non-inventory receipt before processing it, set the default user’s authority to the Receipt of Non-inventory Item (A19) secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review: Not Auth to Non-inventory Item. In order to process the non-inventory receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Receipt of Non-inventory Item (A19) secured feature.

• You must use the po_line_seq_nbr to identify the PO line to receive; see Item to Receive Hierarchy.

• You must pass Y in the non_inv_item tag to indicate the item is a non-inventory item that does not exist in the Item table. The system validates that the Inventory item field for the PO line in the PO Detail table is set to N (indicating the item does not exist in the Item table).

non_inv_item	Inventory item field	Results
Y	N	The system considers the item a non-inventory item and continues processing the PO receipt; see Determining the Quantity to Receive.
Y	Y	The system cannot determine if the item is a non-inventory item since the non_inv_item flag in the CWReceiptIn message contradicts the Inventory item setting for the PO line. The system places the PO Receipt In XML Message (CWReceiptIn) in an error status: Invalid Non-inventory Item
N or blank	N	The system cannot determine if the item is a non-inventory item since the non_inv_item flag in the CWReceiptIn message contradicts the Inventory item setting for the PO line. The system places the PO Receipt In XML Message (CWReceiptIn) in an error status: Invalid or Missing Non-inventory Flag.
N or blank	Y	The system considers the item an inventory item and continues processing the PO receipt; see Determining the Quantity to Receive.

• If you define a location, the system ignores it since the item is a non-inventory item that cannot be received into inventory.

Updates: When you receive a non-inventory item that does not exist in the Item table, the system:

• Updates the PO line:

- Decreases the Quantity due by the receipt quantity.

- Increases the Quantity received by the receipt quantity.

- Updates the status of the PO line to Closed if the entire quantity on the line has been received.

• Updates the status of the PO to Closed if there is no more merchandise to receive.

• Does not create an inventory transaction history record since the item on the PO line does not exist in the Item table.

• Does not update inventory in any warehouse or location since the item was not received into inventory.

Item to Receive Hierarchy

Order Management System uses the following hierarchy to determine the item and SKU to receive on the PO.

1.	PO Line Sequence Number Use po_line_seq_nbr to identify the PO line to receive. If a po_line_seq_nbr is specified, the system ignores the values defined in the item, sku, vendor_item, short_sku, upc_type, upc_code, and retail_ref_nbr tags. Validation: The system validates the po_line_seq_nbr against the Seq # field in the PO Detail table for the specified po_nbr. • If the po_line_seq_nbr does not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. • If the po_line_seq_nbr exists in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. • If the po_line_seq_nbr exists in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.
2.	Item and SKU Use the item and sku to identify the PO line to receive. The sku is required only if the item contains SKUs. The system only reviews the item and SKU specified if the po_line_seq_nbr is blank. If an item and sku are specified, the system ignores the values defined in the vendor_item, short_sku, upc_type, upc_code, and retail_ref_nbr tags. Validation: The system validates the item and sku (if the item contains SKUs) against the ITM Number and SKU Code in the PO Detail table for the specified po_nbr. • If the item and sku do not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. • If the item and sku exist in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. • If the item and sku exist in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.
3.	Vendor Item Use the vendor_item to identify the PO line to receive. The system only reviews the vendor item specified if the po_line_seq_nbr, item and sku are blank. In addition, the system ignores the values defined in the short_sku, upc_type, upc_code, and retail_ref_nbr tags. Validation: The system performs the following validation when you use the vendor_item to identify the PO line to receive. If the vendor item is defined on the PO Line: Validates the vendor_item against the Item field in the PO Detail table for the specified po_nbr. • If the vendor_item exists in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. • If the vendor_item exists in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive. If the vendor item is not defined on the PO Line: • Validates the vendor_item against the Item field in the Vendor Item table. - If the vendor_item does not exist, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the vendor_item exists, the system determines the item and sku for which the vendor item is defined. • Validates the item and SKU associated with the vendor item against the ITM Number and SKU Code in the PO Detail table for the specified po_nbr. - If the item and SKU do not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.
4.	Short SKU Use the short_sku to identify the PO line to receive. The system only reviews the short SKU code specified if the po_line_seq_nbr, item, sku, and vendor_item are blank. If a short_sku is specified, the system ignores the values defined in the upc_type, upc_code, and retail_ref_nbr. Validation: The system performs the following validation when you use the short_sku to identify the PO line to receive. • Validates the short_sku against the Short SKU field in the SKU table. - If the short_sku does not exist, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the short_sku exists, the system determines the item and sku for which the short SKU code is defined. • Validates the item and SKU code associated with the short SKU code against the ITM Number and SKU Code in the PO Detail table for the specified po_nbr. - If the item and SKU do not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.
5.	UPC Type and UPC Code Use the upc_type and upc_code to identify the PO line to receive. The system only reviews the UPC type and UPC code specified if the po_line_seq_nbr, item, sku, vendor_item, and short_sku are blank. You can pass the upc_code without the upc_type; however, if you pass a upc_type, you must also pass a upc_code. Note: Include any leading zeros. For example, if the UPC code is 06012011, pass 06012011 and not 6012011. If a upc_type and upc_code are specified, the system ignores the value defined in the retail_ref_nbr tag. Valid values for UPC type are: • E13 = EAN-13 • E8 = EAN-8 • UA = UPC-A • UE = UPC-E Validation: The system performs the following validation when you use the upc_type and upc_code to identify the PO line to receive. • Validates the upc_type and upc_code combination against the UPC type and UPC fields in the Item UPC table. If a upc_code is defined without a upc_type, or the upc_type is an invalid value, the system validates the upc_code only. - If the upc_code does not exist, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the upc_type and upc_code combination does not exist, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the upc_type and upc_code combination exists, the system determines the item and SKU for which the UPC code is defined. • Validates the item and SKU code associated with the UPC code against the ITM Number and SKU Code in the PO Detail table for the specified po_nbr. - If the item and SKU do not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.
6.	Retail Reference Number Use the retail_ref_nbr to identify the PO line to receive. The system only reviews the retail reference number specified if the po_line_seq_nbr, item, sku, vendor_item, short_sku, upc_type, and upc_code are blank. Validation: The system performs the following validation when you use the retail_ref_nbr to identify the PO line to receive. • Validates the retail_ref_nbr against the Retail reference # field in the SKU table. - If the retail_ref_nbr does not exist, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the retail_ref_nbr exists, the system determines the item and SKU for which the retail reference number is defined. • Validates the item and SKU associated with the retail reference number against the ITM Number and SKU Code in the PO Detail table for the specified po_nbr. - If the item and SKU do not exist in the PO Detail table for the specified po_nbr, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, but the PO line is not in an Open status, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status. - If the item and SKU exist in the PO Detail table for the specified po_nbr, and the PO line is in an Open status, the system determines the quantity to receive; see Determining the Quantity to Receive.

Determining the Quantity to Receive

Order Management System uses the quantity in the PO Receipt In XML Message (CWReceiptIn) to determine the quantity of the PO line to receive.

The quantity must be a positive number greater than zero, without decimals. If you include a decimal in the quantity, such as 12.99, the system ignores the decimal; for example, 12.99 passes as 12.

Errors: See Errors Related to the Receipt Quantity for a list of errors that can occur when the system tries to determine the quantity to receive on the PO line.

Over Receiving the PO Line Order Quantity

The Over Receipt % (A61) system control value allows you to receive more than the quantity ordered on the PO line, up to the percentage limit defined in the system control value. This allows you to receive merchandise that the vendor over-ships. For a partial receipt, the system compares the Quantity received to date against the Quantity ordered on the PO line.

When the system evaluates the over receipt %: The system evaluates the Over Receipt % (A61) system control value only if you identify the item and SKU to receive using the po_line_seq_nbr.

Note: If you identify the item and SKU to receive using any other item indicator, the system does not allow you to over receive the PO line by any quantity. When the system processes the over receipt, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status: PO Ln# Could Not Be Identified.

See Determining the Item and SKU to Receive for more information on the Item to Receive Hierarchy and see If More than One PO Line Matches the Item to Receive for more information on the logic the system performs when more than one PO line matches the item to receive.

Secured feature: The Override Tolerance (A18) secured feature allows you to override the percentage defined in the Over Receipt % (A61) system control value and receive any amount greater than the quantity ordered on the PO line.

Note: If you wish to review the over receipt before processing it, set your default user’s authority to the Override Tolerance (A18) secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the over receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override Tolerance (A18) secured feature.

Over Receipt Examples

In the examples below, the Over Receipt % (A61) system control value is set to 10%.

Order Qty	Receipt Qty	Results
100	100	The system receives the 100 units into inventory since the quantity received matches the quantity ordered.
100	110	Using PO Line Seq # as the Item Identifier The system receives the 110 units into inventory since the quantity received falls within the Over Receipt % (A61). Using Another Item Identifier The system places the PO Receipt In XML Message (CWReceiptIn) in an error status: PO Ln# Could Not Be Identified. You can correct the error by either: • Changing the quantity to be equal to or less than the ordered quantity on the PO line. • Changing the item identifier to the PO line sequence number.
100	115	Using PO Line Seq # as the Item Identifier Because the receipt quantity is greater than the Over Receipt % (A61), the system receives the 115 units only if the Default User has authority to the Override Tolerance (A18) secured feature. If the Default User does not have authority to the Override Tolerance (A18) secured feature, the system places the PO Receipt In XML Message (CWReceiptIn) in an error status: Receipt Qty Exceeds Order Qty. The user correcting the error must have authority to the Override Tolerance (A18) secured feature; otherwise, in order to process the receipt the user must change the quantity to be equal to or less than the over receipt quantity allowed by the Over Receipt % (A61) system control value. Using Another Item Identifier The system places the PO Receipt In XML Message (CWReceiptIn) in an error status: PO Ln# Could Not Be Identified. You can correct the error by either: • Changing the quantity to be equal to or less than the ordered quantity on the PO line. • Changing the item identifier to the PO line sequence number. The user correcting the error must have authority to the Override Tolerance (A18) secured feature; otherwise, in order to process the receipt the user must change the quantity to be equal to or less than the over receipt quantity allowed by the Over Receipt % (A61) system control value.

Under Receiving the PO Line Order Quantity

The Under Receipt % (A62) system control value allows you to close a PO line when most of the merchandise has been received, if the quantity received is within a user-defined tolerance percentage. This allows you to close a PO line automatically if the vendor under-ships.

Example: If the Under Receipt % (A62) system control value is 10% and you receive 90% of the quantity ordered on the PO line, the system updates the status of the PO line to Closed.

Under Receipt Examples

In the examples below, the Under Receipt % (A62) system control value is set to 10%.

Order Qty	Receipt Qty	Results
100	100	The system updates the status of the PO line to closed when it receives the 100 units into inventory because the quantity received matches the quantity ordered.
100	90	Using PO Line Seq # as the Item Identifier The system updates the status of the PO line to closed when it receives the 90 units into inventory because the quantity received falls within the Under Receipt % (A62). Using Another Item Identifier The system receives the 90 units into inventory, but does not update the status of the PO line to closed.
100	85	Using PO Line Seq # as the Item Identifier The system receives the 85 units into inventory, but does not update the status of the PO line to closed since the receipt quantity is less than the allowed Under Receipt % (A62). Using Another Item Identifier The system receives the 85 units into inventory, but does not update the status of the PO line to closed.

Determining the Receipt Warehouse and Location

Receipt warehouse hierarchy: Order Management System uses the following hierarchy to determine the receipt warehouse for a PO passed through the Purchase Order Receipt In API.

1. Use the warehouse defined in the PO Receipt In XML Message (CWReceiptIn).

2. Use the warehouse defined on the PO.

Determining the receipt location: The settings of the Default Primary Location - Suspense Placement and PO Receipts (C08) and Default Primary Location from an Item Warehouse (G06) system control values determine the receipt location for a PO passed through the Purchase Order Receipt In API. See Determining the Receipt Location.

Validation: The system performs the following validation on the receipt warehouse and location.

• If passed, validates the whs in the CWReceiptIn message against the Warehouse field in the Warehouse table: Invalid Warehouse.

• If passed, validates that the location in the CWReceiptIn message is a valid location for the specified warehouse in the Location table: Invalid Location for Warehouse.

• Checks the settings of the Allow Multiple Primary Item Locations (D12) and Update Primary Primary Location for Item During Receiving (I35) system control values to determine how to update the item location during receiving; see Updating Item Locations During Receiving.

See Errors Related to the Receipt Location and Warehouse for a list of errors that can occur when the system tries to determine the receipt warehouse and location.

Non-inventory items: If you define a whs and/or location in the PO Receipt In XML Message (CWReceiptIn) for a non-inventory item that does not exist in the Item table, the system ignores it since the item is a non-inventory item that cannot be received into inventory. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table.

Drop ship items: If the item is a drop ship item, the system treats the item as a non-inventory item and does not require a receipt warehouse and location.

Updating Item Locations During Receiving

The following system control values control how the system updates item locations when it processes a PO Receipt received through the Purchase Order Receipt In API.

• Allow Multiple Primary Item Locations (D12):

- If set to ALLOW, the system allows you to receive an item into more than one primary location.

- If set to NOT ALLOW or CONFIRM, the system does not allow you to receive the item into more than one primary location.

Note: Regardless of the setting of this system control value, the system allows you to receive the item into a non-primary location.

• Update Primary Primary Location for Item During Receiving (I35):

- If selected, the system updates the item’s primary primary location with the receipt location, based on whether a primary primary location is already defined and whether an on-hand quantity already exists for the primary primary location.

- If unselected, the system does not update the item’s primary primary location with the receipt location.

The table below explains how the system updates item locations during receiving, based on the settings of the Allow Multiple Primary Item Locations (D12) and Update Primary Primary Location for Item During Receiving (I35) system control values.

D12 SCV	I35 SCV	Results
NOT ALLOW	unselected	The system prevents you from receiving the item into more than one primary location. If the receipt location is a primary location other than the primary location already defined for the item, the PO Receipt In XML Message (CWReceiptIn) is placed in an error status: Mult Primary Loc Not Allowed.
CONFIRM	unselected
ALLOW	unselected	The system allows you to receive the item into a primary location other than the primary location already defined for the item.
NOT ALLOW	selected	The system prevents you from receiving the item into a primary location other than the primary location already defined for the item. If the receipt location is a primary location other than the primary location defined for the item, the PO Receipt In XML Message (CWReceiptIn) is placed in an error status: Mult Primary Loc Not Allowed. However, if a primary location is not defined for the item, the system allows you to receive the item and updates the item’s primary primary location with the receipt location.
CONFIRM	selected
ALLOW	selected	The system allows you to receive the item into a primary location other than the primary location already defined for the item. In addition: • If a primary location is not defined for the item, the system updates the item’s primary primary location with the receipt location. • If a primary primary location exists, but there is no on-hand quantity in the location, the system updates the item’s primary primary with the receipt location and deletes the previous primary primary item location. • If a primary primary location exists and the on-hand quantity in the location is greater than zero, the system retains the item’s primary primary location.

Determining the Receipt Location

The table below explains which warehouse and location the system chooses as the receipt warehouse and location, based on the settings of the Default Primary Location - Suspense Placement and PO Receipts (C08) and Default Primary Location from an Item Warehouse (G06) system control values.

C08 SCV	G06 SCV	Results
A warehouse and location are defined in the CWReceiptIn message The system uses the warehouse in the message as the receipt warehouse.
unselected or selected	unselected or selected	The system receives the merchandise into the warehouse and location defined in the PO Receipt In XML Message (CWReceiptIn).
A warehouse is defined in the CWReceiptIn message, but a location is not defined The system uses the warehouse in the message as the receipt warehouse.
unselected	unselected	The system cannot determine the receipt location and places the CWReceiptIn message in an error status: Missing Location.
unselected or selected	selected	• If a primary item location exists for the warehouse in the message, the system receives the merchandise into the first primary item location, in alphanumeric order, in the warehouse defined in the CWReceiptIn message. • If a primary item location does not exist for the warehouse in the message, the system places the message in an error status: Missing Location.
selected	unselected	• If the warehouse defined in the CWReceiptIn message contains the item’s primary primary location, the system receives the merchandise into the warehouse defined in the CWReceiptIn message and the item’s primary primary location. • If a location with the same name as the item’s primary primary exists for the warehouse in the message, the system receives the merchandise into the warehouse defined in the CWReceiptIn message and the location with the same name as the item’s primary primary. • If the item’s primary primary location, or a location with the same name as the item’s primary primary, does not exist for the warehouse in the CWReceiptIn message, the system places the CWReceiptIn message in an error status: Invalid Location for Warehouse.
A warehouse and location are not defined in the CWReceiptIn message The system uses the warehouse on the PO as the receipt warehouse.
unselected	unselected	The system places the CWReceiptIn message in an error status: Missing Location.
unselected or selected	selected	• If a primary item location exists for the warehouse on the PO, the system receives the merchandise into the first primary item location, in alphanumeric order, in the warehouse defined on the PO. • If a primary item location does not exist for the warehouse on the PO, the system places the CWReceiptIn message in an error status: Missing Location.
selected	unselected	• If the warehouse on the PO contains the item’s primary primary location, the system receives the merchandise into the warehouse on the PO and the item’s primary primary location. • If a location with the same name as the item’s primary primary exists for the warehouse on the PO, the system receives the merchandise into the warehouse on the PO and the location with the same name as the item’s primary primary. • If the item’s primary primary location, or a location with the same name as the item’s primary primary, is not a valid location in the warehouse on the PO, the system places the CWReceiptIn message in an error status: Invalid Location for Warehouse.
A location is defined in the CWReceiptIn message, but a warehouse is not defined The system uses the warehouse on the PO as the receipt warehouse.
unselected or selected	selected	The system ignores the location in the message and: • If a primary item location exists for the warehouse on the PO, the system receives the merchandise into the first primary item location, in alphanumeric order, in the warehouse on the PO. • If a primary item location does not exist for the warehouse on the PO, the system places the CWReceiptIn message in an error status: Missing Location.
unselected or selected	unselected	• If the location in the message is a valid location in the warehouse on the PO, the system receives the merchandise into the warehouse defined on the PO and the location specified in the message. • If the location in the message is not a valid location in the warehouse on the PO, the system places the CWReceiptIn message in an error status: Invalid Location for Warehouse.

Receipt Warehouse and Location Examples

In the examples below, the item on the PO line to receive has the following item locations:

Item Whs	Item Location	Location Type
1	PRIMARY A1 B1	this is the item’s primary primary location primary secondary
2	PRIMARY A1 B1	primary primary secondary
3	A010101 A020202 B010101	primary primary secondary

Example 1:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
1, 2, or 3	3 / B010101	unselected or selected	unselected or selected

Receipt warehouse and location: Warehouse 3 and location B010101.

Example 2:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
1, 2, or 3	3 / no location	unselected	unselected

Receipt warehouse and location: Because the Default Primary Location - Suspense Placement and PO Receipts (C08) and Default Primary Location from an Item Warehouse (G06) system control values are both set to unselected, the system cannot determine the receipt location and places the CWReceiptIn message in an error status: Missing Location.

Example 3:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	3 / no location	unselected or selected	selected

Receipt warehouse and location: Warehouse 3 and location A010101.

Example 4:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	3 / no location	selected	unselected

Receipt warehouse and location: Since primary primary location PRIMARY for the item does not exist for warehouse 3 specified in the CWReceiptIn message, the system places the CWReceiptIn message in an error status: Invalid Location for Warehouse.

Example 5:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	1 / no location	selected	unselected

Receipt warehouse and location: Warehouse 1 and location PRIMARY.

Example 6:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
1, 2, or 3	no whs or location	unselected	unselected

Example 7:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	no whs or location	selected	unselected

Receipt warehouse and location: Warehouse 2 and location PRIMARY.

Example 8:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	no whs or location	unselected or selected	selected

Receipt warehouse and location: Warehouse 2 and location A1.

Example 9:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	no whs / B010101	unselected or selected	unselected

Receipt warehouse and location: Since location B010101 in the CWReceiptIn message is not a valid location for warehouse 2 specified on the PO, the system places the CWReceiptIn message in an error status: Invalid Location for Warehouse.

Example 10:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
3	no whs / B010101	unselected or selected	unselected

Receipt warehouse and location: Warehouse 3 and location B010101.

Example 11:

Whs on PO	Whs / Location in CWReceiptIn Msg	Default Primary Primary Loc (C08)	Default Primary Loc in Item Whs (G06)
2	no whs / B010101	unselected or selected	selected

Receipt warehouse and location: Warehouse 2 and location A1.

Successful PO Receipts

Order Management System performs the following updates when it processes a PO Receipt In XML Message (CWReceiptIn) that includes valid data.

Receiving into Inventory: If you receive merchandise directly into inventory, the system updates inventory immediately, and the merchandise is available to be reserved and picked.

The system:

• Updates the PO line:

- Decreases the Quantity due by the receipt quantity.

- Increases the Quantity received by the receipt quantity.

- Updates the status of the PO line to Closed if the entire quantity on the line has been received.

• Updates the status of the PO to Closed if there is no more merchandise to receive.

• Creates an inventory transaction history record for the PO Receipt transaction.

• Increases the on-hand quantity in the receipt item warehouse and item location.

• Decreases the on-order quantity for the warehouse on the PO.

• Recalculates the average cost.

• Performs vendor item analysis.

Non-inventory items: See Receiving a Non-Inventory Item that Does Not Exist in the Item Table for more information on the updates the system performs when it receives a non-inventory item that does not exist in the Item table.

PO download triggers: The setting of the Create Generic PO Download Trigger for PO Receipt (K27) system control value determines whether the system creates a purchase order download (POH) trigger when a purchase order line is received through the Purchase Order Receipt In API.

Receiving into a staging warehouse: When you receive into a staging warehouse, the same updates take place at receiving as when you receive into inventory. However, you normally define the staging warehouse to be non-allocatable and non-viewable in Order Entry, and define each location to be non-pickable; the result is that the inventory is not generally available or visible on the system until you place it in your main warehouse.

Receiving into a pending warehouse: When you receive merchandise into a pending warehouse, the system performs the following updates at receiving time:

• Updates the PO line:

- Decreases the Quantity due by the receipt quantity.

- Increases the Quantity received by the receipt quantity.

- Updates the status of the PO line to Closed if the entire quantity on the line has been received.

• Updates the status of the PO to Closed if there is no more merchandise to receive.

• Creates an inventory transaction history record for the PO Receipt transaction in the pending warehouse.

• Decreases the on-order quantity for the item in the “final destination” warehouse.

• Creates a pending putaway detail record. If a pending putaway detail record already exists for the PO and item/SKU, the system adds the receipt quantity to the existing pending putaway detail record. The pending putaway detail record indicates:

- The quantity of the item in the pending warehouse for this receipt. The on hand quantity for the item at the item warehouse level indicates the total pending putaway quantity for the item.

- The “final destination” warehouse where the inventory will be placed.

- The expected due date of the inventory; this due date is displayed in order entry, order maintenance, standard or streamlined order inquiry, inventory inquiry, and item availability for the “final destination” warehouse.

• Creates a PO layering record for the “final destination” warehouse.

The following updates do not occur when merchandise is received into a pending warehouse.

• The on-hand quantity for the item in the "final destination" warehouse is not changed.

• The costing calculation is not performed.

• Vendor Item analysis is not performed

These updates occur when the merchandise is transferred from the pending putaway warehouse to the "final destination" warehouse.

See Pending Putaway Overview for an overview of the updates the system performs when you place inventory into a pending warehouse.

Failed PO Receipts

If the PO Receipt In XML Message (CWReceiptIn) received from the warehouse management system includes invalid or missing data, Order Management System does not process the PO Receipt and does not perform any updates to the PO, item warehouse, or item location.

In addition, the system creates a record in the PO Receipt Error table. You can review, correct, and reprocess PO receipt errors in the Working with PO Receipt Errors (WPRE) menu option. See Failed PO Receipts for a list of errors.

Note: If you do not see the failed PO Receipt in the Working with PO Receipt Errors (WPRE) menu option, it could be that the error occurred before the PO Receipt was received into Order Management System, such as an invalid XML error. See Troubleshooting the Purchase Order Receipt In API.

Options Not Supported in the PO Receipt In Process

The following functions are not supported through the Purchase Order Receipt In API.

• Receiving into suspense (Allow Receipt to Suspense (A59)).

• Creating a purchase order detail line during receipts.

• Defining additional charges during PO receipts (Allow Additional Costs to P/O Receipts (A60)).

Troubleshooting the Purchase Order Receipt In API

Purpose: If the Purchase Order Receipt In API fails to process the expected updates, check the following.

• Has all of the setup required for the Purchase Order Receipt In API been completed? See Order Management System Setup for the Purchase Order Receipt In API to check your settings.

• Is there an error listed at the Work with PO Receipt Errors Screen? See PO Receipt Errors for a list of errors.

• 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.

The system writes an OK message similar to the following in the Message log, indicating the XML message was valid:

10:20:04,071 INFO MQ - Out Message:<Message>OK</Message>

Invalid XML?

If the PO Receipt In XML Message (CWReceiptIn) is missing data or contains invalid data, the system does not display the error in the Working with PO Receipt Errors (WPRE) menu option.

Invalid XML response: The Purchase Order Receipt In API fails to process the PO Receipt In XML Message (CWReceiptIn) and returns an Invalid XML Message response in the following scenarios.

• company exceeds 3 positions

• po_nbr exceeds 7 positions

• po_line_seq_nbr exceeds 5 positions

• receipt_time exceeds 6 positions

• quantity exceeds 7 positions

• quantity contains a negative quantity, such as 12-

• short_sku exceeds 7 positions

• upc_code exceeds 14 positions

• whs exceeds 3 positions

The system writes an invalid XML message similar to the following in the Message log, indicating why the message is invalid:

<Message>Invalid XML Message: ERROR: Attribute poNbr value too long. Max length = 7.</Message>

Exception response: The Purchase Order Receipt In API fails to process the PO Receipt In XML Message (CWReceiptIn) and returns an Exception XML Message response in the following scenarios:

• cost exceeds 11 positions with a 4-place decimal

• sku exceeds 14 positions

• retail_ref_nbr exceeds 15 positions

The system writes an exception XML message similar to the following in the Message log, indicating an error occurred:

<Message>Invalid XML Message: java.lang.Exception: javax.transaction.RollbackException: [com.arjuna.ats.internal.jta.transaction.arjunacore.commitwhenaborted] [com.arjuna.ats.internal.jta.transaction.arjunacore.commitwhenaborted] Can't commit because the transaction is in aborted state</Message>

Order Management System Setup for the Purchase Order Receipt In API

Before you can process Purchase Order Receipt In messages, you must perform the necessary setup.

Information requiring setup includes:

• Default User

• Outbound Purchase Order API

• CWReceiptIn Web Service

• System Control Values Related to the Purchase Order Receipt In API

• Menu Options Related to the Purchase Order Receipt In API

• Secured Features Related to the Purchase Order Receipt In API

Note: Review this information if you are having trouble processing PO receipts received through the Purchase Order Receipt In API to help you troubleshoot the problem.

Default User

The Purchase Order Receipt In API uses your default user as the user ID whose secured feature authority controls the ability to process PO receipts received from an outside system.

• Override Tolerance (A18): Controls whether the user has authority to override the percentage defined in the Over Receipt % (A61) system control value and receive any amount greater than the quantity ordered on the PO line.

Note: If you wish to review the over receipt before processing it, set the default user’s authority to this secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the over receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override Tolerance (A18) secured feature.

• Override PO Cost (A17): Controls whether the user has authority to override the cost defined for the PO line.

Note: If you wish to review the override cost before processing it, set the default user’s authority to this secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process an is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the override code, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override PO Cost (A17) secured feature.

• Receipt of Non-inventory Item (A19): Controls whether the user has authority to receive a non-inventory item that does not exist in the Item table.

Note: If you wish to review the non-inventory receipt before processing it, set the default user’s authority to this secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the non-inventory receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Receipt of Non-inventory Item (A19) secured feature. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table for more information.

Outbound Purchase Order API

Typically, you would use the Purchase Order Receipt In API together with the Outbound Purchase Order API in order to facilitate communication between Order Management System and the warehouse management system. For example, the warehouse management system generates POs based on the information in the PO Download XML Message (CWPurchaseOrderOut) received from Order Management System; when the warehouse management system receives the items specified on the PO, the warehouse management system sends this information to Order Management System in the PO Receipt In XML Message (CWReceiptIn). See Generic Outbound Purchase Order API for more information on the processing and setup for the Outbound Purchase Order API.

CWReceiptIn Web Service

The CWReceiptIn web service allows an external system to post the PO Receipt In XML Message (CWReceiptIn) 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. If you use Oracle Identity Cloud Service for password authentication, in addition to creating the web service authentication user in Work with Web Service Authentication (WWSA), you must also create a corresponding user profile in Oracle Identity Cloud Service and assign the user to the corresponding web service role defined for the Order Management application.

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

Using the CWReceiptIn SOAP-based web service: The CWReceiptIn web service’s .wsdl (Web Services Definition Language) file, which is located on your application server, controls the function of the CWReceiptIn 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 CWReceiptIn web service to receive and process it correctly.

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

Sample CWReceiptIn message in SOAP envelope: The SOAP-based CWReceiptIn 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[

</Message>

]]></dom:performAction>

</soapenv:Body>

</soapenv:Envelope>

System Control Values Related to the Purchase Order Receipt In API

System Control Value	Description
Over Receipt % (A61)	Enter the percentage amount over the quantity ordered that may be received through PO Receiving. This field is 6 positions with a 2-place decimal. For example, if this value is 10% and you ordered 100 units, but the vendor shipped 120 units, you will receive a message in P/O Receiving indicating that the quantity to be received is over the tolerance limit. With the appropriate authority (defined in the Override Tolerance (A18) secured feature), you can override this tolerance limit. This percentage is applied to each line of a PO and is compared against the original order quantity on the line. For a partial shipment, the system compares the total quantity received-to-date against the original order quantity.
Under Receipt % (A62)	Enter the percentage at which a PO may be under-received, but still be considered complete and closed. This field is 6 positions with a 2-place decimal. For example, if this value is 10% and you originally ordered 100 units and have received 95% of the inventory, the PO will be closed because the total received-to-date is within the tolerance range for Receiving. This percentage is applied to each line of a PO and is compared against the original order quantity on the line. Enter zero (0) if you do not want POs closed automatically until each line has been received completely. The system does allow you to close a PO in P/O Receipts if the tolerance is 0 or if you have received everything, but you are still under the tolerance limit.
Vendor Discount % to Costing at Receiving (D76)	Select this field if you want the discount defined in the Terms field in Working with Vendors (WVEN) applied to the cost of an item during PO Receiving. You can review the discounted cost for an item in Display Inventory Transaction History (DITH).
Include PO Estimated Charges in Receipt Cost Calculation (G29)	Select this field if you want the system to include PO estimated additional charges in the receipt cost of an item when a PO is received, fully or partially.
Allow Multiple Primary Item Locations (D12)	Defines whether the system allows an item to have more than one primary item location. See Updating Item Locations During Receiving for more information.
Update Primary Primary Location for Item During Receiving (I35)	Select this field if you want to update the “primary primary” location for an item when receiving a PO. See Updating Item Locations During Receiving for more information.
Default Primary Location - Suspense Placement and PO Receipts (C08)	If you select this field, the primary location for an item will default to the Location field when receiving inventory using Suspense Placement or PO Receipts, if a primary location has been defined for the item in the Item/SKU table, and the warehouse specified is the item's primary warehouse. See Determining the Receipt Location for more information.
Default Primary Location from an Item Warehouse (G06)	If you select this field, a primary location for an item in the warehouse specified for an inventory or receipt transaction will default to the Location field. If more than one primary location has been defined for the item in the specified warehouse, the system will default the first, in alphanumeric order. See Determining the Receipt Location for more information.
Print Drop Ship Invoice at time of Purchase Order Receiving (F10)	If you select this field, the system prints a drop ship invoice when a drop ship purchase order is received.
Labels at PO Receipts (C16)	If set to Y, the system prints a single label for the total quantity received when a PO Receipt In XML Message (CWReceiptIn) is processed successfully. If set to N or P, the system does not print a label.

Menu Options Related to the Purchase Order Receipt In API

Menu Option	Description
Maintaining Purchase Orders (MPOE)	Use this menu option to maintain POs to send to the warehouse management system. See Generic Outbound Purchase Order API for more information on how to send PO information to an external system.
Working with PO Receipt Errors (WPRE)	Use this menu option to review, correct, and reprocess a PO Receipt In XML Message (CWReceiptIn) that was placed in an error status. You can control which users have access to this menu option using the Work with Menu Option Authority Screen.
Receiving Purchase Orders (PORC)	Use this menu option to interactively receive POs instead of receiving POs using the Purchase Order Receipt In API. You may wish to interactively receive a PO if an error occurred using the Purchase Order Receipt In API. When you receive interactively, you must make sure that the inventory information in Order Management System remains consistent with the inventory information in the warehouse management system.

Secured Features Related to the Purchase Order Receipt In API

The system uses your default user to process PO receipts received through the Purchase Order Receipt In API. Set the authority of the default user for the following secured features.

In addition, the system uses the user that corrects any PO receipt errors in the Working with PO Receipt Errors (WPRE) menu option to reprocess corrected PO receipts. Set the authority of users who will correct PO receipt errors for the following secured features.

Secured Feature	Description
Override PO Cost (A17)	• If your default user has authority to this secured feature, the system allows you to override the cost of the PO line during receiving, using the cost tag in the PO Receipt In XML Message (CWReceiptIn). • If your default user does not have authority to this secured feature, the system does not allow you to override the cost of the PO line during receiving, using the cost in the PO Receipt In XML Message (CWReceiptIn): Not Auth to Override Cost. Note: If you wish to review the override PO cost before processing it, set the default user authority to the Override PO Cost (A17) secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the PO receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override PO Cost (A17) secured feature. If the user correcting the error does not have authority to the Override PO Cost (A17) secured feature, the Cost field is display-only on the Change PO Receipt Error Screen.
Override Tolerance (A18)	• If your default user has authority to this secured feature, the system allows you to override the percentage defined in the Over Receipt % (A61) system control value and receive any amount greater than the quantity ordered on the PO line. • If your default user does not have authority to this secured feature, the system allows you to receive an amount greater than the quantity ordered on the PO line, up to the over receipt percentage defined in the Over Receipt % (A61) system control value. See Over Receiving the PO Line Order Quantity for more information. Note: If you wish to review the over receipt before processing it, set the default user authority to the Override Tolerance (A18) secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the over receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override Tolerance (A18) secured feature.
Receipt of Non-inventory Item (A19)	• If your default user has authority to this secured feature, the system allows you to receive a non-inventory item that does not exist in the Item table. • If your default user does not have authority to this secured feature, the system does not allow you to receive a non-inventory item that does not exist in the Item table. Note: If you wish to review the non-inventory receipt before processing it, set the default user authority to the Receipt of Non-inventory Item (A19) secured feature to EXCLUDE so that the PO Receipt In XML Message (CWReceiptIn) fails to process and is placed in the Working with PO Receipt Errors (WPRE) menu option for review. In order to process the non-inventory receipt, the user that corrects the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Receipt of Non-inventory Item (A19) secured feature. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table for more information.

Purchase Order Receipt In: Sample XML Messages

Samples of the PO Receipt In XML Message (CWReceiptIn) are presented below.

Sample XML for an inventoried item:

</Message>

Sample XML for a non-inventory item:

</Message>

PO Receipt In XML Message (CWReceiptIn)

The Purchase Order Receipt In message contains PO receipt information to receive a PO line into a specified location. The external system, such as a warehouse management system, must generate a separate message for each PO line to receive. In addition, if the PO is to be received into more than one location, the external system must generate a separate message for each location.

For more information: See:

• Purchase Order Receipt In API for an overview.

• Purchase Order Receipt In: Sample XML Messages for sample messages.

• XML Messages for a sample of the DTD, schema, and generic sample XML of the PO Receipt In XML message.

Attribute Name	Type	Length	Comments
Message One Message element is required.
source	alpha		Indicates the source of the message.
target	alpha		Indicates the target of the message, such as OROMS.
type	alpha		CWReceiptIn indicates the message contains PO receipt information.
Receipt One Receipt element is required.
transaction_type	alpha	1	Identifies the type of transaction. Valid value: R = PO Receipt transaction. Required.
company	alpha	3	A code for the company that contains the PO to receive. Required. Validated against the CMP Company field in the Company table. Successful CWReceiptIn message: Updates the CMP Company field in the PO Receipt table. Failed CWReceiptIn message: If this value does not represent a valid company code on your system, the transaction will not process, and the error will not be visible through Working with PO Receipt Errors (WPRE). Updates the Company# field in the PO Receipt Error table.
po_nbr	numeric	7	The PO number to receive. The PO must be in an Open status. Required. Validated against the P/O # field in the PO Header table for the specified company. Successful CWReceiptIn message: Updates the PO # field in the PO Receipt table. Failed CWReceiptIn message: If the CWReceiptIn message contains errors, updates the PO# field in the PO Receipt Error table.
po_line_seq_nbr	numeric	5	The PO line sequence number of the PO line to receive. The PO line must be in an Open status. This is the first item indicator the system reviews when Determining the Item and SKU to Receive. If a value is defined in this field, the system ignores the values defined in the item, sku, vendor_item, short_sku, upc_type, upc_code, and retail_ref_nbr. Optional. Validated against the Seq # field in the PO Detail table for the specified po_nbr. Successful CWReceiptIn message: Updates the Seq # field in the PO Receipt table. Failed CWReceiptIn message: Updates the PO Seq# field in the PO Receipt Error table.
receipt_date	numeric	7	The date the item was received into the specified location in the warehouse. Optional. The receipt date must be in MMDDYYYY format and equal to or later than the PO line create date. If a receipt date is not passed, the system updates the receipt date to the date the CWReceiptIn message was processed. Successful CWReceiptIn message: Updates the Receipt date field in the PO Receipt table. Failed CWReceiptIn message: Updates the Receipt Date in the PO Receipt Error table.
receipt_time	numeric	6	The time the item was received into the specified location in the warehouse. Optional. The receipt time must be in HHMMSS format and be a valid time. If a receipt time is not passed, the system updates the receipt time to the time the CWReceiptIn message was processed. Successful CWReceiptIn message: Updates the Time field in the PO Receipt table. Failed CWReceiptIn message: Updates the Receipt Time field in the PO Receipt Error table.
quantity	numeric	7	The number of units of the item to receive into the specified location and warehouse. Required. The quantity must be a positive number greater than zero. If you pass a decimalized number, such as 12.99, the system ignores the number after the decimal; for example, 12.99 passes as 12. See Determining the Quantity to Receive for additional information. Successful CWReceiptIn message: Updates the SKU UOM qty field in the PO Receipt table. Failed CWReceiptIn message: Updates the Quantity field in the PO Receipt Error table.
cost	numeric	11.4	The cost of the item. Your default user must have authority to the Override PO Cost (A17) secured feature in order to pass an override cost in the PO Receipt In message: Not Auth to Override Cost. In order to correct this error in the Working with PO Receipt Errors (WPRE) menu option, the user correcting the error must have authority to the Override PO Cost (A17) secured feature; otherwise, the Cost field is display-only on the Change PO Receipt Error Screen. If you do not pass an override cost, the system performs the Standard Receipt Cost Calculation to determine the receipt cost. Optional. Successful CWReceiptIn message: Updates the Cost field in the PO Receipt table. Failed CWReceiptIn message: Updates the Cost field in the PO Receipt Error table.
currency_rate	numeric	11.7	The currency conversion rate defined for the item at the time of the receipt. Overrides the existing currency rate on the PO. Optional. Successful CWReceiptIn message: Updates the Currency Rate field in the PO Receipt table. Failed CWReceiptIn message: Updates the Currency Rate field in the PO Receipt Error table.
customs_date	numeric	7	The date the receipt was received in a customs or consolidation center for international orders. Optional. The customs date must be in MMDDYYYY format and equal to or later than the PO line create date. Successful CWReceiptIn message: Updates the Customs date field in the PO Receipt table, if passed. Failed CWReceiptIn message: Updates the Customs Date field in the PO Receipt Error table.
item	alpha	12	A code for the item to receive. If the item contains SKUs, you must also specify the sku to receive. This, along with the sku, is the second item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the item and SKU specified if the po_line_seq_nbr is blank. In addition, the system ignores the values defined in the vendor_item, short_sku, upc_type, upc_code, and retail_ref_nbr. Optional. Validated against the ITM Number field in the Item table. The system also validates the item against the PO Detail table to verify that the item exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the Item field in the PO Receipt Error table.
sku	alpha	14	A code for the SKU of the item to receive. This, along with the item, is the second item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the item and SKU specified if the po_line_seq_nbr is blank. In addition, the system ignores the values defined in the vendor_item, short_sku, upc_type, upc_code, and retail_ref_nbr. Optional. Validated against the SKU Code field in the SKU table. The system also validates the item and SKU combination against the PO Detail table to verify that the item and SKU exists on an open PO line on the specified po_nbr. Note: In order for the system to recognize the SKU specified, you must have a blank space between each of the 4-position SKU elements. For example, if the SKU is BLUE SML WMNS, you need to enter BLUE + 1 blank space + SML + 2 blank spaces + WMNS. If the SKU is XSML, you need to enter 5 blank spaces (since the first SKU element is not used) + XSML + 5 blank spaces (since the third SKU element is not used). Failed CWReceiptIn message: Updates the SKU field in the PO Receipt Error table.
vendor_item	alpha	20	A code for the vendor item defined for the item to receive. This is the third item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the vendor item specified if the po_line_seq_nbr, item, and sku are blank. In addition, the system ignores the values defined in the short_sku, upc_type, upc_code, and retail_ref_nbr. Optional. Validated against the Item field in the Vendor Item table. The system also validates the vendor item against the PO Detail table to verify that the item/SKU exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the Vendor Item field in the PO Receipt Error table.
short_sku	numeric	7	The short SKU code defined for the item to receive. The system automatically assigns the short SKU number, which you can review at the second Display SKU screen; see Performing Initial Item Entry (MITM). This is the fourth item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the short SKU code specified if the po_line_seq_nbr, item, sku, and vendor_item are blank. In addition, the system ignores the values defined in the upc_type, upc_code, and retail_ref_nbr. Optional. Validated against the Short SKU field in the SKU table. The system also validates the Short SKU against the PO Detail table to verify that the item/SKU exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the Short SKU field in the PO Receipt Error table.
upc_type	alpha	3	Identifies the type of UPC code defined for the item on the PO line to receive. Valid values: • E13 = EAN-13 • E8 = EAN-8 • UA = UPC-A • UE = UPC-E You use the Work with UPC Codes Screen to work with UPC types and codes. This, along with the upc_code, is the fifth item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the upc type and upc code specified if the po_line_seq_nbr, item, sku, vendor_item, and short_sku are blank. In addition, the system ignores the value defined in the retail_ref_nbr. Optional. However, if you enter a UPC type, you must also enter a upc_code. Validated against UPC type field in the Item UPC table. The system also validates the UPC type and UPC code against the PO Detail table to verify that the item/SKU exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the UPC Type field in the PO Receipt Error table.
upc_code	alpha	14	Identifies the UPC code defined for the item on the PO line to receive. You use the Work with UPC Codes Screen to work with UPC types and codes. This, along with the upc_type, is the fifth item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the upc type and upc code specified if the po_line_seq_nbr, item, sku, vendor_item, and short_sku are blank. In addition, the system ignores the value defined in the retail_ref_nbr. Optional. Can be passed without a upc_type. However, if you pass a valid UPC type, the system validates that the UPC code is valid for the specified UPC type. Note: Include any leading zeros. For example, if the UPC code is 06012011, pass 06012011 and not 6012011. Validated against the UPC field in the Item UPC table. The system also validates the UPC type and UPC code against the PO Detail table to verify that the item/SKU exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the UPC# field in the PO Receipt Error table.
retail_ref_nbr	numeric	15	Identifies the retail reference number defined for the item on the PO line to receive. You can assign a Reference # at the Create Item (Base Information) Screen or the Create SKU 2 of 2 (With Overrides) Screen. This is the sixth item indicator the system reviews when Determining the Item and SKU to Receive. The system only reviews the retail reference number specified if the po_line_seq_nbr, item, sku, vendor_item, short_sku, upc_type, and upc_code are blank. Optional. Validated against the Retail reference # field in the SKU table. The system also validates the retail reference number against the PO Detail table to verify that the item/SKU exists on an open PO line on the specified po_nbr. Failed CWReceiptIn message: Updates the Retail Ref# field in the PO Receipt Error table.
non_inv_item	alpha	1	Indicates if the item to receive is a non-inventory item that does not exist in the Item table. Valid values: • Y = The item to receive is a non-inventory item that does not exist in the Item table. • N or blank = The item to receive is an item that exists in the Item table. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table for instructions. Failed CWReceiptIn message: Updates the Non-inventory Item field in the PO Receipt Error table.
whs	numeric	3	A code for the warehouse where the item to receive is placed. Optional. Validated against the Warehouse table; see Creating and Maintaining Warehouses (WWHS) for more information. See Determining the Receipt Warehouse and Location for more information on how the system determines the receipt warehouse and location. Failed CWReceiptIn message: Updates the Warehouse field in the PO Receipt Error table.
location	alpha	7	A code for the location where the item to receive is placed. Optional. Validated against the Location table; must represent a valid location in the whs indicated. See Creating and Maintaining Locations (WLOC) for more information. See Determining the Receipt Warehouse and Location for more information on how the system determines the receipt warehouse and location. Note: • If the location exceeds the maximum length of 7 positions, it will be truncated. • This attribute is case-sensitive. A value of a is not the same as a value of A. Failed CWReceiptIn message: Updates the Location field in the PO Receipt Error table.

PO Receipt Errors

The table below describes the errors that may occur when processing a PO Receipt In XML Message (CWReceiptIn) through the Purchase Order Receipt In API.

• General PO Receipt In Errors

You can correct these errors in the Working with PO Receipt Errors (WPRE) menu option.

See Invalid XML? for a list of the errors that can occur in a PO Receipt In XML Message (CWReceiptIn) that cannot be fixed in the Working with PO Receipt Errors (WPRE) menu option.

PO Receipt In Error	Possible Reason(s)
General PO Receipt In Errors
Invalid Transaction Type	The transaction_type is missing or invalid. Valid value is R.
Invalid PO#	The po_nbr is missing or invalid.
Invalid PO Status	The po_nbr is not in an Open or Docked status. You cannot receive a PO through the Purchase Order Receipt In API that is in a Cancelled, Held, Suspended, or Closed status.
Invalid Customs Date	The customs_date is invalid. The date must be equal to or later than the current date in MMDDYYYY format; for example, 05042009 represents May 4, 2009.
Invalid Receipt Date	The receipt_date is invalid. The receipt date must be in MMDDYYYY format and equal to or later than the PO line create date.
Invalid Receipt Time	The receipt_time is invalid. The receipt time must be in HHMMSS format and a valid time.
Not Auth to Override Cost	An override cost is defined and the Default User does not have authority to the Override PO Cost (A17) secured feature. Note: In order to correct this error in the Working with PO Receipt Errors (WPRE) menu option, the user correcting the error must have authority to the Override PO Cost (A17) secured feature; otherwise, the Cost field is display-only on the Change PO Receipt Error Screen.
Errors Related to Resolving the Item and SKU See Determining the Item and SKU to Receive for more information.
Invalid Item/SKU	The item and SKU could not be resolved; see Determining the Item and SKU to Receive. For example: • The item does not exist in the Item table. • There is no item indicated. • The sku does not exist in the SKU table for the indicated item. • There is no sku indicated for a SKUed item.
Invalid Item	The item specified does not exist in the Item table.
Invalid SKU	The item is valid for an open PO line on the PO specified, but the sku is invalid for the specified PO line or does not exist in the SKU table.
Invalid Vendor Item for PO	The vendor_item specified is invalid for the open PO lines on the PO or does not exist in the Vendor Item table.
Invalid Short SKU	The short_sku specified is invalid for the open PO lines on the PO or does not exist in the SKU table.
Invalid UPC Type/Code	The upc_type and upc_code combination is invalid for the open PO lines on the PO or does not exist in the Item UPC table.
Invalid Retail Ref#	The retail_ref_nbr specified is invalid for the open PO lines on the PO or does not exist in the SKU table.
Item Could Not Be Identified	The item/SKU could not be identified based on the information provided in the following tags: • po_line_seq_nbr • item and sku • vendor_item • short_sku • upc_type and upc_code • retail_ref_nbr See Determining the Item and SKU to Receive for more information on the hierarchy the system uses to determine the item and SKU to receive.
PO Ln# Could Not Be Identified	• The item has been identified, but could not be matched to an open PO line on the PO specified. • The item contains SKUs and the sku is missing or invalid for the item on the PO line. • The item has been identified, but the PO line associated with the item is not in an Open status. See Determining the Item and SKU to Receive.
Invalid PO Line #	The po_line_seq_nbr contains a number that does not exist on the specified po_nbr.
Invalid PO Line Status	The PO line to receive is not in an Open status. You cannot receive a PO line through the Purchase Order Receipt In API that is in a Cancelled, Held, Suspended, or Closed status.
Invalid Non-inventory Item	The non_inv_item tag is set to Y and the item on the PO line specified is an inventory item that exists in the Item table. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table.
Invalid or Missing Non-inventory Flag	The non_inv_item tag is set to N or blank and the item on the PO line specified is a non-inventory item that does not exist in the Item table. See Receiving a Non-Inventory Item that Does Not Exist in the Item Table.
Not Auth to Non-inventory Item	You are Receiving a Non-Inventory Item that Does Not Exist in the Item Table and the Default User does not have authority to the Receipt of Non-inventory Item (A19) secured feature.
Errors Related to the Receipt Quantity See Determining the Quantity to Receive for more information.
Missing Receipt Quantity	The quantity is missing, 0, or a negative quantity, such as -5.
Receipt Qty exceeds Order Qty	The receipt quantity is greater than the quantity ordered on the PO line and: • the receipt quantity is greater than the allowed over receipt percentage defined in the Over Receipt % (A61) system control value, and • your default user does not have authority to the Override Tolerance (A18) secured feature. To correct this error, the user correcting the error in the Working with PO Receipt Errors (WPRE) menu option must have authority to the Override Tolerance (A18) secured feature.
Errors Related to the Receipt Location and Warehouse See Determining the Receipt Warehouse and Location for more information.
Invalid Warehouse	The whs is not a valid warehouse.
Invalid Location for Warehouse	The location does not exist in the specified whs.
Missing Location	The location is blank and the system could not default a receipt location for the item. See Determining the Receipt Warehouse and Location.
Mult Primary Loc Not Allowed	The Allow Multiple Primary Item Locations (D12) system control value is set to NOT ALLOW or CONFIRM, a primary location is defined for the item, and the receipt location is a different primary location than the one already defined for the item. See Updating Item Locations During Receiving.

Generic Outbound Purchase Order API

Contents

SCVs

Search

Glossary

Reports

Solutions

XML

Index

Working with PO Receipt Errors (WPRE)

Legal

WH13_03 OMSCS 19.0 December 2019 OHC