Generic Order Interface (Order API)

Generic Order Interface (Order API)

Purpose: Use the generic order interface to send orders into Order Management System Cloud Service via an integration layer process (IJCT) or directly from a remote system. You can use this interface for any type of order, including retail point of sale transactions, orders received through a remote call center, and orders taken at a web storefront.

Options: Your options through the generic order interface include:

• response: generating a detailed response listing errors, a detailed response that does not list errors, a simple response, or no response.

• separate payment message: sending the payment information separately or in the same message as the rest of the order information.

• deposit and refund suppression: suppressing the order from deposit processing and refund generation.

• returns: entering a return by specifying a negative order quantity.

• customer updates: updating an existing sold-to, or creates a new sold-to, bill-to, or permanent ship-to customer.

In this chapter:

• Order API Processing Overview

- Suppressing Deposits and Refunds

- Creating a Quote through the Order API

- Processing a Return

- Performing Credit Card Tokenization on Web Orders

- Performing Online Credit Card Authorization on Web Orders

- Creating Authorization History for Orders Authorized on the Web

• Typical Order Interface Scenarios

- Sending a Separate Payment Message

• Order API Setup Requirements

• Customer Creation, Matching and Update Logic in the Order API

- Customer Sold To Selection, Creation and Update

- Creating or Selecting Shipping Addresses or Customers

- Customer Bill To Selection and Creation

• Resolving the Item and SKU in the Order API

• User-Defined Fields in the CWOrderIn Message

• Selecting the Sales Rep

• Discounted and Added Items in the CWOrderOut Response Message

• Rejecting the Order (Order API)

• Order Interface XML Message Formats

- Inbound Order XML Message (CWORDERIN)

- Inbound Order Message: Sample XMLs

- Detailed Order XML Response (CWORDEROUT)

- Detailed Order Response Message: Sample XML

- Order Acknowledgement XML Message (CWORDEROUT)

- Order Acknowledgement Message: Sample XML

Order API Processing Overview

Typical process: A typical generic order interface process includes the following steps:

1.	Receive message: The generic order API web service receives the Inbound Order XML Message (CWORDERIN) and sends it to the order API program.
2.	Parse message: The order API program parses the message (identifies its components). If the message is not well-formed XML, or if any of the numeric fields passed exceed their maximum length, the program returns an error indicating the XML is invalid and does not continue.
3.	Review header and customer: If the message passes the initial validation, the program begins identifying the information in the message, including: • sold-to customer • bill-to customer The program performs much of the same processing that applies in interactive order entry, such as checks for duplicate customers. The program also processes other updates related to the order header, such as customer ownership and user fields. At this point, customer information is written to the database.
4.	Review ship-to: The program continues processing the order ship-to information. If there is a separate shipping address for the order (permanent, order-level, or recipient customer), the information is processed at this time.
5.	Review details and begin writing to database: The program processes the items on the order, as well as performing related calculations (pricing, freight, tax, and so on), and reserves available inventory. At this point the program writes all the header, ship-to, and detail data available to the database, setting the order header status to E (error) and the order ship-to status to S (suspended) pending further processing. Order cross reference: The program writes a record in the Order Cross-Reference table to track the Order Management System order number and the web order number. This step is necessary for situations when the initial inbound message does not include all required information for the order, such as when payment information is sent separately from the header and details; the order cross reference enables the program to determine which order to update. The ORDER_CLN job also uses the order cross reference when it deletes abandoned orders.
6.	Review additional order data: The program processes additional information, such as special handling and detail message, once the items are identified, and updates the database.
7.	Repeat for additional ship-tos: The previous three steps are repeated for each separate ship-to for the order.
8.	If payment is sent: If the message includes any payment information, the program: • processes and saves the payment method(s) to the database, using encryption as specified for your company. • performs normal end-of-order processing, such as repricing, adding promotional inserts, and credit checking. • looks at the setting of the Delay Order API Edit (I56) system control value to determine how to submit the order API edit. - if selected, the system performs the order edit in asynchronous sequence, or in parallel with the remaining order processing. In this situation, the system continues with order processing and will generate the response message before the order edit completes. The order will remain in an error status and the order ship-to in a suspended status until the order finishes processing through the asynchronous order edit. - if unselected, the system performs the order edit in synchronous, or interactive, sequence. • generates the response message based on the response_type specified in the inbound message. The response_type can indicate to return: - a detailed response message - a detailed response message listing any errors on the order - a summary response message - no response beyond a simple message indicating OK
	• after performing the order edit: - if there are no errors and the Quote field for the order type is unselected, the program puts the order in open or held status, deletes the Order Cross-Reference record, and submits the order to the order async job. - if there are no errors and the Quote field for the order type is selected, the program puts the quote in a quote status and deletes the Order Cross-Reference record. The system does not submit the quote to the order async job since background updates are not performed on a quote until it is converted to an order. - if there are any errors, the program leaves the order in error status and the order ship-to in suspended status. (Note: The ship-to status is the status displayed in standard order inquiry.) - if the inbound order is a duplicate of an existing order and the Reject Duplicate Web Orders (K64) is selected, the order API program checks for a duplicate order with payment and discards it. A response message is returned indicating the order is a duplicate. • determines if the order qualifies for pick slip preparation; see Preparing Orders for Pick Slip Generation.
	Orders in error: If the order does not pass the edit, or if it does not include payment information, it is retained in the Default Batch for E-Commerce Orders in Error (G41). However, if the order_channel is P, the system places the order in the Batch Number for Retail Channel Orders (I78) if it has errors. You can use batch order entry to review, work with, and approve these orders. When the order is accepted, the system clears the batch number from the order header if the batch number matches this system control value and the order displays in regular order maintenance and inquiry.See Batch Orders and Web Orders.
9.	If payment is not sent on an order: If the message does not include payment information, the program puts the order through the order edit process based on the response_type specified in the inbound message: • If the response_type is E, indicating to include information on errors in the response message, the program performs the order edit and returns the response message. The setting of the Delay Order API Edit (I56) system control value determines whether the system submits the order API edit in synchronous or asynchronous sequence. • If the response_type is a value other than E, the program generates the type of response requested (detailed, acknowledgement, or none) and waits to receive an additional message before performing the order edit and attempting to complete the order. Since there are no payment methods on the order, the order remains in an error status. Orders in error remain in a suspended/error status until you use batch order entry to edit and approve the batch.
	If payment is not sent on a quote: If the message does not include payment information and the Quote field for the order type is selected, the program looks at the setting of the pay_incl tag in the message. • If the pay_incl tag is N, the system places the quote in an error status and waits for a second CWOrderIn message that includes the payment information to complete the quote. If a second message is not received, you will need to correct or delete the incomplete quote in batch order entry. • If the pay_incl tag is Y, the system looks at the Pay method required field for the order type. - If the Pay method required field is selected, the system requires a pay method on the quote. If a pay method is not defined, the system places the quote in an error status. You will need to correct the quote in batch order entry. - If the Pay method required field is unselected, the system does not require a pay method on the quote and continues with regular processing.
