Chapter 41: Generic Order Interface (Order API)
Purpose: Use the generic order interface to send orders into CWDirect via CWIntegrate. 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
• batching: batched or non-batched orders
• 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 creating a new sold-to, bill-to, individual, or permanent ship-to customer
Order API or e-commerce message? You can use either the CWOrderIn message (generic order API) or the CWCreateOrder message (E-Commerce Order Creation) to create orders in CWDirect. The CWOrderIn message includes additional information that is not part of the CWCreateOrder message. To determine which message best suits your business requirements, compare the information included in each.
Recommended method for processing remote orders: You should use the order API rather than the phone order load to process remote orders because of the superior data security provided by the order API.
In this chapter:
• Order Interface Processing Overview
• Suppressing Deposits and Refunds
• Performing Credit Card Tokenization on Web Orders
• Creating Authorization History for Orders Authorized on the Web
• Performing Online Credit Card Authorization on Web Orders
• Typical Order Interface Scenarios
• Sending a Separate Payment Message
• Related System Control Values
• Customer Creation, Matching and Update Logic
• Customer Sold To Selection, Creation and Update
• Creating or Selecting Shipping Addresses or Customers
• Customer Bill To Selection and Creation
• Order Interface XML Message Formats
• Inbound Order XML Message (CWORDERIN)
• Inbound Order Message: Sample XML
• Detailed Order XML Response (CWORDEROUT)
• Detailed Order Response Message without Errors: Sample XML
• Detailed Order Response Message with Errors: Sample XML
• Order Acknowledgement XML Message (CWORDEROUT)
• Order Acknowledgement Message: Sample XMLs
Order Interface Processing Overview
A typical generic order interface process includes the following steps:
1. An order, or group of orders, is sent from a remote system (such as a web storefront, retail point-of-sale, or call center) to a site in CWIntegrate.
2. The CWIntegrate site translates the message and sends it to an MQ Series queue on the iSeries.
3. A process queue for the ORDER_IN process in Working with Integration Layer Processes (IJCT) is monitoring the queue. The process queue:
• Determines that the message is an inbound order message
• Interprets, or parses, the message
• Creates the related order, customer, and other files in CWDirect
4. If the order is identified as a batch order, it waits in the batch for review. Otherwise, the order is edited for complete, correct information:
• If the order passes the edit, the information is passed to the ORDER_ASYNC job. The order goes into open or held status, depending on if it passes all normal credit and fraud checks.
• 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 and the order is not part of a batch, the system places the order in the Batch Number for Retail Channel Orders (I78) if it contains errors. You can use batch order entry to review, work with, and approve these orders.
See Perform Order Edit Interactively (I56) for more information on when the system performs the order edit, depending on whether the payment information for an order is sent separately or together with the original order message.
5. An acknowledgement message is sent if the message specified a response (detailed or simple).
Accepting orders in a remote order batch: When you press F9 to accept an order that is part of the e-commerce order batch (the order batch number in the Default Batch for E-Commerce Orders in Error (G41) system control value) or retail channel order batch (the order batch number in the Batch Number for Retail Channel Orders (I78) system control value), the system writes an order transaction history message indicating the user that accepted the order. The system writes an order transaction history message each time a user accepts the order so that you can track the users that changed an order in a remote order batch. You can review order transaction history messages on the Display Order History Screen.
An example of the order transaction history message the system creates when a user accepts an order that is part of a remote order batch is displayed below. The system includes an amount regardless of whether the change updated the order total. Note: The Transaction Note indicates the type of remote order batch:
• Batch order changed - Ecomm.
• Batch order changed - Retail.
Date |
Type |
Transaction Note |
Amount |
User |
8/4/14 |
4 |
Batch order changed - Ecomm. |
20.75 |
SFLYE |
Features not supported: The generic order interface does not currently support all features available through interactive order entry. For example, the following are not supported:
• individual originator: you can specify an individual placer on an order, but not a separate originator
• order maintenance currently is 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
• telemarketing specials
• item comments
For more information: See Perform Order Edit Interactively (I56) for a listing of discount and free gift options, indicating whether the order API supports them.
Set and continuity items: To include a set (other than a variable set) or continuity item on an order created through the generic order API, the inbound order message should include the master set or continuity item only, and none of its components. The set or continuity item is “exploded” once the order is created, adding all of the components to the order.
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.
Pre-billing items: If you pre-bill items, the system adds the Pre Billed Amount Item (J72) to the order when it receives a new order that includes a pre-billable item. The Pre Billed Amount Item (J72) is included in the response message with a status of In stock and reserved. The actual pre-billable amount is not indicated in the response message.
See Pre Billed Amount Item (J72) for a 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 set to Y only if the payment method is a credit card.
Suppressing the deposit: If the suppress_deposit_flag is set to Y 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 Y. 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 N. Future shipments against the payment method will be eligible for deposit.
Suppressing refunds: If the suppress_refund_flag is set to Y 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.
For more information: See Working with Refunds, Writeoffs and Balances Due (WREF) for information on reviewing and working with refunds.
You can receive batched orders through the Inbound Order Message. The following attributes in the message control batching:
• batch_number: Must be a number that has not yet been used for an order batch. When the system receives the beginning order for a batch it confirms that the batch number does not exist in the Used Phone Batch file.
• batch_date: Indicates the date of the batch, as displayed at the Work with Order Batches Screen.
• batch_beg_end_flag: The first order in the batch should have this flag set to B. The last order in the batch should have this flag set to E.
• approve_batch: Indicates whether to automatically approve the batch, and put the orders in open or held status, once the last order in the batch is received.
• batch_order_count: Indicates the number of orders in the batch, as displayed at the Work with Order Batches Screen. The batch will be out of balance if the number of orders received for the batch is not the same as this value.
• batch_qty_count: The total order line quantity of all orders in the batch, as displayed in the # of units field at the Change Order Batch Screen. The batch will be out of balance if the total number of units is not the same as this value.
• batch_prepaid_total: The total prepaid dollar amount for the batch, used if you are batching cash.
Note: The response_type should be set to N for batched orders.
Required values for orders in the batch: When sending batched orders, complete the following attributes in the Inbound Order Message:
• First order:
• batch_number
• batch_date
• batch_beg_end_flag = B
• batch_order_count
• batch_qty_count
• batch_prepaid_total (if you use cash batching)
• Last order:
• batch_number = same as first order
• approve_batch
• batch_beg_end_flag = E
• All other orders: batch_number = same as first order
Important: Each order, including batched orders, must have a unique order_number specified to avoid errors in creating and processing.
For more information: See Introducing Batch Order Entry for an overview of order batching, and see Opening an Order Batch for information on creating a batch.
Note: You should stop and restart the background jobs and the ORDER_IN process after changing any order-related system control values.
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 Default Disposition Code (C18).
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.
Generating the CWCustomerReturn message: If the Send RA Message for Negative Quantity in OE/OM (J58) system control value is set to Y, the system generates a Generic WMS Customer Return XML Message (CWCustomerReturn) when you process a return through the Inbound Order XML Message (CWORDERIN).
Note: The system generates the CWCustomerReturn message when you process a return through the CWOrderIn message, even if the return contains an invalid return reason or return disposition; the system generates the CWCustomerReturn message using the invalid information.
In order to generate a Generic WMS Customer Return XML Message (CWCustomerReturn), the following must be defined:
• The Use PkMS Interface Values (F31) system control value is set to Y.
• Program name IFR0086 is defined in the PkMS Return/Case Interface Program (F38) system control value.
• MQ is defined in the PkMS Transport Type (G80) system control value.
• GENERIC or GENERIC_2 is defined in the RA Program XML Message Format (H45) system control value.
See Generating a CWCustomerReturn Message for Returns for more information on generating the Generic WMS Customer Return XML Message (CWCustomerReturn).
Performing Credit Card Tokenization on Web Orders
Credit card tokenization allows you to replace the credit card number with a token provided by the authorization service.
CWDirect calls the tokenization process for a web order if the Use Tokenization field for the service bureau associated with a credit card pay type on the order is set to Y, the Card type for the pay type is C Credit Card, and the already_tokenized tag for the credit card payment on the order is N or blank.
Creating Authorization History for Orders Authorized on the Web
CWDirect 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 is defined for the credit card payment on the order. If an auth_date, auth_amount, transaction_id, vendor_response, cid_response or avs_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 A (Approved); however, during pick slip generation, the credit card payment will go out for batch authorization since the authorization history record does not contain an approved authorization amount. Also, 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 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); however, since an authorization date was not defined, the system considers the authorization expired.
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, cid_response or avs_response is defined, CWDirect creates an authorization history record with a status of D (Declined). During pick slip generation, the credit card payment will go out for batch authorization.
Vendor response processing: Before the order is accepted and placed in an open status, the system:
• Looks at the Credit Card Vendor Response file for the authorization service defined for the credit card payment method to find a match to the vendor_response, cid_response, and avs_response from the authorization service. If the response is associated with a hold reason, the system places the order and payment method on hold; see Hierarchy for Placing the Credit Card On Hold. Also, if the avs_response does not exist in the Credit Card Vendor Response file, the system places the order on hold.
• If an entity dollar limit is defined for the response code, the system may place the order on hold if it exceeds the dollar limit. You can define an entity dollar limit by ship via, item class or postal code; see Entity Dollar Limit Setup for an overview.
• 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.
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.
Performing Online Credit Card Authorization on Web Orders
Online credit card authorization allows you to send and receive electronically 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 CWDirect receives the web order after determining if the order should go on hold.
If the order is eligible to receive a credit card authorization during order entry, the system sends the amount requiring authorization to the authorization service and waits for a response.
There are 3 types of responses you can receive from the authorization service.
• R = an authorization response was received, such as declined or approved.
• T = the program timed out before an authorization response was received.
• U = an undefined response was received.
Additionally, the authorization service 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.
If a pop up window message has been defined for the vendor response received, the Select Authorization Response Option Window will not display since web order processing occurs outside of a CWDirect screen.
Performing Online Verification Only: If the Online Auth Verification Only (I96) system control value is set to Y, 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.
Credit cards requiring authorizations less than the automatic authorization dollar threshold: When you perform online authorization, the system determines if the authorization amount qualifies for automatic authorization.
• If the credit card amount to authorize is less than the dollar amount defined in the $ Threshold for Automatic Authorization # Assignment (K36) system control value and you have defined an authorization number in the Authorization Number for Authorizations Under $ Threshold (K37) system control value, the system does not send the credit card to the service bureau for authorization and instead assigns the authorization number defined in the Authorization Number for Authorizations Under $ Threshold (K37) to the credit card.
• If the $ Threshold for Automatic Authorization # Assignment (K36) or Authorization Number for Authorizations Under $ Threshold (K37) system control value is blank, the credit card amount to authorize is less than $1.00, and you have defined an authorization number in the Authorization Number for Authorizations Under $1.00 (I08) system control value, the system does not send the credit card to the service bureau for authorization and instead assigns the authorization number defined in the Authorization Number for Authorizations Under $1.00 (I08) system control value to the credit card.
Credit cards requiring authorizations less than the reserve dollar threshold: If the Authorize Full Amount During Order Entry (G99) system control value is set to N and the authorization amount does not qualify for automatic authorization (see above), the system determines if the authorization amount meets the reserve dollar threshold.
• If the credit card amount to authorize is less than the amount defined in the Online Auth Reserve $ Threshold (L74) system control value and part of the order is not shippable, the system does not send the credit card to the service bureau for authorization. The system will send the credit card to the service bureau during batch authorization.
• If the credit card amount to authorize is less than the amount defined in the Online Auth Reserve $ Threshold (L74) system control value and all of the order is shippable, the system sends the credit card to the service bureau for authorization.
• If the credit card amount to authorize is equal to or greater than the amount defined in the Online Auth Reserve $ Threshold (L74) system control value, the system sends the credit card to the service bureau for authorization.
Bill Me Later orders: When you process an online authorization for an order containing a Bill Me Later pay type, the system always authorizes the pay types on the order for the full amount, regardless of the setting of the Authorize Full Amount During Order Entry (G99) system control value and Online Auth Verification Only (I96) system control value; see Performing Online Authorization for a Bill Me Later Order.
For more information: See Chapter 49: Performing Online Credit Card Authorizations for an overview of the online credit card authorization process and the required setup.
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 chapter.
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 CWDirect; 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
• CWDirect item information has been downloaded 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
• you might specify a response_type of E (errors), in order to include a description of any errors in the order in the Detailed Order XML Response (CWORDEROUT). In this situation, you would normally have the Perform Order Edit Interactively (I56) system control value set to Y in order to see errors identified through the order edit.
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, for example, 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, 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
• set to D to generate the Detailed Order XML Response (CWORDEROUT) without listing any errors found on the order;
• 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);
• pay_incl: set to N
What does the payment-only order message consist of? The payment-only message includes Message element, the Payments element, plus the following attributes in the Header element:
• rdc_order_nbr: the order_id included in the order response message. Required to identify the order.
• payment_only: set to Y
• 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
Overview: In addition to the setting of any Related System Control Values, the setup required for the generic order interface consists of:
• ORDER_IN process and process 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. Each process queue monitors a separate MQ Series queue for incoming messages.
• CWIntegrate site: The ORDER_IN process must receive a correctly formatted XML Inbound Order XML Message (CWORDERIN). You can use the CWIntegrate POS site to translate incoming orders into this format and send the resulting messages to CWDirect. See the CWDirect/CWStore integration manual for more information.
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 |
If no order_type is specified in the message, the system uses this value. |
|
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. See Selecting the Sales Rep. |
|
Require Salesrep Number in Order Entry/Order Maintenance (E87) |
When this value is set to Y, the order will be in error if the system cannot resolve the sales rep. See Selecting the Sales Rep. |
If no source code is specified at the header or on a detail line in the message, this value defaults. |
|
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. |
|
Having this system control value set to N does not prevent you from specifying an existing bill-to in the message and assigning it to the order. |
|
Update Customer Sold to with Bill to Account Number for New E-Commerce Orders (H87) |
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 the new bill-to, regardless of the setting of this system control value. |
If you specify a coupon number that does not match a record in the Coupon Redemption file, the system creates a coupon or credit payment method on the order; however, if this system control value is not set to Y, the order will be in error because of an Invalid coupon. |
|
The system uses these values when matching a sold-to customer. See Customer Sold To Selection, Creation and Update. |
|
Indicates whether to perform the order edit interactively or submit the order to a batch order edit. If the edit takes place interactively, the order totals and other information in the Detailed Order XML Response (CWORDEROUT) is more accurate. |
|
If the order_channel is P and the order is not part of a batch, the system places the order in this order batch if it contains errors. You can correct the errors in batch order entry. |
|
Controls whether the system defaults the individual email address to the Order email address field on an order. The system uses the following hierarchy in updating the order-level email address when creating orders through the Generic Order Interface (Order API): • If an order_email is specified in the Inbound Order Message, use that email address; otherwise, • If there is an email address specified for the individual placer (either specified in the ind_email_address in the message, or an existing email address for the individual), and the Default Individual Email Address (J17) system control value is set to Y, use that email address; otherwise, • If there is an email address specified for the sold-to customer (either specified in the sold_to_email in the message, or an existing email address for the customer), use that email address; otherwise, • Leave the order-level email address blank. |
|
Defines whether the system overrides the ship via code on the order to the Preferred ship via defined for the ship to customer’s SCF (the first 3 digits of the destination postal code). See Ship Via Defaults for Remote Orders for more information on the ship via that defaults to a remote order. |
|
Defines whether the system includes the Promotion element and its attributes in the Detailed Order XML Response (CWORDEROUT). The Promotion element lists the type of end of order promotions that were applied to the order. You can use this information on the web storefront to display to the customer the type of promotions for which the order qualifies, such as ship via upgrade, reduced or free freight, or free items. |
|
Defines whether the system generates a Generic WMS Customer Return XML Message (CWCustomerReturn) when you process a return through the Inbound Order XML Message (CWORDERIN); see Processing a Return. |
|
Defines whether the system searches all active offers for a matching alias when there is an alias specified in the alias_item attribute. See Resolving the Item and SKU for more information. |
|
Defines whether you can apply a promotion by specifying a randomly assigned single-use code related to the promotion in the single_use_promo_code attribute. See Creating and Using Single-Use Promotion Codes for more information. |
|
Prevents promotion discounts and benefits from applying to the order. See the system control value for more information. |
Customer Creation, Matching and Update Logic
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 set to Y, 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 Phone Interface 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 set to Y, 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 Phone Interface Values (F70) system control value), use the matching customer with the lowest customer number (customer created first); otherwise,
5. Prospect ID: If a valid prospect_id is specified in the message (but no valid customer_number, existing alternate_sold_to_id, sold_to_eve_phone, or sold_to_day_phone):
• Find the Prospect Finder record whose Prospect finder number matches the prospect_id. If there is just one customer whose name and address matches the name and address for the Prospect Finder record (using the matching rules specified through the Phone Interface Values (F70) system control value), use that customer; otherwise,
• If there are multiple customers whose name and address match the selected Prospect Finder record, use the customer with the highest customer (most recently created customer); otherwise,
6. Name and address match: If none of the above matches work, use the matching rules specified through the Phone Interface Values (F70) system control value to search for a customer who matches the name and address information specified in the message:
• 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,
7. Create customer: If there is no matching customer, create a new customer for the order.
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 set to Y.
If using President’s Club: If the Use President’s Club Membership (H94) system control value is set to Y, the alternate customer number is used to identify an existing or prospective President’s Club membership. See Alternate Customer Number Matching through the Order API with President’s Club for a discussion.
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 file). 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 fax/mobile)
• opt-in/out flag
• rent flag
• mail flag
• customer class
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 set to Y 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 fax/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 set to Y, the system updates the email address at the customer sold-to level and in the Customer Sold To Email file. 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 will still update the email address if the sold_to_email_update flag is set to Y.
See Creating and Updating Sold-to Customers (WCST) for a discussion of each of these fields.
Individual customers: The Inbound Order XML Message (CWORDERIN) uses the same logic as e-commerce orders in selecting or creating individuals. See Selecting or Creating Individual Customers in E-Commerce Orders.
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. The rules for matching an existing customer or creating a new customer are summarized below.
Description |
How to add in Inbound Order Message |
order-level shipping address |
|
Specified just for a particular order. This is the type of shipping address that you create by pressing F14 at the Work with Order Screen or Work with Order/Detail Screen. |
ship_to_type = 1 customer_ship_to_number = blank alternate_ship_to_id = 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 |
recipient customer |
|
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 pressing F2 at the Work with Order Screen, or pressing F19 or F2 at several screens in order entry. |
Existing customer: ship_to_type = 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 use as the recipient customer for the order. alternate_ship_to_id = blank permanent_ship_to_number = blank New customer: ship_to_type = 2 customer_ship_to_number = blank alternate_ship_to_id = 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 Phone Interface Values (F70), the system uses the existing customer for the order. |
permanent shipping address |
|
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 pressing F7 at the Work with Order Screen or Work with Order/Detail Screen. |
Existing permanent ship-to: ship_to_type = 3 customer_ship_to_number = number of the sold-to customer for the order alternate_ship_to_id = blank 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 = 3 customer_ship_to_number = number of the sold-to customer for the order alternate_ship_to_id = blank 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 Phone Interface 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 Phone Interface 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 Phone Interface 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 Phone , 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 that uses an A/R payment method:
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 an existing bill-to customer exactly, use that bill-to; 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 Bill to number assigned to the sold-to customer, if any; otherwise,
4. Search the Customer Bill To file 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, regardless of the setting of the Update Customer Sold to with Bill to Account Number for New E-Commerce Orders (H87) system control value.
For each order detail line, the system determines the item and SKU to use by checking the following attributes in the sequence indicated:
5. alias_item
6. sku_xref_nbr
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.
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 and the Search Offers for Alias (J68) system control value
• SKU cross reference number: Work with SKU Cross Reference Type Screen
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 set to Y, 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, suspend the order because of the invalid rep. |
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 set to Y, put the order in error because of the missing rep. |
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) specified for the sold-to customer on the order.
| Part E: Generic Order Interface | Contents | SCVs | Search | Glossary | Reports | XML | Index | Order Interface XML Message Formats |
GO01_01 CWDirect 18.0 August 2015 OTN