Purpose: Use the inbound return API to create and process a return against an order detail line, based on XML messages from an external system. The RETURN_IN job in Working with Integration Layer Processes (IJCT) processes return API requests.
Retail pickup or delivery orders: Unless the Suppress Returns for Retail Pickup/Delivery (L88) system control value is selected, you can process a return against a retail pickup or delivery order; however, shipping the order deactivates the Order Broker Payment Type (K98) applied to these orders, so you would first need to enter a new payment method in order to process the related refund.
Note: You cannot process an exchange against a retail pickup or delivery order.
The system does not send a status update to the Order Broker when you process a return against a retail pickup or delivery order.
See Retail Pickup (including Ship-for-Pickup) or Delivery Orders for an overview.
Ship-for-pickup orders: Unless the Payment at POS for Ship for Pickup Orders (L60) system control value is selected, you can process a return for a ship-for-pickup order. See Ship-for-Pickup Orders for an overview.
Store pickup orders: You cannot process a return against a store pickup order. See Store Pickup Orders for an overview.
In this chapter:
- Returning Against an Existing Return Authorization
- Determining the Return Warehouse and Location
- Tax Overrides and Return Processing
• Return Request Message (CWReturnIn)
- Return Request Message: Sample XML
• Return Response Message (CWReturnOut)
- Return Response Message: Sample XML
Purpose: You can use the generic return API to create, receive, and credit a return for a specified ship to order line.
The steps are:
1. |
An external system sends a Return Request Message (CWReturnIn) to Order Management System, using a queue specified for the RETURN_IN job. |
2. |
The RETURN_IN job in Working with Integration Layer Processes (IJCT) processes the return. |
|
• If there is an error, the RETURN_IN job creates a record in the Return Error table. You can review return errors in the Work with Return Interface Errors (WRIE) menu option. Note: If the SECRISK periodic function deactivated the payment methods on the order, the Return Response Message (CWReturnOut) returns the message No active paytypes. You cannot process the return unless you enter a different pay type for the order. See the Credit Card Retention Days (K65) system control value for background on the SECRISK function. |
|
• If there are no errors, the RETURN_IN job creates and receives and sends the return to the Billing Async to create the credit invoice. You can view the return in Work with Return Authorizations (WRTA). |
3. |
If the send_response field in the Return Request Message (CWReturnIn) is selected, the RETURN_IN job sends an Return Response Message (CWReturnOut) back to the external system, indicating if the return processed successfully or if an error occurred. |
Performing an exchange: In order to perform an exchange, you need to create the return using the Return Request Message (CWReturnIn) and then add the exchange item to a new order using the Generic Order Interface (Order API).
Creating a return that is not associated with an existing order: You can use the Generic Order Interface (Order API) to create a return that is not associated with an existing order. See Processing a Return for instructions.
In order to create a return using the Return Request Message (CWReturnIn), you must identify the Order Management System order associated with the return. You can identify the order by passing a value in one of the following fields:
• ecom_order_nbr, to specify the alternate order number from an outside system that is associated with the order. Orders from the web storefront and CWStore update this field. The e-commerce order number is stored in the E-Commerce order number field in the Order Header Extended table.
• ohd_order_nbr, to specify the Order Management System order number.
In addition, you must define which ship to is associated with the return by passing a value in the ship_to_nbr field.
Identifying the order and ship to number is required in order to process an inbound return.
You must create the return against an existing Order Management System order detail line. You can identify the order line to return against using the following fields:
• odt_seq_nbr: The order detail line sequence number defined in the Order Detail table.
• ra_nbr and ra_line_nbr: The return authorization number and return authorization line number defined in the RA Detail table. See Returning Against an Existing Return Authorization for additional information.
• item and sku: The item number, defined in the Item table. If the item is a SKUed item, you must also specify the SKU code, defined in the SKU table.
• short_sku: The short SKU for the item, defined in the SKU table.
• retail_ref_nbr: The retail reference number for the item, defined in the SKU table.
• upc_type and upc_code: The UPC type and UPC code for the item, defined in the Item UPC table. Note: Include any leading zeros. For example, if the UPC code is 06012011, pass 06012011 and not 6012011.
• alias: The alias code for the item, defined in the Page Letter Alias table. If the item is a SKUed item, you must pass sku along with alias in order to find the correct item and SKU code.
Note: If you pass information in a combination of the above fields, all of the information must be valid for a specific order detail line on the specified ship to order; otherwise, the return request will error: Invalid Order Detail Line.
What if the item exists on more than 1 order line? If the item exists on more than 1 order line, the system returns the item against the first order detail line, in order line sequence, that has enough quantity available to return to meet the return request.
Example: The RETURN_IN job receives an Return Request Message (CWReturnIn) against a ship to order for item AB101 for a quantity of 2. The order includes the following order lines.
Order line |
Item |
Shipped qty |
Results |
1 |
AB101 |
1 |
The system creates and processes a return against order line 3 for a quantity of 2. |
2 |
BC202 |
2 |
|
3 |
AB101 |
5 |
|
4 |
AB101 |
2 |
Using the example above, you will receive an error if you try to return item AB101 for a quantity of 6 since none of the order lines for item AB101 has a shipped quantity of 6 that is available to return. The system will not return against multiple order detail lines.
Returning Against an Existing Return Authorization
When the RETURN_IN job processes an Return Request Message (CWReturnIn) that includes a return authorization to return against, the system will receive and credit the existing return authorization.
In order to process a return against an existing return authorization, you must identify the following in the Return Request Message (CWReturnIn):
• the order number to return against (ecom_order_nbr or ohd_order_nbr)
• ship to number (ship_to_nbr)
• RA number and RA line number (ra_nbr and ra_line_nbr)
If you are using standard return authorization processing (the Use Streamlined Return Authorizations (F44) system control value is unselected and:
• the return is created, but not yet received, the system will receive and credit the return.
• the return is received, but not yet credited, the system will credit the return.
If the existing RA has already been completely processed or you are using streamlined return authorization processing (the Use Streamlined Return Authorizations (F44) system control value is selected), the Return Response Message (CWReturnOut) will indicate that the return failed with the error_message: Return Already Processed.
Note: When you return against an existing return authorization, the system processes the return using the settings defined for the existing RA, ignoring any value passed in the following fields:
• reason
• whs
• location
If you are not returning against an existing return authorization: If you are not returning against an existing return authorization, the system creates a new return authorization for the order ship to, using the next RA # available for the order ship to in the RA Header table. If the Use OROB Drop Shipping (H13) system control value is selected, when the system creates a new return authorization, the system looks at the highest RA# assigned to the order ship to in the RA Header table and compares it to the highest RA # assigned to the order ship to in the CSF Transaction table. Whichever table has the higher RA # defined for the order ship to, the system uses the next available number to create the return authorization. For example, if the highest RA # in the RA Header table for an order ship to is 1, but the highest RA # in the CSF Transaction table for an order ship to is 2, the system creates a new return authorization for the order ship to using RA # 3.
Determining the Return Warehouse and Location
The RETURN_IN job uses the following hierarchy to determine the warehouse and location where the item will be returned.
1. |
Return the item to the whs and location specified in the Return Request Message (CWReturnIn). |
2. |
If the whs and location are blank, return the item, based on the settings defined for the disposition specified in the Return Request Message (CWReturnIn). • If the disposition’s Affect inventory field is N, the item will not be returned to a warehouse or location. • If the disposition’s Affect inventory field is Y and the Use primary location field is Y, the item will be returned to its primary primary warehouse and location. • If the disposition’s Affect inventory field is Y and a Warehouse and Location are defined, the item will be returned to the specified warehouse and location. |
3. |
If the whs, location, and disposition are blank, return the item, based on the settings defined for the return disposition code defined in the Default Return Disposition Code for Inbound Returns (H65) system control value. If this system control value is unselected, the return will be placed in an error status: Invalid Rtn Disposition. |
If the item does not exist in the warehouse, the system will automatically create an item warehouse record. If the item has not been previously placed in this location, the system will automatically create an item location record.
You can use the suppress_refund field in the Return Request Message (CWReturnIn) to indicate if you do not want to create a refund for the return. For example, it might not be appropriate to generate a refund for a POS order, when the transactions have already taken place at the store.
If a value is passed in the suppress_refund field, the system updates the Suppress refund field in the Order Payment Method table for each payment method on the order. You can review the setting of the Suppress refund field at the Display Order Pay Type Screen (2 of 2).
• If the suppress_refund field in the Return Request Message (CWReturnIn) is N or is blank, the system updates the Suppress refund field for the payment methods on the order to N or leaves it blank, allowing the system to generate a refund for the order.
• If the suppress_refund field in the Return Request Message (CWReturnIn) is selected, the system updates the Suppress refund field for the payment methods on the order to Y, preventing a refund from being generated. If you generate a refund for the order, the refund is created in a status of N (cancel pending). When you use Processing Refunds (MREF), the refund status changes to C (cancelled). You cannot change the setting of the Suppress refund flag for a payment method, and the system will never generate a refund for the order payment method. In order to generate a refund, you need to deactivate the payment method and enter a new one; you will need to process any cancel-pending refund for the payment method before you can deactivate the payment method on the order.
The system writes an order transaction history message each time the Suppress refund flag is changed for a pay type: Suppress refund updated to Y on p/t 4.
What if the suppress_refund flag setting is different on returns for the same order? If you process multiple returns for an order, the system will update the Suppress refund field for each payment method on the order based on the setting defined for the last return processed.
If an unprocessed refund already exists for the order and a Return Request Message (CWReturnIn) is received for the order, the system will not update the status of the existing refund.
Example: The Suppress refund flag for the payment method on an order is blank.
The RETURN_IN job receives a CWReturnIn message for the order with the suppress_refund flag selected. The system updates the Suppress refund flag for the payment method to selected.
Because the Suppress refund flag for the payment method on the order is selected, the system creates the refund in an N (cancel pending) status.
The RETURN_IN job receives another CWReturnIn message for the order with the suppress_refund flag unselected. The system updates the Suppress refund flag for the payment method to unselected.
Because the Suppress refund flag for the payment method on the order is unselected, the system creates the refund in an O (open) status. The refund previously created for the order remains in a cancel pending status.
The RETURN_IN job receives another CWReturnIn message for the order with the suppress_refund flag set to blank.
The system does not update the Suppress refund setting for the payment method on the order. Because the Suppress refund flag for the payment method on the order is unselected, the system creates the refund in an O (open) status. The system does not update the status of the refunds previously created for the order.
If the Billing Async is inactive: If the Billing Async is inactive when the RETURN_IN job receives inbound return messages, the system will not process the returns until the Billing Async is started. However, the system will update the Suppress refund flag for the payment methods on the order as each inbound return is received.
Once the Billing Async is active, the system will process the returns. In addition, the status of all of the refunds created for the order will be based on the suppress_refund setting of the last return processed. Using the example above, the setting of the suppress_refund flag for the last return processed was blank, leaving the Suppress refund flag for the payment methods on the order as unselected; in this example, the system would create each refund in an open status.
Tax Overrides and Return Processing
Order Management System updates the Tax override field for an order line to selected if the order was received from an external system and a tax, GST, or PST amount was defined, indicating the tax amount from the external system should be retained on the order line.
If the Tax override field for the order line you are returning is selected, the system does not call the regular tax routine to recalculate the amount of tax remaining on the order line and how much tax to include on the credit invoice. Likewise, if you use an external tax system to calculate tax, the system does not call the tax system to recalculate the tax amount.
Instead, the system prorates the tax override amount across the units ordered on the order line to determine the new tax override amount and the tax amount to return.
Determining the new tax override amount: The system uses the following calculations to determine the new tax override amount assigned to the order line. This is the tax amount that displays in the Tax field on the Display Order Detail Screen (Reviewing Order Line Detail).
Original order quantity - Total order line return quantity = Net order quantity
Net order quantity / Original order quantity = Return ratio
Return ratio x Original tax override amount = New tax override amount
Determining the tax amount to return: The system uses the following calculations to determine the tax amount to include on the credit invoice created for the return. This is the tax amount that displays in the Tax field on the Second Display Invoice Detail Screen.
Current return quantity / Original order quantity = Return ratio
Return ratio x Original tax override amount = Returned tax amount
Example: An order line includes 5 units of an item. The tax override amount for the order line is 5.00. You return 1 unit of the item against the order line. 2 units of the item have previously been returned against the order line.
In this example:
• The original order quantity is 5.
• The total order line return quantity is 3.
• The current return quantity is 1.
The system determines the new tax override amount:
5 - 3 = 2
2 / 5 = .4
.4 x 5.00 = 2.00
2.00 displays in the Tax field for the order line on the Display Order Detail screen.
The system determines the tax amount to return:
1 / 5 = .2
.2 x 5.00 = 1.00
1.00 displays in the Tax field for the credit invoice on the Display Invoice Detail screen.
A list of errors that may occur when processing a return from an external system is presented below. You can review inbound returns that did not process due to an error in the Work with Return Interface Errors (WRIE) menu option.
Error description |
Reason |
Invalid Company |
The company field does not contain a valid Order Management System company code. |
Invalid item/SKU for Order Detail Line |
The item information specified in the Return Request Message (CWReturnIn) is not located on the order line associated with the odt_seq_nbr. |
Invalid Loc for Return |
The location passed or the location associated with the Default Return Disposition Code for Inbound Returns (H65) is not a valid location for the warehouse specified. |
Invalid Order Detail Line |
The system: • Could not locate an order line to return against, based on the item information passed in the Return Request Message (CWReturnIn). • Could not return against the order line because there wasn’t an available quantity to return, for example, the item had not shipped yet. See Identifying the Order Line for more information on the different ways you can identify the order line to return against. |
Invalid Order Header |
The system could not locate an order to return against based on the value passed in the ecom_order_nbr or ohd_order_nbr field. See Identifying the Order for more information on the different ways you can identify the order to return against. |
Invalid Order Ship To |
The system could not locate the ship to order to return against, based on the value passed in the ship_to_nbr field. |
Invalid RA Detail |
The ra_line_nbr passed does not match the Line # field in the RA Detail table for the specified Order Management System order number, ship to number, and item. The specified order number, ship to number, and item is not associated with an existing return authorization. |
Invalid RA Header |
The ra_nbr passed does not match the RA # field in the RA Detail table for the specified Order Management System order number, ship to number, and item. The specified order number, ship to number, and item is not associated with an existing return authorization. |
Invalid Return Quantity |
The qty passed does not match the quantity available to return for an order line. For example, if an item was ordered on 2 order lines, you must create a separate return for each order line or you will receive this error message. If you are returning against an RA, the quantity passed must match the quantity to return that was created on the RA. |
Invalid Return Reason |
The reason passed in not a valid return reason code. Return reason codes are defined in and validated against the Return Reason table. |
Invalid Rtn Disposition |
The disposition is blank and a disposition code is not defined in the Default Return Disposition Code for Inbound Returns (H65) system control value. |
Invalid Whs for Return |
The whs passed or the warehouse associated with the Default Return Disposition Code for Inbound Returns (H65) is not a valid warehouse. |
Missing Company |
The company field is blank. |
Missing Default Charge Code (H64) for misc credit |
An amount was passed in the credit_amt field and an additional charge code was not defined in the Default Additional Charge Code for Inbound Returns (H64) system control value to assign to the charge. |
Missing Order Detail Ln# |
The system could not locate an order line to return against, based on the item information passed in the Return Request Message (CWReturnIn). See Identifying the Order Line for more information on the different ways you can identify the order line to return against. |
Missing Return Reason |
The reason is blank and a return reason code is not defined in the Default Return Reason Code for Inbound Returns (H63) system control value. |
No Active Paytypes |
Typically, this message indicates that the pay type on the order was deactivated by the SECRISK periodic function, though it could indicate that the payment method was deactivated for another reason, such as that it is a retail pickup or delivery order. See the Credit Card Retention Days (K65) system control value for background on the SECRISK periodic function, and see Retail Pickup (including Ship-for-Pickup) or Delivery Orders for background on retail pickup and delivery orders. |
Order Detail line already returned |
The item passed has already been returned for the available quantity. |
Return Already Processed |
The quantity available to return against the order line has already been returned and processed. |
Return not allowed on Retail Pickup/Delivery Orders. |
The order specified is a retail pickup or delivery order, and the Suppress Returns for Retail Pickup/Delivery (L88) system control value is selected. See that system control value for background. |
Return not allowed for Ship for Pickup Orders. |
The order specified is a ship-for-pickup order, and the Payment at POS for Ship for Pickup Orders (L60) system control value is selected. See that system control value for background. |
Purpose: Before you can process an Return Request Message (CWReturnIn) through the RETURN_IN job, you must perform the necessary Order Management System setup.
System Control Value |
Description |
If a refund_frt value is not passed in the Return Request Message (CWReturnIn), the system uses the setting in this system control value to determine whether the system refunds freight charges for a return initiated from an outside system. If this system control value is unselected, the Refund freight field for the return defaults to unselected. |
|
If a refund_chg value is not passed in the Return Request Message (CWReturnIn), the system uses the setting in this system control value to determine whether the system refunds additional charges for a return initiated from an outside system. If this system control value is unselected, the Refund additional charges field for the return defaults to unselected. |
|
If a refund_hand value is not passed in the Return Request Message (CWReturnIn), the system uses the setting in this system control value to determine whether the system refunds handling charges for a return initiated from an outside system. If this system control value is unselected, the Refund handling field for the return defaults to unselected. |
|
If a refund_duty value is not passed in the Return Request Message (CWReturnIn), the system uses the setting in this system control value to determine whether the system refunds duty charges for a return initiated from an outside system. If this system control value is unselected, the Refund duty field for the return defaults to unselected. |
|
If a reason value is not passed in the Return Request Message (CWReturnIn), the system defaults the return reason in this system control value to a return initiated from an outside system. |
|
If a credit_amt value is passed in the Return Request Message (CWReturnIn), the system defaults the additional charge code in this system control value to a return initiated from an outside system. |
|
If a disposition value is not passed in the Return Request Message (CWReturnIn), the system defaults the disposition code in this system control value to a return initiated from an outside system. |
Menu Option |
Description |
The RETURN_IN job: • Validates the data in the Return Request Message (CWReturnIn). If an error exists, you can display the error in the Work with Return Interface Errors (WRIE) menu option. • Creates a return based on an Return Request Message (CWReturnIn) received from an external system. • Optionally, sends an Return Response Message (CWReturnOut) to the external system. In addition, you must set up an inbound queue to receive an Return Request Message (CWReturnIn) from an external system and an outbound queue to send an Return Response Message (CWReturnOut) to the external system. Note: If the SECRISK periodic function deactivated the payment methods on the order, the Return Response Message (CWReturnOut) returns the error No active paytypes. You cannot complete the return through Work with Return Interface Errors (WRIE), but can use the Return Request Message (CWReturnIn) as an alternative. See Credit Card Retention Days (K65) for background. |
Secured Feature |
Description |
Note: The system does not require authority to these secured features in order to create, receive, and credit a return processed through the RETURN_IN job. The system creates the return without errors; however, if you do not have authority to these secured features, you cannot review the return in WRTA. |
|
Note: The system does not require authority to this secured feature in order to assign a certain return disposition code to a return processed through the RETURN_IN job. |
You can use the CWMessageIn Web Service to route CWReturnIn messages. In this situation, the target for each inbound message must match the Inbound program name for the integration layer process queue, as specified at the Integration Layer Process Queue Screen.
The RETURN_IN integration layer process can remain inactive and a queue is not required if the target is CWRETURNIN in the XML message.
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.
If you are using the CWMessageIn RESTful web service: You POST inbound CWMessageIn messages to the web service’s URI, or endpoint, of the RESTful service. The individual URL for the CWMessageIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWMessageIn, where server:port identifies the application server where the RESTful service is located and CWMessageIn is the name of the web service to call.
If you are using the CWMessageIn SOAP-based web service: The endpoint specified in the CWMessageIn.wsdl file is where you need to post messages in order for the CWMessageIn web service to process them. The endpoint is typically set to http://server:port/CWDirectCPService/services/CWMessageIn, where server:port identifies the application server where the wsdl is located and CWMessageIn is the name of the web service to call. The CWMessageIn SOAP-based web service requires that inbound messages be embedded in SOAP envelope tags.
Return Request Message (CWReturnIn)
The RETURN_IN job in Working with Integration Layer Processes (IJCT) receives and processes this message to create a return against an order line. See Inbound Return API for more information.
See Return Request Message: Sample XML for a sample message.
Attribute Name |
Type |
Length |
Comments |
source |
alpha |
25 |
Identifies the source of the XML message. |
target |
alpha |
25 |
Identifies the target of the XML message. |
type |
alpha |
25 |
Identifies the type of information in the XML message. CWReturnIn indicates the message includes a return request. |
resp_qmgr |
alpha |
50 |
Informational only. |
numeric |
3 |
The Order Management System company where the order associated with the return is located. Required. Updates the Company field in the RA Detail table. |
|
Identifying the order: In order to create a return, you must identify the Order Management System order and ship to number associated with the return. See Identifying the Order for more information. |
|||
alpha |
30 |
The alternate order number from an outside system that is associated with the return, as defined in the E-Commerce order number field in the Order Header Extended table. Orders from the web storefront and CWStore update this field. Required if ohd_order_nbr is blank. Used to locate the order associated with the return. |
|
numeric |
8 |
The Order Management System order number associated with the return, as defined in the Order # field in the Order Header table. Required if ecom_order_nbr is blank. Used to locate the order associated with the return. Updates the Order # field in the RA Detail table. |
|
numeric |
3 |
The order ship to number associated with the return, as defined in the Ship to # field in the Order Ship To table. Required. Updates the Ship to # field in the RA Detail table. |
|
Identifying the order line: You must create the return against an existing Order Management System order detail line. See Identifying the Order Line for more information on the different ways you can identify which order line you wish to return against. |
|||
numeric |
5 |
The order detail line sequence number associated with the return, as defined in the Seq # field in the Order Detail table. Required if ra_nbr, ra_line_nbr, item, sku, retail_ref_nbr, short_sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. |
|
numeric |
3 |
The return authorization number to return against, as defined in the RA # field in the RA Detail table. Required if odt_seq_nbr, item, sku, retail_ref_nbr, short_sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. Note: In order to return against an RA #, you must have the Use Streamlined Return Authorizations (F44) system control value unselected and have an existing return created, but not yet processed. The system will use the order number, ship to number, RA number, and RA line number passed to locate the existing return authorization to return against. See Returning Against an Existing Return Authorization. |
|
numeric |
3 |
The return authorization line number to return against, as defined in the Line # field in the RA Detail table. Required if odt_seq_nbr, item, sku, retail_ref_nbr, short_sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. Note: In order to return against an RA #, you must have the Use Streamlined Return Authorizations (F44) system control value unselected and have an existing return created, but not yet processed. The system will use the order number, ship to number, RA number and RA line number passed to locate the existing return authorization to return against. See Returning Against an Existing Return Authorization. |
|
numeric |
5 |
The number of units of the item to return. The return errors if the return quantity is greater than the quantity available to return on the order line. Required. Updates the Qty returned field in the RA Detail table. |
|
Determining the return warehouse and location: See Determining the Return Warehouse and Location for the hierarchy the RETURN_IN job uses to determine the warehouse and location where the item will be returned. |
|||
numeric |
3 |
The warehouse where the item is being returned. Required if a return disposition code is not defined in the disposition field or Default Return Disposition Code for Inbound Returns (H65) system control value. Updates the Whs field in the RA Detail table. |
|
numeric |
7 |
The warehouse location where the item is being returned. Required if a return disposition code is not defined in the disposition field or Default Return Disposition Code for Inbound Returns (H65) system control value. Updates the Location field in the RA Detail table. |
|
alpha |
3 |
A code that identifies how a returned item will be handled by Order Management System, in terms of whether the return updates inventory and the warehouse and location to which the item will be returned. If the return affects inventory, meaning the item will be returned into active inventory and update the on hand quantity in the specified location, and a whs and location are not defined, the system returns the inventory to the warehouse and location defined for the return disposition code. If a disposition is not passed or is invalid, the system uses the disposition code defined in the Default Return Disposition Code for Inbound Returns (H65) system control value. If the system control value is unselected, the return is placed in an error status: Invalid Rtn Disposition. |
|
numeric |
3 |
Indicates the reason the customer is returning the item. If a reason is not passed, the system uses the return reason code defined in the Default Return Reason Code for Inbound Returns (H63) system control value. If this system control value is unselected, the return is placed in an error status: Missing Return Reason. |
|
alpha |
12 |
The item to return, as defined in the ITM number field in the Order Detail table. If the item is a SKUed item, you must also specify the SKU code in the sku field. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, retail_ref_nbr, short_sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. |
|
alpha |
14 |
The SKU code of the item to return, as defined in the SKU table. Required if item or alias is passed and the item is a SKUed item. Used to locate the order line to return against. |
|
numeric |
7 |
The short SKU code for the item, as defined in the SKU table. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, retail_ref_nbr, item, sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. |
|
numeric |
15 |
The retail reference number for the item, as defined in the SKU table. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, short_sku, item, sku, upc_type, upc_code, and alias are blank. Used to locate the order line to return against. |
|
alpha |
3 |
The type of UPC code, as defined in the Item UPC table. The associated UPC code is defined in the upc_code field. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, short_sku, item, sku, retail_ref_nbr, and alias are blank. Used to locate the order line to return against. |
|
alpha |
14 |
The UPC code assigned to an item, as defined in the Item UPC table. The associated UPC type is defined in the upc_type field. Note: Include any leading zeros. For example, if the UPC code is 06012011, pass 06012011 and not 6012011. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, short_sku, item, sku, retail_ref_nbr, and alias are blank. Used to locate the order line to return against. |
|
alpha |
12 |
An alternate name assigned to the item, as defined in the Page Letter Alias table. Note: If the item is a SKUed item, you must pass sku along with alias in order to find the correct item and SKU code. Required if odt_seq_nbr, ra_nbr, ra_line_nbr, short_sku, item, sku, retail_ref_nbr, upc_type and upc_code are blank. Used to locate the order line to return against. |
|
alpha |
1 |
Indicates whether to refund the freight charge for the returned item. • Y = Refund freight. • N = Do not refund freight. If you enter Y and the source code uses a header level freight method, the system refunds a proportionate amount of freight for the item being returned. If you enter Y and the source code uses a line level or flat freight method, the system refunds the freight charge for the returned item on the order. Note: This setting also controls whether the system refunds any service charges by ship via on the order. If a refund_frt value is not passed, the system uses the setting defined in the Refund Freight Default for Inbound Returns (H59) system control value. Updates the Refund freight field in the RA Detail table. If you are returning against an existing RA, the system uses the Refund freight setting defined for the existing RA detail line, ignoring this value. |
|
alpha |
1 |
Indicates whether the system will credit the handling charge for the returned item. • Y = The system will include the charge for special handling in the customer’s refund. • N = Any charges for special handling, such as monogramming, will not be refunded to the customer. If a refund_hand value is not passed, the system uses the setting defined in the Refund Handling Default for Inbound Returns (H61) system control value. Updates the Refund handling field in the RA Detail table. If you are returning against an existing RA, the system uses the Refund handling setting defined for the existing RA detail line, ignoring this value. |
|
alpha |
1 |
Indicates whether the system will refund the additional charges for the returned item. • Y = Refund additional charges. • N = Do not refund additional charges. If a refund_chg value is not passed, the system uses the setting defined in the Refund Additional Charge Default for Inbound Returns (H60) system control value. Updates the Refund add’l chgs field in the RA Detail table. If you are returning against an existing RA, the system uses the Refund add’l chgs setting defined for the existing RA detail line, ignoring this value. |
|
alpha |
1 |
Indicates whether the system will refund duty charges for the returned item. • Y = Refund duty charges for the returned item. • N = Do not refund duty. If a refund_duty value is not passed, the system uses the setting defined in the Refund Duty Default for Inbound Returns (H62) system control value. Updates the Refund duty field in the RA Detail table. If you are returning against an existing RA, the system uses the Refund duty setting defined for the existing RA detail line, ignoring this value. |
|
numeric |
9.2 |
The credit amount to refund the customer for the return. For example, you may wish to refund return postage. The credit amount must be a positive amount. If you define a credit amount, the system will assign the code defined in the Default Additional Charge Code for Inbound Returns (H64) system control value to the credit. If this system control value is unselected and a credit amount is passed, the return is placed in an error status: Missing Default Charge Code (H64) for misc credit. Updates the Add’l charges field in the Order Additional Charge table. |
|
alpha |
1 |
Indicates whether an Return Response Message (CWReturnOut) is sent back to the external system, indicating if the return was processed successfully or if any error occurred. • Y = Send an Return Response Message (CWReturnOut). • N = Do not send an Return Response Message (CWReturnOut). |
|
alpha |
1 |
Indicates whether you wish to suppress a refund for the return. For example, if the return is from a retail store, you may have already refunded the customer. • Y = Do not create a refund for the return. The system changes the Suppress refund field for each payment method of the order to selected. • N = Create a refund for the return. The system changes the Suppress refund field for each payment method of the order to unselected. Note: If you process multiple returns for an order, the system will update the Suppress refund field for each payment method on the order based on the setting defined for the last return processed. See Suppressing Refunds. |
|
Return Request Message: Sample XML
A sample of the Return Request Message (CWReturnIn) is presented below.
<Message source="cwi" target="OMS" type="CWReturnIn" resp_qmgr="CWIAS400">
<Return company="555" ecom_order_nbr="1122005" ohd_order_nbr="7885" ship_to_nbr="1" odt_seq_nbr="1" ra_nbr="1" ra_line_nbr="1" qty="1" whs="205" location="2050101" disposition="KM" reason="2" item="2005SKU1" sku="RED WMNS SMLL" short_sku="1781" retail_ref_nbr="12005" upc_type="E13" upc_code="200511" alias="SKU12005" refund_frt="Y" refund_hand="Y" refund_chg="Y" refund_duty="Y" credit_amt="150" send_response="Y" suppress_refund="N" />
</Message>
Return Response Message (CWReturnOut)
The RETURN_IN job in Working with Integration Layer Processes (IJCT) sends this message to an external system, indicating if the Return Request Message (CWReturnIn) was processed successfully or if any error occurred. See Inbound Return API for more information.
See Return Response Message: Sample XML for a sample message.
Attribute Name |
Type |
Length |
Comments |
source |
alpha |
25 |
Identifies the source of the XML message. |
target |
alpha |
25 |
Identifies the target of the XML message. |
type |
alpha |
25 |
Identifies the type of information in the XML message. CWReturnOut indicates the message is a return response. |
date_created |
numeric |
8 |
The date the outbound return message was created, in YYYY-MM-DD format. |
time_created |
numeric |
8 |
The time the outbound return message was created, in HH:MM:SS format. |
company |
numeric |
3 |
The Order Management System company where the return was created. From the Company field in the RA Detail table. |
ecom_order_nbr |
alpha |
30 |
The alternate order number associated with the order that was returned against. From the E-Commerce order number field in the Order Header Extended table. |
order_nbr |
numeric |
8 |
The Order Management System order number that was returned against. From the Order # field in the RA Detail table. |
ship_to_nbr |
numeric |
3 |
The ship to order number that was returned against. From the Ship to # in the RA Detail table. |
odt_seq_nbr |
numeric |
5 |
The order detail sequence number associated with the order line that was returned against. From the Seq # field in the Order Detail table. |
ra_nbr |
numeric |
3 |
The return authorization number associated with the return. From the RA # field in the RA Detail table. |
ra_line_nbr |
numeric |
3 |
The return authorization line number associated with the return. From the Line # field in the RA Detail table. |
item |
alpha |
12 |
A code for the item that was returned. From the ITM number field in the RA Detail table. |
sku |
alpha |
14 |
A code for the SKU of the item that was returned. From the SKU code field in the RA Detail table. |
whs |
numeric |
3 |
A code for the warehouse where the item was returned. From the Whs field in the RA Detail table. |
location |
alpha |
7 |
A code for the warehouse location where the item was returned. From the Location field in the RA Detail table. |
qty |
numeric |
5 |
The quantity of the item returned. From the Qty returned field in the RA Detail table. |
action_result |
alpha |
7 |
Indicates if the return was processed successfully or if an error occurred. • Success = The return was processed successfully. • Failure = An error occurred and the return was not processed. The error_message attribute indicates the description of the error, and the error can be viewed in the Work with Return Interface Errors (WRIE) menu option. |
alpha |
70 |
A description of the first error encountered while processing the Return Request Message (CWReturnIn). See Return API Errors for a list of possible errors and how to correct them. |
|
Return Response Message: Sample XML
A sample of the Return Response Message (CWReturnOut) is presented below.
<Message source="OMS" target="cwi" type="CWReturnOut" date_created="2006-01-12" time_created="14:35:48">
<Return company="555" ecom_order_nbr="1122005" ohd_order_nbr="7885" ship_to_nbr="1" odt_seq_nbr="1" ra_nbr="1" ra_line_nbr="1" item="2005SKU1" sku="RED WMNS SMLL" whs="205" location="2050101" qty="1" action_result="Success" />
</Message>
| Work with Return Interface Errors (WRIE) | Contents | SCVs | Search | Glossary | Reports | Solutions | XML | Index | Issuing Refunds |
CS09_12 OMS 17.1 September 2018 OTN