10.	If an additional message is received: You can send subsequent messages to complete an order with payment information or update an order with errors: • If the subsequent message is flagged payment_only, the program adds the payment information to the order and submits it to the same processing as if the order had been submitted in a single message. • If the subsequent message is not flagged payment_only, then the program deletes the existing order and recreates it using the information provided in the inbound message. As a result, it is important that the subsequent message include all information required to complete the order, or the information that was not included in the subsequent message will be lost. Note: The program identifies the order based on the record in the Order Cross Reference table.
11.	If an order remains incomplete: If the order does not include payment information, it is eligible to be deleted by the ORDER_CLN job once the Time Limit for Suspended E-Commerce Orders (G43) has passed. Note: Because a quote does not reserve inventory and may not require a payment method, the ORDER_CLN job does not include quotes. You will need to manually delete quotes that are incomplete in batch order entry.
12.	Generate order confirmation email? If the order is not in suspended status because of errors, it is eligible to generate an order confirmation email or Outbound Email XML Message (CWEmailOut)based on the criteria described under When Does the System Generate an Email Notification?. If the order has errors, then the Suppress Order Confirmations for Orders in Error (K09) system control value indicates whether to generate the order confirmation or CWEmailOut message, or wait until you correct the order and it is processed by the ORDR_ASYNC background job. Generate quote confirmation email? If the Quote field for the order type is selected and the quote is not in suspended status because of errors, it is eligible to generate a quote confirmation email or Outbound Email XML Message (CWEmailOut) based on the following criteria: • The Quote field and Email notification field for the order type on the quote are selected, and • The Opt in/out setting for the sold to customer on the quote is O1 or O2, and • An email address is defined for the quote or sold to customer. Note: The system does not generate an order confirmation for a quote until it is converted to an order; see Converting Quotes to Orders.

Logging: The order API program writes the inbound and outbound messages, plus any errors, to the ORDER.log file, depending on your logging level. See Logs for more information.

Features not supported: Interactive order entry features that require the operator to make a selection from a pop-up window are typically not supported through the generic order interface. For example, the following are not supported:

• variable sets

• item comments

For more information: See Discounted and Added Items in the CWOrderOut Response Message for a listing of discount and free gift options, indicating whether the order API supports them.

Set items: To include a set (other than a variable set) on an order created through the generic order API, the inbound order message should include the master set item only, and none of its components. The set item is “exploded” once the order is created, adding all of the components to the order just as it would in interactive order entry.

Zone reservation items: If an item is subject to zone reservation, the system applies the Standard Zone Reservation Rules or Alternate Zone Reservation Rules based on your setup. However, if the zone reservation rules that apply to the item would normally display the Select Order Line Option Window in order entry, the system always adds the item as a future order. See Shipping Zone Reservation Overview for a complete discussion.

Suppressing Deposits and Refunds

You can use the suppress_deposit_flag and the suppress_refund_flag to suppress processing of deposits and refunds for orders you receive through the generic order interface. For example, it might not be appropriate to process a deposit or generate a refund for a retail outlet order if the transactions have already taken place at the store.

What happens when you set these flags? When the system creates the order, it sets the corresponding flags for the Order Payment Method. You can review the settings of the Suppress refund and the Suppress deposit flags at the Display Order Pay Type Screen (1 of 2).

Note: Regardless of the setting in the message, the Suppress deposit flag for the order payment method is selected only if the payment method is a credit card.

Suppressing the deposit: If the suppress_deposit_flag is selected in the message, the first time you bill a shipment against the payment method, the system sets the Suppress deposit flag for the Invoice Payment Method to selected. This setting prevents the invoice payment method amount from being included the next time you use Processing Auto Deposits (SDEP) for the related authorization service.

Note: Once the system has billed the first shipment against an order payment method, it sets the Suppress deposit flag for the payment method to unselected. Future shipments against the payment method will be eligible for deposit.

Suppressing refunds: If the suppress_refund_flag is selected in the message, the system prevents 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 (canceled).

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; however, you will need to process any cancel-pending refund for the payment method before you can deactivate the payment method on the order. See Working with Refunds, Writeoffs and Balances Due (WREF) for information on reviewing and working with refunds.

Creating a Quote through the Order API

The system considers an order received through the order API a quote if the Quote field for the order type on the order is selected. In this situation, the system performs the same validations as it does for a regular order and also validates that the quote is a valid quote.

You can send a quote through the order API using the one-pass or two-pass option.

If the message does not include payment information and the Quote field for the order type is selected, the program looks at the setting of the pay_incl tag in the message.

• If the pay_incl tag is N, the system places the quote in an error status and waits for a second CWOrderIn message that includes the payment information to complete the quote. If a second message is not received, you will need to correct or manually delete the incomplete quote in batch order entry.

• If the pay_incl tag is Y, the system looks at the Pay method required field for the order type on the quote.

- If the Pay method required field is selected, the system requires a pay method on the quote. If a pay method is not defined, the system places the quote in an error status. You will need to correct the quote in batch order entry.

- If the Pay method required field is unselected, the system does not require a pay method on the quote and continues with regular processing.

CWOrderOut Response message: The CWOrderOut Response message for a quote does not include any item availability information since the system does not reserve inventory on a quote.

Quotes that fail web order validation: If a quote received through the order API fails validation, the system treats the quote the same as a regular order: The system updates the Status of the quote to E (Error) and places the quote in the e-commerce error batch. You can review the quotes in error on the Work with Orders within a Batch Screen.

The system performs the following validation specifically for quotes:

• The quote cannot contain an express-bill ship via: Invalid Ship Via.

• The quote cannot contain a negative order line: Price cannot be negative.

• The quote cannot contain more than one ship to customer. If more than one ship to customer is defined, the system assigns the first ship to customer to the quote and ignores any other ship tos that are passed in the message.

• The quote cannot contain a cash/check pay type: Invalid Pay Type.

Quote confirmation: When a quote is created through the order API, the system sends a Quote Confirmation email if:

• The quote passes web order validation, and

• The Quote field and Email notification field for the order type on the quote are selected, and

• The Opt in/out setting for the sold to customer on the quote is O1 or O2, and

• An email address is defined for the quote or sold to customer.

See Quote Confirmation Email Sample and Contents for a sample.

Quote form: The system does not automatically print a quote form for a quote received through the order API. You can print a quote form for the quote through the Print/Email Quote Window.

Quote maintenance, cancellation, and conversion: The order API allows you to create new quotes; you cannot maintain, cancel, or convert a quote to an order using the order API. These functions are available in Order Management System. See:

• Maintaining Quotes in Order Maintenance

• Cancelling a Quote through Order Maintenance

• Converting Quotes to Orders

Entering Pre-Order Quotes for an overview and required setup

Processing a Return

You can use the generic order interface to process a return by specifying a negative order line quantity.

Other information used to process a return (see the descriptions of each attribute in the Item element for a complete description of each):

• line_warehouse: indicates the warehouse where the returned merchandise is placed. There must be a record of the item in this warehouse, or the order will be in error with a reason of Item not valid for whs.

• location: indicates the location where the returned merchandise is placed. If the item has not been previously placed in this location, the system creates an Item Location record.

• return_reason: Used to track the return; use the Display Order Line History Screen to review the return reason code used for an order detail line.

• return_disposition: Used to indicate how to process the return. If the message does not specify a valid return disposition value, the system uses the return disposition code defined in the Default Disposition Code (C18) system control value. Note: The system uses this return disposition code to determine whether the return updates inventory and the warehouse and location to which the item is returned; however, the system does NOT store this return disposition on the RA Detail record.

Return processing: The system uses the same general rules for processing a return as when you use the Enter Return/Exchange Reason Window. See Posting a Return or Exchange Through Order Entry for more information.

When you process a return through the generic order interface, it does not generate an order confirmation email, although it might generate a return confirmation email. See Working with E-Mail Notification Templates (WEMT) for more information on email generation and logic.

Return authorization download triggers: If the Create Return Download Triggers (K28) system control value is selected, the system creates a return authorization download (RAD) trigger when you post a return using the generic order interface, based on the trigger rules defined for the Return Authorization Download (RETURN_OUT) integration layer job. The RETURN_OUT integration layer job monitors for return authorization download triggers and generates a Return Authorization Outbound XML Message (CWReturnRAOut) to send the return authorization information to a remote system. See Outbound Return API for an overview.

Performing Credit Card Tokenization on Web Orders

Credit card tokenization allows you to replace the credit card number with a token provided by the service bureau.

Order Management System calls the tokenization process for a web order if the Use Credit Card Tokenization (L18) system control value is selected, the Request token field for the service bureau defined for the pay type is selected, the Card type for the pay type is C Credit Card, and the already_tokenized tag for the credit card payment in the Inbound Order XML Message (CWORDERIN) is N or blank.

For more information: See the Data Security and Encryption Guide for processing details.

Performing Online Credit Card Authorization on Web Orders

Online credit card authorization allows you to send and receive the information required to authorize a credit card at the time the order is placed instead of at the time the pick slip is generated for the order.

The system performs online authorization when Order Management System receives the web order after determining if the order should go on hold, applying any discounts and promotions to the order, and performing credit card tokenization. If the order is placed on hold, the system does not perform online authorization for the web order; the order will go out for authorization during batch order entry.

If the order is eligible to receive a credit card authorization during order entry, the system sends the amount requiring authorization to the service bureau and waits for a response.

The service bureau sends back a response code, authorization code, AVS response code (if you are performing AVS verification), CID response code (if you are performing credit card identification verification), and date. Also, if a hold reason code has been defined for the vendor response received, the system places the order on hold.

Note: In order to perform online authorization on web orders, the Online Authorization setting for the order type on the web order must be set to Without Window.

Credit cards requiring authorizations less than $1.00: If the credit card amount to authorize is less than $1.00 and the Authorization Number for Authorizations Under $1.00 (I08) system control value specifies an authorization number, the system does not send the credit card to the service bureau for authorization; instead, it assigns the authorization number from the system control value. If the system control value is blank, the system sends the credit card to the service bureau for authorization, regardless of the amount that requires authorization.

Performing Online Verification Only: If the Online Auth Verification Only (I96) system control value is selected, the system processes online authorizations for $1.00 for the purpose of validating the card. During batch authorizations, the system authorizes the card for the shippable dollar amount and voids the online authorization for $1.00.

For more information: See Performing Online Credit Card Authorizations for an overview of the online credit card authorization process and the required setup.

Creating Authorization History for Orders Authorized on the Web

Order Management System creates an authorization history record with a status of A (Approved) for an order that received an approved credit card authorization on the web storefront if an auth_number and auth_amount are defined for the credit card payment on the order. If an auth_date, transaction_id, vendor_response, avs_response, or cid_response is defined for the credit card payment, the system also updates the authorization history record with this information.

If an authorization amount is not defined: If an auth_number is defined for the credit card payment but an auth_amount is not defined, the system:

• creates the authorization history record with a status of D (Declined) since an authorization amount was not defined.

• During pick slip preparation (see Applying Pick Slip Preparation to an Order), the system creates a new authorization history record in a G Generated status, using the information from the declined authorization and the Total Order Amount on the Pick Control Header as the authorization amount. If an auth_date is not defined, the system defaults the current date to the manual authorization. Once a pick associated with a manual authorization is printed, the system updates the status to A Authorized. However, during pick slip generation, if the approved authorization amount is less than the amount required during pick slip generation, the credit card payment will go out for batch authorization for the difference.

If an authorization date is not defined: If an auth_number and auth_amount is defined for the credit card payment but an auth_date is not defined, the system creates the authorization history record with a status of A (Approved) and defaults the current date as the authorization date.

If an authorization number is not defined: If an auth_number is not defined for the credit card payment, but an auth_date, auth_amount, transaction_id, vendor_response, avs_response, or cid_response is defined, the system:

• does not create an authorization history record.

• if the order is eligible for online authorization, the system sends the credit card payment to the service bureau for authorization and creates an authorization history record based on the results returned for the service bureau. See Performing Online Credit Card Authorization on Web Orders.

• if the order is not eligible for online authorization, the system sends the credit card payment to the service bureau during batch authorization. See Using Batch Authorization.

Vendor response processing: Before the order is accepted and placed in an open status, the system:

• Looks at the CC Vendor Response table for the authorization service defined for the credit card payment method to find a match to the vendor_response, avs_response, and cid_response from the authorization service. If the response is associated with a hold reason, or the vendor_response, avs_response, or cid_response does not exist in the CC Vendor Response table, the system:

- places the order on AT Declined Credit Card hold.

- places the payment method on the hold reason defined in the CC Vendor Response table. If the response does not exist in the CC Vendor Response table, the system places the payment method on AV Invalid Response Code hold.

- If the credit card is approved, but is placed on AVS or CID hold, updates the status of the authorization history record to O Authorized But Not Used.

See Hierarchy for Placing the Credit Card On Hold.

• If an entity dollar limit by item class or postal code is defined for the response code, the system:

- places the order on hold using the hold reason defined for the entity dollar limit if the authorization amount exceeds the dollar limit. See Vendor Response Processing above for the updates the system performs.

- releases the order from AVS hold if the authorization amount is less than the dollar limit.

See Entity Setup for an overview.

Note: If the order fails web validation, the system places the order in an error status in batch order entry; in this situation, the system determines if the order should be placed on hold for the response code received from the authorization service when you edit and accept the order batch.

Viewing authorization history: You can review authorization history for an order on the Display Authorization History Screen in Order Inquiry.

Expired authorizations: If the authorization for the web order has expired by the time you run pick slip generation for the order, the system will resend the credit card payment method to the service bureau for authorization during pick slip generation.

Transaction ID in deposit transactions: If a transaction ID is defined for an authorization history record, the system includes the transaction ID in the deposit transaction to provide a link between the authorization and deposit transaction.

Typical Order Interface Scenarios

Some typical uses of the generic order interface are described below. Additional information on setup and specific values in the Inbound Order XML Message (CWORDERIN) are provided later in this topic.

Retail point-of-sale transaction: In this example, you receive sale information from a retail location. It is not necessary to send an acknowledgement, reserve or ship inventory, or process deposits. The typical inbound order message scenario includes:

• messages are sent in batch at a scheduled time each day

• no acknowledgements are necessary

• payment information is included for each order and not sent in a separate message

• the item number might not be included in the message; instead, a related value, such as a product ID, is used to look up the item

• order lines do not affect inventory, an express-bill ship via is used and the retail warehouse represents the store

• order lines are not repriced in Order Management System; the pricing provided in the message is used

• no upselling or promotions apply

• deposits and refunds are suppressed

• if an order is prepaid, the payment amount is the same as the order total (to prevent refunds from being generated)

• when setting up the process queue for these orders, it is not necessary to create multiple inbound sessions

Remote order entry service: In this example, you receive orders that were entered at a remote call center. It is not necessary to acknowledge the order, although you must perform all normal order processing. The typical remote order entry message scenario is similar to the retail point-of-sale information, except:

• a regular ship via, rather than an express-bill ship via is used; order lines do affect inventory

• deposits or refunds are not suppressed

• if an order is prepaid, the actual check amount is indicated

E-commerce order: In this example, you receive orders entered by customers at your web storefront. It is necessary to acknowledge the order and perform all order processing, such as shipment and deposits, just as if you had taken the order by phone or mail. The typical inbound order message scenario includes:

• orders are sent interactively, not in batch

• Order Management System item information has been sent to the web storefront, so the item and SKU code is included in the message

• promotions and discounts can be offered as long as they do not require pop-up windows

• payment information for an order might be included in one message, or sent in a separate message (see Sending a Separate Payment Message)

• when setting up the process queue for these orders in Working with Integration Layer Processes (IJCT), you might create multiple inbound sessions to avoid delays for customers at your web storefront

• if the Reject Duplicate Web Orders (K64) system control value is selected, the system matches the order_number field of the inbound message to the e-commerce order number in the Order Header Extended table. If they match and both orders contain payment information, the order is discarded as a duplicate.

Sending a Separate Payment Message

You can receive the entire order in a single message, or receive the payment information in a separate message from the rest of the order. You might want to receive the payment information separately if you are processing orders from your web storefront; in this situation, receiving the payment information separately allows you to first generate a detailed order acknowledgement listing all of the information received to date from the web storefront, including availability and non-payment related discounts, so you can display this information to the customer before requiring entry of payment.

What does the initial order message consist of? When the payment information will be received after the rest of the order, the initial order message includes all of the typical header-level and detail-level information except the Payments element, and the Header element includes:

• payment_only: set to N

• response_type:

- set to D to generate the Detailed Order XML Response (CWORDEROUT) without listing any errors found on the order;

- set to A to generate the Order Acknowledgement XML Message (CWORDEROUT);

• pay_incl: set to N

What does the payment-only order message consist of? The payment-only message includes the Message element, the Payments element, plus the following attributes in the Header element:

• company_code

• one or both of the following:

- rdc_order_nbr: the Order Management System order_id, which is included in the order response message

- order_number: the order number identifying the order in the external system (the e-commerce order number or cross-reference number.

See below for more information on how Order Management System identifies the order.

• payment_only: set to Y

• response_type:

- set to D to generate the Detailed Order XML Response (CWORDEROUT);

- set to E to generate the Detailed Order XML Response (CWORDEROUT), listing errors found on the order;

- set to A to generate the Order Acknowledgement XML Message (CWORDEROUT)

- set to N to not generate a response

• pay_incl: set to Y

Note: If the Reject Duplicate Web Orders (K64) system control value is selected, sending payment as described above does not result in the order being considered a duplicate.

What if Order Management System cannot identify the order? To identify the order when it receives the payment-only message, the order API uses the following rules:

• Match on Order Management System order number?

- If the message includes both the rdc_order_nbr (Order Management System order number), apply the payment to the order that matches the specified order number. In this situation, even if the message includes the order_number (e-commerce order number or cross-reference number), but it does not match the order cross-reference assigned to the Order Management System order, the order API can still apply the payment to the correct order.

- If there is an order that matches the rdc_order_nbr, but it already has a payment method, return the regular response message based on the response_type, as described above; however, in this situation, the order API does not update the order.

• Match on e-commerce order number?

- If no order matches the rdc_order_nbr, or if the rdc_order_nbr is not included in the message, apply the payment to the order that matches the order_number (e-commerce order number or cross-reference number).

- If there is no order that matches the order_number, or if the matching order already has a payment method, return the error: <Message>Error: The order could not be located.</Message>

Order API Setup Requirements

Overview: In addition to the setting of any Order API-Related System Control Values, the setup required for the generic order interface consists of the following.

CWOrderIn Web Service

The CWOrderIn web service allows an external system to post the Inbound Order XML Message (CWORDERIN) 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.

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

If you are using the CWOrderIn SOAP-based web service: The endpoint specified in the CWOrderIn.wsdl file is where you need to post messages in order for the CWOrderIn web service to process them. The endpoint is typically set to http://server:port/CWDirectCPService/services/CWOrderIn, where server:port identifies the application server where the wsdl is located and CWOrderIn is the name of the web service to call.

The CWOrderIn 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[

</Payments>

<Items>

</Items>

</ShipTo>

</ShipTos>

</Header>

</Message>

]]>

</dom:performAction>

</soapenv:Body>

</soapenv:Envelope>

CWMessageIn Web Service

You can use the CWMessageIn Web Service to route Order In 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.

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.

ORDER_IN Process and Process Queues

If you integrate with external systems that require reading from or writing to queues, use Working with Integration Layer Processes (IJCT) to set up the ORDER_IN process and create a process queue for each order channel, such as a web site or a remote order entry service.In this situation, each process queue monitors a separate queue for incoming messages.

Note: Creating the process queues is not required if you receive and send messages using the ORDER_IN web service (default setting).

Message version: Use the Working with Integration Layer Processes (IJCT) to specify the version of the outbound CWORDERDEROUT response message to generate.

Default User for ORDER_IN

Your default user is used to determine secured feature authority and the default Entered by user to write to the Order Header.

Used how?

• Each time the order API receives an order that is in error, it generates a copy of the Order Error Listing report. You can review the generated reports by advancing to the Document Management screen for your default user.

• Your default user is the Entered by user on the Order Header if the CWOrderIn message does not specify an entered_by_user.

• The authority settings of your default user control some of the edits that apply to the order API:

- your default user’s authority under the Override Price Override Limit (A64) controls whether to put an order in error status when it exceeds the Price Override Limit Percent (E55).

- your default user’s authority under the Allow Maximum Order Line Value Override (A69) controls whether to put an order in error status when it exceeds the Maximum Order Line Value (E98).

- your default user’s authority under the Allow Maximum Order Quantity Override (A70) controls whether to put an order in error status when it exceeds the Maximum Order Quantity (C60).

See Working with User Records (WUSR) for information on setting up users; see Order Creation Errors for a listing of possible errors, including those related to secured feature authority; and see Setting Up Secured Features for general information on secured features, including the secured features that apply to creating orders.

Order API-Related System Control Values

Overview: Most system control values that affect interactive order entry also control the generic order interface. Please note the following values whose function in the generic order interface differs from regular order entry.

System Control Value	Function in Generic Order Interface
Create/Assign Bill To Customers in Order Entry (A76)	Having this system control value unselected does not prevent you from specifying an existing bill-to in the message and assigning it to the order.
Default Source for Internet Orders (E65)	If no source code is specified at the header or on a detail line in the message, this value defaults.
Require Salesrep Number in Order Entry/Order Maintenance (E87)	When this value is selected, the order will be in error if the system cannot resolve the sales rep. See Selecting the Sales Rep.
Remote Order Values (F70)	The system uses these values when matching a sold-to customer. See Customer Sold To Selection, Creation and Update.
Get Orders from E-Commerce (G35)	When this value is selected, the ORDER_CLN job purges “abandoned” (partially created) e-commerce orders after the Time Limit for Suspended E-Commerce Orders (G43) has elapsed.
E-Commerce Order Type (G42)	If no order_type is specified in the message, the system uses this value. Also, the system uses this system control value to identify e-commerce orders for the purposes of email generation, putting the order on hold based on the Maximum Order Amount for E-Commerce Orders (H54), and cleanup of suspended (“abandoned”) orders.
Time Limit for Suspended E-Commerce Orders (G43)	Defines the number of minutes to wait before an “abandoned” (partially created) order is eligible for cleanup.
Default Batch for E-Commerce Orders in Error (G41)	Any order API orders in error are assigned to this batch number, so that you can correct them through batch order entry.
Order Acknowledgement Program (G50)	The program to use for generating order acknowledgment emails.
Shipment Confirmation Program (G51)	The program to use for generating shipment confirmation emails.
Price Override Reason for E-Commerce (G73)	The price override reason code to use if you process price overrides on order API orders.
Backorder Notification E-Mail Program (G95)	The program to use for generating backorder notice emails.
Soldout Notification E-Mail Program (G96)	The program used to generate soldout notification emails.
Default Opt In/Opt Out Flag (G97)	The default Opt in/Opt out setting to use when creating a new customer, indicating the customer’s preferences regarding contact by email.
Credit Card Credit Acknowledgement E-Mail Program (H08)	The program used to create credit card credit acknowledgement emails.
Default Salesrep for E-Commerce Interface (H24)	The salesrep number to default to e-commerce orders if the Require Salesrep Number in Order Entry/Order Maintenance (E87) system control value is selected. See Selecting the Sales Rep.
E-Mail Order Confirmations for All Orders (H51)	Defines whether Order Management System sends an email confirmation when any order is accepted or only when a customer on the web storefront accepts an order.
E-Mail Shipment Confirmations for All Orders (H52)	Defines whether Order Management System sends an email confirmation when any order or return is shipped or only when an e-commerce order or return is shipped.
Return Confirmation E-Mail Program (H53)	The program to generate email, rather than printed, return confirmations.
Maximum Order Amount for E-Commerce Orders (H54)	Orders that exceed this merchandise total go on EH hold. Note: The Maximum Order Amount (A92) system control value does not put generic order interface orders on hold; however, you must specify an amount for this system control value in order for evaluation based on the Maximum Order Amount for E-Commerce Orders (H54) to take place in the order API.
Delay Order API Edit (I56)	Indicates whether the order edit and accept runs interactively or asynchronously for orders received through the Generic Order Interface (Order API).
Batch Number for Retail Channel Orders (I78)	If the order_channel is P, the system places the order in this order batch if it has errors. You can correct the errors in batch order entry.
Suppress Order Confirmations for Orders in Error (K09)	Controls whether the order API generates an order confirmation regardless of whether the order is in error. If this system control value is selected and the order is in error, the order confirmation is not generated until you correct any errors and the ORDR_ASYNC background job processes the order; otherwise, if this system control value is unselected, the order API generates order confirmations for all eligible orders, regardless of whether there are errors.
Reject Duplicate Web Orders (K64)	Controls whether the order API creates a duplicate web order. If this system control value is selected, the system matches the inbound order_number field with the order number in the e-commerce Order Header Extended table. If both orders contain payments, the inbound order is a duplicate and an error response message is sent. However, if the order numbers match but one order does not contain the payment method; the inbound order is not a duplicate and the existing order is updated or replaced. If this system control value is unselected, the order API creates duplicate web orders.

Customer Creation, Matching and Update Logic in the Order API

Customer Sold To Selection, Creation and Update

The system uses the following basic logic in selecting a sold-to customer for the order (see below for exceptions and examples):

1.	Customer number: If a valid customer_number is specified in the message, use that customer; otherwise,
2.	Alternate customer number: If an alternate_sold_to_id is specified in the message (but no valid customer_number): • If there is just one customer whose Alt cust # or Alternate customer # cross-reference (see Working with Alternate Customer Number Cross-References) matches the alternate_sold_to_id, use that customer; otherwise, • If there are any customers with matching Alt cust #’s, use the customer with the highest customer number (most recently created customer); otherwise, • Use the customer with the matching Alternate customer # cross-reference with the highest customer number (most recently created customer); otherwise,
3.	Evening phone: If the Include Telephone Number in Customer Search (I20) system control value is selected, and a sold_to_eve_phone is specified in the message (but no valid customer_number or existing alternate_sold_to_id): • If there is just one customer whose Evening phone number matches the sold_to_eve_phone, use that customer; otherwise, • Of the customers with matching Evening phone numbers whose name and address information matches the information in the message (using the matching rules specified through the Remote Order Values (F70) system control value), use the matching customer with the lowest customer number (customer created first); otherwise,
4.	Daytime phone: If the Include Telephone Number in Customer Search (I20) system control value is selected, and sold_to_day_phone is specified in the message (but no valid customer_number, existing alternate_sold_to_id or sold_to_eve_phone): • If there is just one customer whose Day phone number matches the sold_to_day_phone, use that customer; otherwise, • Of the customers with matching Day phone numbers whose name and address information matches the information in the message (using the matching rules specified through the Remote Order Values (F70) system control value), use the matching customer with the lowest customer number (customer created first); otherwise,
5.	Name and address match: If none of the above matches work, use the matching rules specified through the Remote Order Values (F70) system control value to search for a customer who matches the name and address information specified in the message. Note: When matching on street address or address line 2, the system does not include the roadway descriptive in the match if it is the last word in the address line; see Exact Match Required on Street Address for Remote Orders (F73) and Exact Match Required on Address Line 2 for Remote Orders (F75) for a list of road descriptives the system excludes. • If there is just one customer who matches the name and address information, use that customer; otherwise, • If there are multiple customers who match the name and address information, use the customer with the highest customer number (most recently created customer); otherwise,
6.	Create customer: If there is no matching customer, create a new customer for the order. If the message does not include complete, valid information on the customer’s name and address, the order will be in error.

After searching based on alternate customer number, the system searches based on evening and daytime telephone number only if the Include Telephone Number in Customer Search (I20) system control value is selected/

Ghost customer: If the customer selected through the process described above is flagged as a Ghost, the system creates the order using the target customer with whom the ghost customer was merged (identified through the Customer number cross-reference field in the Customer Sold To table). For example, if the above process selects customer 123, and customer 123 has been merged with customer 456, the order is created for customer 456. In making this assignment, the system does not check that the name or address information for customer 456 matches the information in the message.

Updating the customer: The system always updates the following fields if they are provided in the message:

• alternate customer number

• phone numbers (daytime, evening, or third number (fax or mobile))

• opt-in/out flag

• rent flag

• mail flag

• customer class

• customer price group (provided the customer is not already assigned to a price group). If you do not assign a customer price group to a customer, the system assigns the customer price group defined in the Customer Price Group Code for CPG Pricing Only (L58) system control value to the customer.

The following flags in the Inbound Order XML Message (CWORDERIN) control any additional updates to the customer:

• If the sold_to_address_ update flag is selected and address information is provided in the message the system updates:

- Customer name (prefix, first name, middle initial, last name, suffix, company)

- Address (Address lines 1-4, city, state, zip, country)

- Delivery code (if no sold_to_busres is specified in the message, the system uses the Default Delivery Code for New Order Entry Customers (D13))

- Day, evening, and third (fax or mobile) phone numbers

Note:

• The system does not update the customer address if it finds a match based on a phone number of customer name and address match.

• When the system does update the customer’s name and address, it updates it completely; however, if no phone numbers are provided in the message, the system does not clear the customer’s existing phone numbers.

• If the sold_to_email_update flag is selected, the system updates the email address at the customer sold-to level and in the Customer Sold To Email table. The email provided in the message becomes the customer’s primary email address.

• The setting of one flag does not control the effect of the other. For example, even if the sold_to_address_update flag is set to N, the system still updates the email address if the sold_to_email_update flag is selected.

• If the customer_number passed in the message is not valid, the system does not put the order in error; instead, it continues through the customer search and matching logic.

See Creating and Updating Sold-to Customers (WCST) for a discussion of each of these fields.

Oracle Retail Customer Engagement customer integration: When you use the Oracle Retail Customer Engagement customer integration, if you create or update a customer through the order API, Order Management System sends the information about the customer to Oracle Retail Customer Engagement so that the customer records in the two systems are synchronized. See the Customer Engagement Customer Integration for more information.

Creating or Selecting Shipping Addresses or Customers

In addition to the customer sold-to address, there are three types of shipping addresses for an order. Each is described in the following table.

Van delivery processing: When an order is received through the generic order interface, the system evaluates the shipping address defined for the web order to determine if it qualifies for van delivery, and if it does, performs several updates to the order.See Van Delivery Processing through the Generic Order Interface (Order API) and Van Delivery Processing for an overview.

The rules for matching an existing customer or creating a new customer are summarized below.

Description	How to add in Inbound Order Message
Defining an order-level shipping address on a web order
An order-level shipping address is specified just for a particular order. This is the type of shipping address that you create by selecting Order Ship To at the Work with Order Screen.	• ship_to_type or Default Recipient Type for E-Commerce Orders (H33) = 1 • customer_ship_to_number = blank • ship-to name and address attributes (starting with ship_to_prefix) = must provide a valid shipping address for the order • permanent_ship_to_number = blank
Defining a recipient customer on a web order
A recipient customer is another customer sold-to, different from the customer who places the order, who receives all or part of the order. This is the type of shipping address that you create or select by selecting Sold To/Recip at the Work with Order Screen, or selecting Accept/Add Rcp or Sold To/Recip at several screens in order entry.	Existing customer: • ship_to_type or Default Recipient Type for E-Commerce Orders (H33) = 2, and, • customer_ship_to_number = valid customer number, or • ship_to name and address attributes (starting with ship_to_prefix) = must match an existing sold-to customer Note: If the system does not find a matching customer using the information listed above, it creates a new customer sold-to to use as the recipient customer for the order. • permanent_ship_to_number = blank New customer: • ship_to_type = 2 • customer_ship_to_number = blank • ship_to name and address attributes (starting with ship_to_prefix) = must provide a valid shipping address to create the new customer sold to • permanent_ship_to_number = blank Note: If the ship_to name and address provided in the message are an exact match to an existing sold-to customer based on the fields specified with the Remote Order Values (F70), the system uses the existing customer for the order.
Defining a permanent shipping address on a web order
A permanent shipping address is permanently attached to the customer sold-to; you can track order and item history for each permanent shipping address as well as for the sold-to customer. This is the type of shipping address that you create or select by selecting Ship To at the Work with Order Screen.	Existing permanent ship-to: • ship_to_type or Default Recipient Type for E-Commerce Orders (H33) = 3 • customer_ship_to_number = number of the sold-to customer for the order • permanent_ship_to_number = valid permanent ship-to number for the sold-to customer Note: If the ship_to name and address information is provided, the system uses it to create a new permanent ship-to for the sold-to customer only if it cannot find an existing permanent ship-to using the other information provided, and if the ship-to name and address information does not match an existing permanent ship-to for the sold-to customer. New permanent ship-to: • ship_to_type or Default Recipient Type for E-Commerce Orders (H33) = 3 • customer_ship_to_number = number of the sold-to customer for the order • ship_to name and address attributes (starting with ship_to_prefix) = must provide a valid shipping address to create the new permanent ship-to • permanent_ship_to_number = blank Note: If the ship-to name and address provided in the message are an exact match to an existing permanent ship-to customer, the system uses the existing customer for the order.

Summary:

• Matching an existing customer: The system uses the ship_to name and address attributes to match an existing customer or permanent ship-to as follows:

- customer sold-to (recipient customer): When the ship_to_type is 2 and the system cannot select a customer based on the customer_ship_to_number, the system selects an existing sold-to customer as the order recipient if the ship_to name and address information in the message is an exact match based on the fields specified with the Remote Order Values (F70).

- permanent ship-to: When the ship_to_type is 3 and the system cannot select a permanent ship_to based on the customer_ship_to_number and permanent_ship_to_number, the system selects an existing permanent ship-to for the order if the ship_to name and address information in the message is an exact match based on the fields specified with the Remote Order Values (F70).

The system does not update an existing recipient or permanent ship-to customer based on the information in the ship_to attributes.

• Creating a new customer: The system uses the ship_to name and address attributes to create a new customer or permanent ship-to as follows:

- customer sold-to (recipient customer): If the ship_to_type is 2 and the system cannot select a customer based on the customer_ship_to_number, and if the ship_to name and address information do not match an existing sold-to customer based on the fields specified with the Remote Order Values (F70), the system uses the information to create a new sold-to customer for the order recipient.

- permanent ship-to: If the ship_to_type is 3 and the system cannot select a permanent ship_to based on the customer_ship_to_number and permanent_ship_to_number, and if the ship_to name and address information in the message are not an exact match to an existing permanent ship-to for the sold-to customer based on the fields specified with the Remote Order Values (F70), the system uses the name and address information to create a new permanent ship-to for the order.

Customer Bill To Selection and Creation

The system uses the following logic in selecting a bill-to customer for an order:

1.	If a valid bill_to_number is specified in the message, use that bill-to customer on the order; otherwise,
2.	If there is bill-to name and address information specified in the message: • If that information matches a single existing bill-to customer based on the Remote Order Values (F70), use that bill-to; or, • If that information matches more than one existing bill-to customer based on the Remote Order Values (F70), use the bill-to customer created the most recently (highest bill-to number); or, • If that information does not match an existing bill-to customer, create a new bill-to using the information in the message; otherwise,
3.	Use the valid Bill to number currently assigned to the sold-to customer, if any; otherwise,
4.	Search the Customer Bill To table for a bill-to customer that matches the name and address of the sold-to customer; if there is more than one match, use the bill-to with the highest number (bill-to created last); otherwise,
5.	Create a new bill-to customer based on the sold-to customer information. In this situation, the new bill-to number is also assigned to the customer sold-to as well as to the order.

Note:

• The system does not update an existing bill-to customer through the Inbound Order Message.

• The bill-to information, if any, provided in the message is used on the order, regardless of whether the customer sold-to is already assigned to another bill-to.

• When the system creates a new bill-to based on the sold-to information in the message and the customer sold-to is not already assigned to a bill-to, the sold-to will be assigned to that bill-to.

• The bill-to assignment takes place regardless of the setting of the Create/Assign Bill To Customers in Order Entry (A76) system control value and regardless of whether the customer placing the order is a new or existing customer.

Resolving the Item and SKU in the Order API

For each order detail line, the system determines the item and SKU to use by checking the following attributes in the sequence indicated:

1. item_id and sku

2. short_sku_number

3. retail_ref_number

4. upc_type and upc_code

5. alias_item

If any of the attributes listed above is blank or invalid, the system checks the next attribute in the order indicated.

If all of the attributes listed above are blank or invalid, the order is suspended with the error, Base item does not exist.

Note: You cannot use the SKU cross reference set up through Maintaining SKU Cross Reference Codes (MSKR) to identify an item and SKU through the order API.

For more information:

• item and SKU codes: Create Item Screen and Create SKU 1 of 2 (With Overrides) Screen

• short SKU number: Short SKU

• retail reference number: Reference #

• upc type and code: Work with UPC Codes Screen

• alias: Work with Alias Screen

User-Defined Fields in the CWOrderIn Message

Overview: The Order Header User Field table is available to store information about the order that does not belong in any of the system-defined tables or fields. Although this table is not accessible from a screen, you can create order-related records in this table by passing the information in the CWOrderIn message.

Setup: Before you can process user-defined fields in the CWOrderIn message, you must first create user-defined detail to identify the type of information you expect to receive. For example, in order to use the Order Header User Field table to store an additional external source code for the order, you would use the Create User Defined Field Screen to create a user field record such as:

• File code = OHD

• File description = Order header (or similar description)

You then use the Create User Defined Field Screen to create a user-defined detail record such as:

• Field label = source (or similar label)

• Field type = T (text)

• Field usage = I (input)

The Display sequence field is required, but the setting does not matter in this case, because the user-defined fields are not listed on a screen. However, you need to check the User Defined Field Detail table and determine the Sequence number, because the system uses this number for processing. The Sequence number is not listed on any screen.

Note: You can set up and use as many user-defined field types as you want for the Order Header User Field table, although you can receive and store only one field of each type for an order. For example, you could not receive and store two external Source fields for the same order.

Processing: When the system receives a CWOrderIn message, it compares the user_field_det_seq_number in the message with the Sequence number in the User Defined Field Detail table to determine the format of the user field information received in the message. If there is no sequence number, or the sequence number is invalid, the system compares the user_field_Label in the message with the Field label in the User Defined Field Detail table.

If the system finds a match based on sequence number or label, it creates a record in the Order Header User Field table for the order. If the system does not find a match, or if it finds a duplicate message type, it ignores the information. The system creates no more than one record in the Order Header User Field table for each record type.

Example: You have created a user-defined detail record such as the one described above. The Sequence number is 1. You receive the following information in the new order message:
User Field Information	Matches?
user_field_det_seq_number = 9 user_field_Label = SOURCE	yes, based on label
user_field_det_seq_number = blank user_field_Label = SOURCE	yes, based on label
user_field_det_seq_number = 1 user_field_Label = SRC	yes, based on sequence number
user_field_det_seq_number = 9 *user_field_Label* = SRC	no (neither sequence number or label match)

Selecting the Sales Rep

Overview: The system uses the sales_rep_number and sales_rep_name in the Inbound Order XML Message (CWORDERIN) to determine the correct sales rep to use on the order.

Related system control values:

• Default Salesrep for E-Commerce Interface (H24): When a default sales rep is specified here, the system assigns this rep to orders if it cannot resolve the rep based on the information in the inbound order message.

• Require Salesrep Number in Order Entry/Order Maintenance (E87): When this value is selected, the order will be in error if the system cannot resolve the sales rep.

sales_rep_number	sales_rep_name	Result
blank	specified	• If there is a Default Salesrep for E-Commerce Interface (H24), use that rep on the order. • Otherwise, if: - the sales_rep_name matches an existing rep, use that rep on the order. - the sales_rep_name does not match an existing rep, create a new rep using the next available number, and use that rep on the order.
specified	blank	Uses the sales_rep_number specified in the message on the order; if the number does not match an existing rep, place the order in error: Invalid Salesman Number.
blank	blank	• If there is a Default Salesrep for E-Commerce Interface (H24), use that rep on the order. • Otherwise, the system does not assign a rep to the order. If the Require Salesrep Number in Order Entry/Order Maintenance (E87) system control value is selected, place the order in error because of the missing rep: Invalid Salesman Number.
specified	specified	• If the sales_rep_number matches an existing rep, uses that rep on the order. The system does not update the existing rep with the sales_rep_name specified in the message, even if it is different. • If the sales_rep_number does not match an existing rep, creates a new rep and uses that rep on the order.

Important: The system does not use the Salesrep # (Sales representative number)S specified for the sold-to customer on the order.

Error: If the salesrep is not active, the system places the order in error: Sales Rep Inactive.

Salesrep store: If you do not pass a sales_rep_store and a Home Store is defined for the sales_rep_number assigned to the order, the system defaults this store number to the Originating Store field in the Order Header table. However, if the Home Store defined for the salesrep is inactive, the system places the order in error: Sales Rep Store Inactive.

Creating a salesrep: If the system creates a new salesrep, the system sets the Active flag for the new salesrep in the Salesman table to Y. The system will NOT assign the store number defined for the order to the new salesrep.

Discounted and Added Items in the CWOrderOut Response Message

When order information is passed back to the customer in the CWOrderOut response message, the system includes certain discounts and promotions that have been applied to the order in the Promotion element of the response message.

You can use this information to display to the customer on the web storefront the types of promotions for which the order qualifies, such as a ship via upgrade, reduced or free freight, or free items. You can use this information to simulate the promotion and free gift windows that display during interactive order entry.

Response type: The system includes discounts and promotions that have been applied to the order only in the Detailed version of the CWOrderOut response message. The response_type specified in the Inbound Order XML Message (CWORDERIN) controls whether an order response is generated when the order goes through the edit.

If the response_type is:

• D (detailed): The system sends the Detailed Order XML Response (CWORDEROUT). This message includes any discounts and promotions that have been applied to the order.

• E (errors): The system sends the Detailed Order XML Response (CWORDEROUT), including descriptions of any errors currently on the order. This message also includes any discounts and promotions that have been applied to the order. However, some promotions may not apply to the remote order until the error is corrected in batch order entry. In this situation, the CWOrderOut response message may not reflect all of the promotions that apply to the order.

• A (acknowledgement): The system sends the Order Acknowledgement XML Message (CWORDEROUT). This message does not include any discounts and promotions that have been applied to the order.

• N (no response): The system does not send a response. However, any eligible discounts and promotions have been applied to the order.

Sending payment information separately: If the payment information is sent separately from the rest of the order in the generic order API, the CWOrderOut response message might be generated twice: once when you receive the initial order message and once when you receive the payment information. In this situation:

• Any discounts or promotions that are applied to the order as a result of the pay type on the order are not included in the CWOrderOut response message that is generated for the initial order message. In addition, the Order Audit Discounts that have been applied to the order during the initial order message are stored in the Order Discount Audit Table (OEODIS) until payment information is received and the order is accepted. Once the order is accepted, the system removes the records from the Order Discount Audit table.

• The CWOrderOut response message that is generated after the payment information is received will contain all discounts and promotions that have been applied to the order.

Order confirmation email: The system generates an Order Confirmation email (based on the program defined in the Order Acknowledgement Program (G50) system control value) even if the remote order is in error (E) status, and must be corrected through batch order entry. Depending on the type of error, some promotions may not apply to the remote order until the error is corrected in batch order entry. In this situation, the Order Confirmation email may not reflect all of the promotions that apply to the order.

Special handling: If a package insert item or free gift contains special handling you will need to go into order maintenance to specify the special handling for the item. This is because when the order is received in Order Management System, the system reevaluates the order to see if it still qualifies for the item, and if it does, the system adds the item back to the order.

Freight by weight: If you are using the freight by order weight freight method to calculate freight and the freight for the order changes as a result of adding a new item to an order, the system updates the shipping amount in the CWOrderOut response message. For example, if an item is added to the order as a result of a price table premium or free gift, the system updates the shipping amount to reflect the new item that has been added to the order.

Batch order entry: If a web order contains errors and needs to be corrected in batch order entry, the system reevaluates the discounts and promotions that have been applied to the order when you correct the order in the order batch. Once the order has been corrected and the order batch has been accepted, the system reapplies any discounts and promotions for which the order qualifies and removes the records associated with the orders in the order batch from the Order Discount Audit Table (OEODIS). Note: While you are working with the orders in an order batch, the discounts and promotions that are applied to an order may not represent the final discounts and promotions that are applied to the order once the order batch is accepted. To view the final discounts and promotions that have been applied to an order, review the order in standard order inquiry after the order batch has been accepted.

Discounting and Added Items in the CWOrderOut Response Summary

The following table summarizes when the CWOrderOut response message reflects repricing and free or accompanying items.

Type of Discount	Applies to Web Order?	Reflected in First Response?
Based on Source Code or Offer, or on Item Offer or SKU Offer
free gifts by offer or source code Note: • Free gifts set up for the source code override free gifts set up for the offer. If an order would qualify for both the offer and source code free gifts, only the source code's free gift is added to the order. • If the order qualifies for a free gift by source or offer, but also qualifies for other promotions which bring the merchandise total below the amount required for the free gift, the system removes the free gift from the order. See Work with Offer Free Gifts Screen and Work with Source Free Gifts Screen.	yes	yes; included in the Promotion element (promotion_type_code FG). In addition, the system adds the free gift to the Detail element.
additional charge discount based on offer Note: If the Prorate Dollar Discounts and Coupons (D90) system control value is unselected, the system adds these discounts to the order as a negative additional charge, or credit. However, if this system control value is selected, the dollar discount is applied on a pro-rata basis to each item on the order and is reflected in the selling price. See Work with Offer Dollar Discounts Screen.	yes	yes; included in the Promotion element (promotion_type_code RA) and additional_charges tag if the Prorate Dollar Discounts and Coupons (D90) system control value is unselected; otherwise the discount is reflected in the actual_price for each item in the Detail element.
additional charge discount based on source Note: If the Prorate Dollar Discounts and Coupons (D90) system control value is unselected, the system adds these discounts to the order as a negative additional charge, or credit. However, if this system control value is selected, the dollar discount is applied on a pro-rata basis to each item on the order and is reflected in the selling price. See Work with Source Dollar Discounts Screen.	yes	yes; included in the Promotion element (promotion_type_code SA) and additional_charges tag if the Prorate Dollar Discounts and Coupons (D90) system control value is unselected; otherwise the discount is reflected in the actual_price for each item in the Detail element.
source percentage discount See Create Source Code Screen (1 of 2).	yes	yes; the discount is reflected in the actual_price for the item.
quantity break by item The system reprices items on an order based on quantity break by item only if the Quantity Break/Item (A87) system control value is selected. See Item Volume Discounting.	yes	yes; the discount is reflected in the actual_price for the qualified item.
accompanying items See Work with Accompanying Item Screen.	yes	yes; the system adds the accompanying item to the Detail element.
associate pricing See Second Create Customer Sold To Screen.	yes	yes; the discount is reflected in the actual_price for the item.
Promotions (WPRO)
free freight promotion See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code FF); in addition, the shipping tag is not included since the shipping amount is zero.
freight override promotion See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code FO). In addition, the freight discount is reflected in the shipping tag.
additional charge discount for additional freight promotion See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code AA) and additional_charges tag.
additional charge discount for freight promotion See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code FA) and additional_charges tag.
additional charge discount for order promotion Note: If you specify an additional charge code for the promotion, the discount will appear on the order as a credit additional charge; otherwise, the discount amount is prorated against the items on the order. See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code OA) and additional_charges tag if an additional charge code is defined for the promotion; otherwise the discount is reflected in the actual_price for each item in the Detail element.
additional charge discount for tiered promotion See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code TA) and additional_charges tag.
free gift for tiered promotion Note: If the order qualifies for a free gift for tiered promotion, but also qualifies for other promotions which bring the merchandise total below the amount required for the free gift, the system still applies the free gift to the order. See Working with Promotions (WPRO).	yes	yes; included in the Promotion element (promotion_type_code TG). In addition, the system adds the free gift to the Detail element.
free gift for BOGO (Buy One/Get One Free) promotion	yes	yes; included in the Promotion element (promotion_type_code FB). In addition, the system adds the free gift to the Detail element.
other promotion discounts not applied through an additional charge code or adding a free gift	yes	the discount is reflected in the actual_price for the qualified item.
Price Tables (WPTB)
price table premiums Note: The system automatically adds premium items that are offered as a free item to the order. However, if the premium item is offered at a discounted price, instead of offered as a free item, the system does not automatically add the premium item to the order. See Working with Price Tables (WPTB).	yes	yes if the item is a free item. Included in the Promotion element (promotion_type_code PT). In addition, the system adds the premium item to the Detail element.
price table discounting See Working with Price Tables (WPTB).	yes	yes; the discount is reflected in the actual_price for the qualified item.
Additional Promotions, Free Gifts, Discounts, and Price Breaks
package inserts Note: The system adds package insert items to the order only if the Evaluate Promotional Items/Inserts in Order Entry/Maintenance (E48) system control value is selected. See Package Insert Processing (WPIP).	yes	yes; included in the Promotion element (promotion_type_code PI). In addition, the system adds the package insert item to the Detail element.
price codes Note: The system reprices items on an order based on price codes only if the Price Codes (D93) system control value is selected. See Working with Price Codes (WPCD).	yes	yes; the discount is reflected in the actual_price for the qualified item.
quantity price matrix The system reprices items on an order based on the quantity price matrix only if the Quantity Price Matrix Pricing (K41) system control value is selected. See Working with Quantity Price Matrix (WQPM).	yes	yes; the discount is reflected in the actual_price for the qualified item.
customer percentage discount See Second Create Customer Sold To Screen.	yes	yes; the discount is reflected in the actual_price for the item.
membership discount See Working with Customer Memberships (WWCM).	yes	yes; the discount is reflected in the actual_price for the item.
Relate award amount The system reprices items on the order based on the relate_award_amount included in the ShipTo element of the Inbound Order XML Message (CWORDERIN) only if the amount is .01 or greater and the Use ORCE Loyalty (M06) and Prorate Dollar Discounts and Coupons (D90) system control values are selected. See the Customer Engagement Loyalty Integration, specifically, Applying Awards during the Generic Order Interface (Order API) for more information.	yes	yes; the discount is reflected in the actual_price for the item.
promotional pricing See Work with Promotional Pricing (WPRP).	no	no

Rejecting the Order (Order API)

Purpose: After beginning creation of an order through the order API, the web storefront or other external system can send a message indicating to reject the order, provided no payment information has been sent.

Required information: The reject message (CWORDERREJECT) needs to specify the company code and either the order number or order cross-reference number (web order number) for an existing order. Optionally, the message can include both the order number and the order cross-reference number.

Example:

</Header>

</Message>

Eligible for rejection? To be eligible for rejection through the reject message, the order must currently be in error and not have a payment method. It does not matter if the order has additional errors besides the lack of a payment method.

Response: The API returns a simple response message indicating whether the reject request was successful (pass) or unsuccessful (fail), for example:

Multi-recipient order? When the API receives a reject message for a multi-recipient order, it rejects all recipients. It is not possible to reject a single order recipient.

No separate DTD: The order reject message does not have a separate DTD or schema from the CWOrderIn message; it just needs to specify a type of CWORDERREJECT, while the CWOrderIn message specifies a type of CWORDERIN. See the Inbound Order XML Message (CWORDERIN) and the Order Reject Request Message (CWORDERREJECT) for background.

Update to Deleted Order table: When you process an order rejection through the reject message, the system writes a record in the Deleted Order table. The record includes:

• Company code

• Order number

• Job: ORDREJTAPI

• User ID: your default user

• Program stack: CALLED FROM ORDER API TYPE=CWORDERREJECT - BUILDORDERREJECTBO

• Date deleted: includes the date and time

• Process: Order Reject API

• System date

• Ecommerce order: The E-commerce order number in the Order Header Extended table and in the E-Commerce Order Reference table. From the order_number passed in the Inbound Order XML Message (CWORDERIN).

If no reject message sent: The ORDER_CLN job deletes abandoned orders if no reject message is received. See the Time Limit for Suspended E-Commerce Orders (G43) system control value for background.

Generic Order Interface

Contents

SCVs

Search

Glossary

Reports

Solutions

XML

Index

Order Interface XML Message Formats

Legal

GO01_01 OMSCS 19.0 December 2019 OHC