Chapter 116: Generic Customer History API

Chapter 116: Generic Customer History API

Purpose: Use the generic customer history integration to provide a customer’s order history, or detailed information about a single order, to an external system such as CWStore or Store21. The external system can request and receive information on:

• all orders for the customer, a limited number of the customer’s most recent orders, or a single order

• all orders regardless of channel (such as e-commerce orders), or excluding a particular channel

• all orders for a specific entity, or regardless of entity

• all ship-to’s for a multi-recipient order, or a particular ship-to

The response can include detailed information that includes all items, payment methods, and ship-to’s on the order; summary information about the header only; or just selected information from the header and order details.

Different message flows: The Customer History Outbound Message Type (J84) system control value determines whether the CUST_HIST job generates a different response message based on the type of information included in the request, or always generates the same message. The two different message flows are described in this chapter.

In this chapter:

• Typical Customer History Flow: Different Response Message Types

• Typical Customer History Flow: Store21

• Additional Background on Customer History API Processing

• When is the Response Message Empty?

• Customer History API Setup Requirements

• Customer History Request XML Message (CustHistIn)

• Customer History Request Message: Sample XMLs

• Customer History Response XML Message (CWCUSTHISTOUT)

• Customer History Response Message: Sample XML

• Detailed Customer History Response XML Message (CWORDEROUT)

• Detailed Order Inquiry Response Message: Sample XML

• Summary Order Inquiry Response XML Message (CWORDEROUT)

• Summary Order Inquiry Response Message: Sample XML

• Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21)

• CWCUSTHISTOUTSTORE21 Message: Sample XML

Typical Customer History Flow: Different Response Message Types

A typical customer history inquiry flow would begin when a customer in a retail store has a question about an order placed in CWDirect. This message flow is possible if the Customer History Outbound Message Type (J84) system control value is blank.

1. The store clerk inquires on history for the customer.

2. The customer history request is processed:

• CWStore sends a customer history request message to CWIntegrate. The message uses the customer number in CWStore, which is the same as the alternate customer number in CWDirect. Typically, the request limits the number of orders in the response to no more than 15, in order to insure an acceptable response time.

• CWIntegrate translates CWStore’s request message to the Customer History Request XML Message (CustHistIn) and sends it to the queue specified for the CUST_HIST job running in Working with Integration Layer Processes (IJCT) in CWDirect.

• The CUST_HIST job sends the Customer History Response XML Message (CWCUSTHISTOUT), listing the customer’s orders, to CWIntegrate.

• CWIntegrate translates the response to CWStore’s format and sends it to CWStore.

3. CWStore presents the list of orders, and summary information about each, on screen.

4. The store clerk selects an order from the list for further inquiry.

5. The order inquiry request is processed:

• CWStore again generates the Customer History Request XML Message (CustHistIn); however, this request includes the specific order number or alternate order number (such as the CWStore transaction number), and the send_detail flag is set to Y.

• The CUST_HIST job in CWDirect generates the Detailed Customer History Response XML Message (CWORDEROUT), listing detailed information about the selected order, and sends it to CWIntegrate. The detailed information includes sold-to, ship-to, and bill-to addresses, payment methods, items, and shipments.

• CWIntegrate translates the order history response and sends it to CWStore.

6. CWStore displays the detailed information about the order onscreen.

Alternate flow: Alternately, if the store clerk or customer know the specific order number for inquiry, they can start by sending the request message based on the order number, and use the send_detail flag to indicate whether CWDirect should send the full Detailed Customer History Response XML Message (CWORDEROUT), or just the Summary Order Inquiry Response XML Message (CWORDEROUT) as a quick confirmation.

Outbound XML version: Both the CUST_HIST job and the ORDER_IN job in Working with Integration Layer Processes (IJCT) can generate the CWORDEROUT message. There are different versions of the CWORDEROUT message available for use with these integrations, with each additional version of the message including new information that was not in the previous version. The outbound XML version specified for the ORDER_IN job controls the version of the CWORDEROUT message generated for both the ORDER_IN job and the CUST_HIST job.

A few things to note:

• Version 2.0 of the CWORDEROUT message added tax information at the detail level and shipment override information at the ship-to level.

• Version 3.0 of the CWORDEROUT message added President’s Club information, the ability to send information on errors on the order, and the promotions for which the order qualifies.

• The CWORDEROUT message does include tax amounts for order detail lines and shipping override information when the message is generated by the CUST_HIST job, as long as the outbound XML version for the ORDER_IN job is set to 2.0 or higher.

• The CWORDEROUT message does not include President’s Club information, Errors, or Promotions when the message is generated by the CUST_HIST job, regardless of the outbound XML version specified for the ORDER_IN job. This information is relevant only to the generic order API, and is not relevant to the customer history API, even though both API’s use the same DTD.

Typical Customer History Flow: Store21

If the Customer History Outbound Message Type (J84) system control value is set to STORE21, the CUST_HIST job always sends the Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21) regardless of whether the Customer History Request XML Message (CustHistIn) requests information on a customer or indicates a specific order number. Also, the send_detail flag in the request message does not affect the level of detail included in the response message.

For example, if the request message identifies a particular customer by customer number or alternate customer number (but does not specify a particular order), the Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21) includes a listing of orders for that customer. If the request message identifies a particular order number or alternate order number, the Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21) includes the same level of detail, but for that particular order only.

Additional Background on Customer History API Processing

Requests from multiple systems: You can have the CUST_HIST job respond to customer history requests from multiple external systems by setting up a process queue for each system. For example, you can set up a process queue for both a retail store and a web storefront so you can send customer history to each. However, the setting of the Customer History Outbound Message Type (J84) system control value controls whether the responses resemble those in the Typical Customer History Flow: or in the Typical Customer History Flow: Store21, and this setting applies to all process queues.

Are orders in error or suspended status included in the response? When the request is based on the customer number or alternate customer, the response does not include orders that are in error (E) or suspended (S) status; however, if the request specifies a particular order that is in error or suspended status, then the response provides information on that order.

Finding the correct customer for the history request: Optionally, you can use this integration together with the customer inquiry (search) integration in order to enable an external system to first identify the customer record before requesting history for the specific customer. See Generic Customer Inquiry (Search) API for an overview of how you might use the customer inquiry (search) integration) to find a customer’s customer number.

When is the Response Message Empty?

The CUST_HIST job sends an “empty” response when the request does not include sufficient valid data. The empty response indicates to the external system that CWDirect received the request, but it was incomplete or invalid. For example, the job sends an empty response when the request includes:

• an invalid company code, or no company indicated

• a customer or alternate customer number that doesn’t exist, or no customer indicated

• a customer that has no orders, or no orders within the specified entity

• an order number or alternate order number that doesn’t exist

• a customer number that is not consistent with the alternate customer number, if indicated

• a customer number or alternate customer number that is not the sold-to customer for the order number or alternate order number, if indicated

• a ship-to number and an order or alternate order number that is not consistent with the ship-to number (for example, a ship-to number of 3 is indicated, but the specified order has only 2 ship-to’s)

• a customer who does not have any orders except those in an excluded order channel, if indicated

Depending on the setting of the Customer History Outbound Message Type (J84) system control value and the type of information provided in the request, the empty response resembles the following:

</Message>

Customer History API Setup Requirements

To use the customer history API, you need to configure the CUST_HIST job in Working with Integration Layer Processes (IJCT), and send a correctly formatted Customer History Request XML Message (CustHistIn) to a queue specified for the job. Similarly, you must be prepared to receive the responses described in this chapter. Typically, you would use CWIntegrate to generate the request message and translate the response message.

Related system control value: The Customer History Outbound Message Type (J84) system control value determines the response message generated. See that system control value for more information.

You can use CWIntegrate for a seamless integration with CWStore version 7.8 or higher, but the CUST_HIST job will process customer history requests from any source as long as the XML files are correctly formatted and contain the required information. More information on using the customer history API as part of the point of sale integration with CWStore is provided in the operations guide for the CWDirect/CWStore Integration.

Customer History Request XML Message (CustHistIn)

The CUST_HIST job requires an XML request laid out as follows.

Important: Please note the following rules for numeric fields:

• Do not pass an alphanumeric value in a numeric field; doing so will cause the CUST_HIST job to go into a message wait status.

• Do not exceed the specified length of any numeric field; doing so will cause the value to be interpreted incorrectly or possibly cause the CUST_HIST job to error.

General rules for alphanumeric fields:

• case-sensitive; an a is not equivalent to an A.

• will be truncated if they exceed the maximum length specified below; a transaction_code of Adjustment will be truncated to A and processed correctly

Important guidelines for best performance: For best response time when requesting customer history, you should limit requests based on customer number or alternate customer number to no more than 15 orders based on the number_of_orders attribute.

For more information: See:

• Typical Customer History Flow: Different Response Message Types and Typical Customer History Flow: Store21 for a discussion of when you might use this message.

• XML Messages for a table that provides links to the DTD, schema, and a sample XML layout for each XML message.

• Customer History Request Message: Sample XMLs for sample messages.

Attribute Name	Type	Length	Comments
Message
source	alpha	25	Identifies the source of the XML message. IDC indicates the XML message is from CWIntegrate.
target	alpha	25	Identifies the target of the XML message. RDC indicates the XML message is sent to CWDirect.
type	alpha	25
resp_qmgr	alpha	25	Identifies the destination WebSphere MQ queue manager.
resp_q	alpha	25	Identifies the destination queue.
CustomerHistoryRequest
company	numeric	3	Indicates the company associated with the customer. Validated against the Company file; see Setting Up Companies (WCMP). See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the company number indicated.
Note: If the request includes either the customer_number or alternate_sold_to_id (but not the direct_order_number or the alternate_order_number), and the Customer History Outbound Message Type (J84) system control value is blank, the CUST_HIST job generates the Customer History Response XML Message (CWCUSTHISTOUT).
customer_number	numeric	9	Indicates the customer number for the sold-to customer on the order. Validated against the Customer Sold To file; see Creating and Updating Sold-to Customers (WCST). To retrieve customer history by customer, the request can specify either the customer_number or the alternate_sold_to_id, below. See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the customer_number indicated.
alternate_sold_to_id	alpha	15	Indicates the Alt cust (Alternate customer number) or one of the alternate customer number cross-references for the sold-to customer. Typically, the alternate customer number identifies the customer in an external system, such as CWStore. This is the Interface customer code in the Customer Sold To file. If there are no matches in the Customer Sold To file, the system checks the Alternate Customer Number Cross Reference file for matches; see Working with Alternate Customer Number Cross-References for an overview.
			Primary alternate customer number takes precedence: The system first searches for a match in the Customer Sold To file. If there are no matches in the Customer Sold To file, the system then searches the Alternate Customer Number Cross Reference file for a match.
			If multiple matches: If there is more than one customer with a matching alternate customer number in the Customer Sold To file, the CUST_HIST job selects the customer created last, based on customer number. For example, if both customer 101 and customer 201 both have 400 as the primary alternate customer number, the CUST_HIST job selects customer 201. However, if there are no matches in the Customer Sold To file, but there are matches in the Alternate Customer Number Cross Reference file, the CUST_HIST job selects the customer who was most recently assigned the matching alternate customer number. For example, if customers 101, 201, and 301 all have 400 assigned in the Alternate Number Cross Reference file but not as the primary number, and customer 301 was the one most recently assigned alternate customer number 400, CUST_HIST job selects customer 301.
			Note: The alternate_sold_to_id is case-sensitive. See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the alternate_sold_to_id indicated. Selecting based on alternate customer number is not implemented with ghost customers. See Ghost Customers for an overview.
number_of_orders	numeric	5	Indicates the maximum number of orders to include in the response message. The CUST_HIST job uses this number only if the request is based on the customer_number or alternate_sold_to_id. Note: Although this attribute is optional, MICROS recommends that you limit a request based on customer information to no more than 15 orders to prevent a negative effect on response time. For example, if response time for a customer with 100 orders is about 30 seconds, restricting the number of orders to 15 reduces response time to five or six seconds. If the request restricts the number of orders, the response includes the most recent orders.
Note: If the request specifies either the direct_order_number or the alternate_order_number and the Customer History Outbound Message Type (J84) system control value is blank, the CUST_HIST job generates: • the Detailed Customer History Response XML Message (CWORDEROUT) if the send_detail flag is set to Y • the Summary Order Inquiry Response XML Message (CWORDEROUT) if the send_detail flag is set to N If the Customer History Outbound Message Type (J84) system control value is set to STORE21, then the CUST_HIST job always generates the Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21).
direct_order_ number	numeric	8	Indicates a single order to include in the response. See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the direct_order_number indicated. Note: Do not include an order number longer than 8 positions to avoid the possibility of causing the CUST_HIST job to error.
direct_order_ship_ to_nbr	numeric	3	Optional. Identifies the shipping address to include on a multiple ship-to order. In order inquiry, the ship-to number appears as a suffix to the order number, separated by a hyphen (-). See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the direct_order_ship_to_nbr indicated.
alternate_order_ number	alpha	30	Indicates the order number used in an external system, such as CWStore, and stored in the E-commerce order number field in the Order Header Extended file. This field is labeled the Web order number at the Display Order Properties Screen. If the direct_order_number is valid, the CUST_HIST does not check the alternate_order_number. See When is the Response Message Empty? for information on when the CUST_HIST job sends an “empty” response based on the alternate_order_number indicated.
send_detail	alpha	1	Indicates whether to send detail or summary information in the response message. Valid values are: Y = Send the Detailed Customer History Response XML Message (CWORDEROUT) N = Send the Summary Order Inquiry Response XML Message (CWORDEROUT) If the send_detail setting is not included in the request, the CUST_HIST job sends the Summary Order Inquiry Response XML Message (CWORDEROUT). Not considered: The setting of this flag is not a factor when: • The request is based on the customer_number or alternate_sold_to_id; in this case, the CUST_HIST job always sends the Customer History Response XML Message (CWCUSTHISTOUT). • The Customer History Outbound Message Type (J84) system control value is set to STORE21; in this case, the CUST_HIST job always sends the Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21).
exclude_order_ channel	alpha	1	Optional. Indicates a specific order channel, such as retail orders, to exclude from the Customer History Response XML Message (CWCUSTHISTOUT). The CUST_HIST job checks the Internet order field in the Order Header file for the order channel. However, the CUST_HIST job does not consider this setting when the request is based on direct_order_number or alternate_order_number.
entity	numeric	3	Optional. Indicates a specific entity to include in the Customer History Response XML Message (CWCUSTHISTOUT). The system determines the entity for an order by the source code on the order header; each source code specifies a division, and each division specifies an entity. If the request message indicates an entity, only orders for this entity are included in the response; otherwise, orders are included regardless of entity. However, the CUST_HIST job does not consider this setting when the request is based on direct_order_number or alternate_order_number. Available in XML version: 2.0 (version 11.5 of CWDirect).

Customer History Request Message: Sample XMLs

Samples of the Customer History Request XML Message (CustHistIn) are presented below.

Customer History Request by Customer: If the request includes either the customer_number or alternate_sold_to_id, the CUST_HIST job generates the Customer History Response XML Message (CWCUSTHISTOUT).

</Message>

Customer History Request by Order (Detail): If the request specifies either the direct_order_number or the alternate_order_number, the CUST_HIST job generates the Detailed Customer History Response XML Message (CWORDEROUT) if the send_detail flag is set to Y.

• the Summary Order Inquiry Response XML Message (CWORDEROUT) if the send_detail flag is set to N

</Message>

Customer History Request by Order (Summary): If the request specifies either the direct_order_number or the alternate_order_number, the CUST_HIST job generates the Summary Order Inquiry Response XML Message (CWORDEROUT) if the send_detail flag is set to N.

</Message>

Customer History Response XML Message (CWCUSTHISTOUT)

When the Customer History Request XML Message (CustHistIn) includes customer information and the Customer History Outbound Message Type (J84) system control value is blank, the CUST_HIST job generates an XML response laid out as follows.

Note:

• Attributes are included in the response only if they contain a value. Blank attributes are not passed.

• Numeric fields use implied decimals; for example, a value of $12.34 is presented as 1234.

For more information: See:

• Detailed Customer History Response XML Message (CWORDEROUT) for descriptions of each attribute.

• Typical Customer History Flow: Different Response Message Types for a discussion of when the CUST_HIST job might generate this message.

• Customer History Response Message: Sample XML for a sample message.

• XML Messages for a table that provides links to the DTD, schema, and a sample XML layout for each XML message.

Message

• source

• target

• type

Header

• company_code

• order_id

• reference_order_number

• customer_number

• alternate_sold_to_id

• bill_to_number

• order_date

• order_channel

• bill_me_later_ind

ShipTo

• ship_to_number

• sub_total

• discount_total

• shipping

• additional_shipping

• tax

• additional_charges

• handling

• order_total

• gst

• pst

• ship_to_status

• gift_order

• purchase_order_nbr

• discount_pct

• ship_via_code

• ship_via_description

• customer_number

• permanent_ship_to_number

Customer History Response Message: Sample XML

A sample of the Customer History Response XML Message (CWCUSTHISTOUT) is presented below. The CUST_HIST job generates this message if the Customer History Request XML Message (CustHistIn) includes either the customer_number or alternate_sold_to_id.

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</ShipTo>

</ShipTos>

</Header>

</Headers>

</Message>

Detailed Customer History Response XML Message (CWORDEROUT)

When the Customer History Request XML Message (CustHistIn) includes order information, the send_detail attribute is set to Y, and the Customer History Outbound Message Type (J84) system control value is blank, the CUST_HIST job generates an XML response laid out as follows.

For more information: See:

• Summary Order Inquiry Response XML Message (CWORDEROUT) for information on the response generated when the Customer History Request XML Message (CustHistIn) includes order information, the send_detail attribute is set to Y, and the Customer History Outbound Message Type (J84) system control value is blank, and the send_detail attribute is set to N.

• Typical Customer History Flow: Different Response Message Types for a discussion of when the CUST_HIST job might generate this message, and for more information on how the system determines whether to include additional information based on the XML version of the message.

• Detailed Order Inquiry Response Message: Sample XML for a sample message.

• Detailed Order XML Response (CWORDEROUT) for a description of the additional elements and attributes that might be included in the CWORDEROUT message when it is generated in response to the Inbound Order XML Message (CWORDERIN) as part of the generic order API.

• XML Messages for a table that provides links to the DTD, schema, and a sample XML layout for each XML message.

Note: When the ORDER_IN job generates the CWORDEROUT message, it might include additional elements based on the outbound XML version. See Typical Customer History Flow: Different Response Message Types for a discussion.

Attribute Name	Type	Length	Comments
Message
source	alpha	25	Identifies the source of the XML message. RDC indicates the XML message originates from CWDirect.
target	alpha	25	Identifies the target of the XML message. IDC indicates the XML message is sent to CWIntegrate.
type	alpha	25	Identifies the type of information in the XML message.
Header
company_code	numeric	3	Indicates the company associated with the customer; see Setting Up Companies (WCMP).
order_id	numeric	8	A unique number identifying the order. If the response includes multiple orders, it starts with the most recent order first and presents orders in descending sequence by order number.
reference_order_ number	alpha	30	The E-commerce order number in the Order Header Extended file, which is used to store an alternate order number, such as a sale transaction received from CWStore through the point of sale integration. This field is labeled the Web order number at the Display Order Properties Screen.
customer_number	numeric	9	A unique number identifying the sold-to customer.
alternate_sold_to_id	alpha	15	The Alt cust (Alternate customer number), if any, for the sold-to customer. Typically, the alternate customer number identifies the customer in an external system, such as CWStore.
bill_to_number	numeric	7	The bill-to account number, if any, associated with the order; see Creating and Updating Bill-to Customers (WCBT).
order_date	numeric	8	The Order date in the Order Header file. Displayed on the Order Inquiry Header Screen. MMDDYYYY format.
order_channel	alpha	2	From the Internet order field in the Order Header file. Typical settings are: I = an internet order P = a point of sale order blank = an order taken in CWDirect
bill_me_later_ind	alpha	1	Valid values are: Y = The customer has an existing Bill Me Later account N = The customer does not have an existing Bill Me Later account The system determines the setting of this flag based on whether there is an account number in the Customer Sold To BML file, regardless of whether the customer actually uses a Bill Me Later payment method on this order. For example, if the customer is applying for a Bill Me Later account with this order but it has not yet gone out for authorization, then this flag is set to N, because the account number has not yet been established. See Bill Me Later Processing for more information.
order_status	alpha	1	The current status of the order. Valid values are: C = Canceled H = Held X = Closed E = Error S = Suspended Included only if the status is not open (blank). Orders in error (E) or suspended (S) status are not included in the customer history response, although they are available through an order inquiry request and response .
order_type	alpha	1	The Order type field in the Order Header file. Defined in and validated against the Order Type file; see Establishing Order Types (WOTY).
order_type_ description	alpha	30	The description from the Order Type file; see Establishing Order Types (WOTY).
b2b_order	alpha	1	From the B2B order? flag in the Order Header file. Valid values are: Y = This is a B2B order; see Entering B2B Orders N = This is not a B2B order This flag is set only for B2B orders and orders you receive through the e-commerce interface or the Generic Order Interface (Order API).
store_restock_order	alpha	1	From the Store restock order? flag in the Order Header file. Valid values are: Y = This is a retail Store restock order; see Understanding Store Restock. N = This is not a retail store restock order Note: This flag is also set for orders you receive through the e-commerce interface or the Inbound Order Message.
entered_date	numeric	8	The Entered date in the Order Header file. MMDDYYYY format.
entered_time	numeric	6	The Entered time in the Order Header file, which you can review at the Display Order Properties Screen.
email_confirm_date	numeric	8	The date when the system generated an automatic email confirmation or the Outbound Email XML Message (CWEmailOut). From the Order Header file (Note: This field might be listed as Future use date 1). MMDDYYYY format. Included only if an email confirmation or outbound XML message was generated.
source_code	alpha	9	The source code from the order header; see Working with Source Codes (WSRC).
offer_id	alpha	3	The offer associated with the source code on the order header.
Note: The sold-to name and address is from the Customer Sold To file. See Creating and Updating Sold-to Customers (WCST) for a description of the sold-to information that is included in the customer history response.
sold_to_prefix	alpha	3
sold_to_fname	alpha	15
sold_to_initial	alpha	1
sold_to_lname	alpha	25
sold_to_suffix	alpha	3
sold_to_company	alpha	30
sold_to_busres	alpha	1
sold_to_address1	alpha	32
sold_to_address2	alpha	32
sold_to_address3	alpha	32
sold_to_address4	alpha	32
sold_to_apartment	alpha	10
sold_to_city	alpha	25
sold_to_state	alpha	2
sold_to_state_ description	alpha	25	As set up through Setting Up the Country File (WCTY).
sold_to_zip	alpha	10
sold_to_country	alpha	3
sold_to_day_phone	alpha	14
sold_to_eve_phone	alpha	14
sold_to_fax_phone	alpha	14	The third (fax or mobile) phone number.
allow_rent	alpha	1
allow_mail	alpha	1
sold_to_opt_in	alpha	2
ind_number	numeric	3	The number identifying the individual placer of the order, if any. See Creating and Updating Individuals for an overview.
Note: The bill-to name and address is from the Customer Bill To file. See Creating and Updating Bill-to Customers (WCBT) for a description of the bill-to information.
bill_to_prefix	alpha	3
bill_to_fname	alpha	15
bill_to_initial	alpha	1
bill_to_lname	alpha	25
bill_to_suffix	alpha	3
bill_to_company	alpha	30
bill_to_busres	alpha	1
bill_to_address1	alpha	32
bill_to_address2	alpha	32
bill_to_address3	alpha	32
bill_to_address4	alpha	32
bill_to_apartment	alpha	10
bill_to_city	alpha	25
bill_to_state	alpha	2
bill_to_state_ description	alpha	25	As set up through Setting Up the Country File (WCTY).
bill_to_zip	alpha	10
bill_to_country	alpha	3
bill_to_day_phone	alpha	14
bill_to_eve_phone	alpha	14
bill_to_fax_phone	alpha	14	The third (fax or mobile) phone number.
Payment			Note: See the Display Order Pay Type Screen (1 of 2) for more information on order payment methods.
payment_seq_ number	numeric	2	Indicates the sequence in which the payment methods were added to the order. From the Order Payment Method file.
pay_type	numeric	2	A unique code to identify a form of payment. From the Pay Type file; see Working with Pay Types (WPAY).
pay_type_desc	alpha	30	The description associated with the pay type.
credit_card_nbr	alpha	20	The customer’s credit card account number used on this order. Credit card pay types only. If you use credit card tokenization, this number may be a token rather than the actual credit card number. If you use credit card encryption, the credit card number in this message is not encrypted; however, the system encrypts the credit card number in the CWDirect database.
credit_card_exp_dt	numeric	4	The month and year when the customer’s credit card number expires. MMYY format. Credit card pay types only.
credit_card_auth_dt	numeric	8	The month, day, and year that your credit card authorization service confirmed or authorized the customer's credit card for the order, or you manually authorized the credit card. Included only if the authorization has not already been used. MMDDYYYY format.
credit_card_auth_ nbr	alpha	7	The number you entered when you manually authorized the credit card, or that the authorization service assigned when authorizing the credit card. Included only if the authorization has not already been used.
check_nbr	numeric	9	For a check pay type, a number identifying the customer’s check number.
gift_cert_nbr	numeric	7	For a gift certificate or coupon pay type, a number identifying the gift certificate or coupon.
amt_to_chg	numeric	9.2	The total dollar amount to charge against the payment method. Not included for the "catch-all" payment method on an order if there is more than one payment method.
start_date	numeric	4	For a stored value card or debit card pay type, the date when the card is effective. MMYY format. See Types of Credit Cards for more information.
card_issue_nbr	alpha	2	For a debit card pay type, an incremental number assigned by the bank to indicate how many times the card has been replaced due to loss or theft. See Types of Credit Cards for more information.
ShipTo			Note: See Reviewing the Order Inquiry Header Screen for more information on the order ship-to.
ship_to_number	numeric	3	A number to identify the shipping address on the order. In order inquiry, the ship-to number appears as a suffix to the order number, separated by a hyphen (-).
sub_total	numeric	9.2	The merchandise total for this shipping address on the order. Note: See the Order Inquiry Header Screen for a description of each of the order totals.
discount_total	numeric	9.2	The total discount for the shipping address, displayed at the Order Inquiry Header Screen.
shipping	numeric	7.2	The total freight charge for this shipping address.
additional_shipping	numeric	7.2	The total additional freight charge for this shipping address.
tax	numeric	7.2	The total tax, excluding any hidden tax, for this shipping address.
additional_charges	numeric	7.2	The total additional charges for this shipping address.
handling	numeric	7.2	The total special handling for this shipping address.
order_total	numeric	11.2	The total of all merchandise, freight, tax, and charges for the shipping address.
gst	numeric	7.2	The total Canadian Goods and Service Tax, if any, that applies to the order shipping address. The GST and the PST are included in the tax total.
pst	numeric	7.2	The total Canadian Provincial Services Tax, if any, that applies to the order shipping address. The GST and the PST are included in the tax total.
ship_to_status	alpha	1	Indicates the status of this shipping address. This status could differ from the order header if, for example, the order has multiple shipping addresses and you canceled just one. Included only if the status is not open (blank).
gift_order	alpha	1	From the Gift order flag in the Order Ship To file; see the Gift flag at the Display Order Properties Screen. Valid values are: Y = This is a gift order N = This is not a gift order
purchase_order_nbr	alpha	15	The Purchase order #, if any, in the Order Ship To file; see the Purchase order # at the Display Order Properties Screen.
discount_pct	numeric	5.2	The discount percentage, if any, from the Order Ship To file.
ship_via_code	numeric	2	The ship via used for this shipping address, from the VIA ship via code in the Order Ship To file; see the Ship via at the Display Order Properties Screen.
ship_via_ description	alpha	30	The description of the ship via, as set up through Working with Ship Via Codes (WVIA).
shipping_override	alpha	1	Indicates whether the Freight override flag is set. Set to Y if there is a freight override; otherwise, not included. The Display Order Properties Screen displays the Freight override flag on the order. Available in XML version: 2.0 (version 9.0 of CWDirect). The outbound XML setting of the ORDER_IN job determines whether to include this tag as part of the customer history API; see Typical Customer History Flow: Different Response Message Types for a discussion.
customer_number	numeric	9	Included only if there is an order recipient.
permanent_ship_to_number	numeric	3	Included only if the order uses a permanent ship-to.
Note: The ship-to name and address can default from the Customer Sold To (recipient customer), Customer Ship To (permanent ship-to), or Order Ship To files (order-level shipping address), depending on the type of shipping address.
ship_to_prefix	alpha	3
ship_to_fname	alpha	15
ship_to_initial	alpha	1
ship_to_lname	alpha	25
ship_to_suffix	alpha	3
ship_to_company	alpha	30
ship_to_busres	alpha	1
ship_to_address1	alpha	32
ship_to_address2	alpha	32
ship_to_address3	alpha	32
ship_to_address4	alpha	32
ship_to_apartment	alpha	10
ship_to_city	alpha	25
ship_to_state	alpha	2
ship_to_state_ description	alpha	25	As set up through Setting Up the Country File (WCTY).
ship_to_zip	alpha	10
ship_to_country	alpha	3
Detail			Note: See Reviewing Order Details for more information on the detail lines on an order; also, see Performing Initial Item Entry (MITM) for more information on the item/SKU itself.
line_seq_number	numeric	5	A sequence number to identify each detail line on the order.
short_sku_number	numeric	7	A unique number, assigned by the system and stored in the SKU file, to uniquely identify each item/SKU.
retail_ref_number	numeric	15	A retail reference or alternate product number to identify the item/SKU. Stored in the SKU file.
status	alpha	1	The status of the order line. Valid values are: B = Express Bill C = Canceled E = Error H = Held S = Soldout X = Closed A status code is not included if the order line status is open (blank).
alias_item	alpha	12	An alternate item code, used to track sales for different placements of the item. From the Order Detail file; included only if there was an alias used to order the item/SKU.
item_id	alpha	12	A unique code to identify an item.
item_description	alpha	30	The description of the item.
sku	alpha	14	The item’s unique characteristics, such as its color or style. Included only if the item has SKU’s.
sku_description	alpha	40	The description of the SKU.
actual_price	numeric	7.2	The unit price of the item from the Order Detail file. Not included for free gift or no-charge items.
offer_price	numeric	7.2	The unit price of the item as defined for the Item Offer or SKU offer and saved in the Order Detail file.
original_retail_price	numeric	7.2	The Original Retail Price from the SKU file; this is the Original retail $ at the second Create/Change/Display SKU screen in Work with Items/SKUs.
drop_ship	alpha	1	Valid values are: Y = This is a drop-ship item N = This is not a drop-ship item. If the item is reserved on the order detail line, this flag is set to N regardless of whether the item is flagged as a drop-ship in the Item file.
detail_ship_via	numeric	2	The ship via, if any, entered at the Work with Order Line Screen as an override to the ship via on the order header.
pickup_type	alpha	2	Not implemented through the Generic Customer History API.
pickup_system_ location	alpha	10
pickup_location	alpha	10
order_quantity	numeric	5	The total quantity of the item ordered on the detail line. This number is negative for returns you process by entering a negative quantity in order entry.
cancel_quantity	numeric	5	Included only if any quantity of the item on the order has been canceled.
sold_out_quantity	numeric	5	Included only if any quantity of the item on the order has been sold out.
ship_quantity	numeric	5	Included only if any quantity of the item on the order has been shipped. This number is negative for returns you process by entering a negative quantity in order entry.
return_quantity	numeric	5	Included only if any quantity of the item on the order has been returned. Not included for returns you process by entering a negative quantity in order entry.
expected_ship_date	numeric	8	Passed only if the item is backordered and there is an open purchase order for the item. MMDDYYYY format, or if the Calculate Expected Date in OE if No PO (J61) system control value is set to Y. See Determining the Expected Ship Date. This date is included for drop ship items only if the Assign Drop Ship Expected Ship Date (I59) system control value is set to Y. See that system control value for more information.
last_ship_date	numeric	8	Included only if there has been a shipment, or if you processed a return by entering a negative quantity in order entry. MMDDYYYY format.
reserved_ warehouse	numeric	3	The warehouse where the order detail line is currently reserved. Sent only if there is a reserve_quantity.
reserve_quantity	numeric	5	Included only if any quantity of the item on the order is reserved.
tax	numeric	10.5	The total tax amount applied to the order detail line. Available in XML version: 2.0 (version 9.0 of CWDirect). The outbound XML setting of the ORDER_IN job determines whether to include this tag as part of the customer history API; see Typical Customer History Flow: Different Response Message Types for a discussion.
gst_tax	numeric	10.5	The total GST tax, if any, applied to the order detail line. See GST Rate (A90) for a discussion. Available in XML version: 2.0 (version 9.0 of CWDirect). The outbound XML setting of the ORDER_IN job determines whether to include this tag as part of the customer history API; see Typical Customer History Flow: Different Response Message Types for a discussion.
pst_tax	numeric	10.5	The total PST tax, if any, applied to the order detail line. See GST Rate (A90) for a discussion. Available in XML version: 2.0 (version 9.0 of CWDirect). The outbound XML setting of the ORDER_IN job determines whether to include this tag as part of the customer history API; see Typical Customer History Flow: Different Response Message Types for a discussion.
set_main_item	alpha	1	Indicates whether the item is the main item of a set: Y = a main set item N = not a main set item Available in XML version: 4.0 (release 12.5 of CWDirect).
set_component_item	alpha	1	Indicates whether the item was added to the order as a component of a set: Y = a set component N = not a set component Available in XML version: 4.0 (release 12.5 of CWDirect).
set_seq_number	numeric	3	Indicates the sequence number that uniquely identifies a set and its components on this order. The main set item and its components have the same set sequence number. This attribute is not included for items that are not part of a set. Available in XML version: 4.0 (release 12.5 of CWDirect).
gift_wrap	alpha	1	Indicates whether the item should be gift wrapped: Y = gift wrap the item N = do not gift wrap the item Available in XML version: 5.0 (release 17.0 of CWDirect)
Shipment Note: See Reviewing Financial Information for more information on invoices for an order.
invoice_nbr	numeric	7	A unique number to identify an invoice. The system creates an invoice when you confirm shipment or process a return.
invoice_ship_ quantity	numeric	5	The total unit quantity of the item shipped and billed on this invoice. The quantity is negative for a return.
invoice_ship_date	numeric	8	The date when the shipment was confirmed, or when the return was credited. MMDDYYYY format.
invoice_tracking_ nbr	alpha	30	From the Manifest Upload Audit file. See PC Manifest Socket Interface for an overview.
invoice_ship_via_ code	numeric	2	From the Manifest Upload Audit file. See PC Manifest Socket Interface for an overview.
invoice_ship_via_ desc	alpha	30	From the ship via description, as set up through Working with Ship Via Codes (WVIA).
Promotion 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. Other types of promotions, such as those that apply a discount to item pricing, are not listed in this element, although any discounts they apply are reflected in the pricing indicated in the response message. Available in XML version: The Promotion element and all of its attributes are available in version 3.0 (release 10.0 of CWDirect).
promotion_type_code	alphanumeric	2	A code used to identify the type of promotion applied to the order. Valid values: FF = free freight FO = freight override FA = additional charge on freight promotion FV = ship via override on freight promotion AA = additional charge on additional freight promotion AV = ship via override on additional freight promotion OA = additional charge on order promotion OV = ship via override on order promotion TA = additional charge on tiered promotion TG = free gift on tiered promotion RA = additional charge on offer promotion RG = free gift on offer promotion SA = additional charge on source promotion SG = free gift on source promotion PI = package insert
			PT = premium See End of Order Discounts Applied during Repricing for more information about each promotion type. From the Promotion type field in the Order Discount Audit file.
promotion_type_code_desc	alphanumeric	25	A description of the type of promotion applied to the order. Valid values are: • free freight • freight override • additional charge on freight promotion • ship via override on freight promotion • additional charge on additional freight promotion • ship via override on additional freight promotion • additional charge on order promotion • ship via override on order promotion • additional charge on tiered promotion • free gift on tiered promotion • additional charge on offer promotion • free gift on offer promotion • additional charge on source promotion • free gift on source promotion • package insert • premium See End of Order Discounts Applied during Repricing for more information about each promotion type.
promotion_ original_ freight_amt	numeric	7.2	The freight amount for the order ship to before it was discounted by a freight promotion. This value is only populated for the FF (free freight) or FO (freight override) promotion types. From the Original freight field in the Order Discount Audit file.
promotion_ freight_amt	numeric	7.2	The freight amount for the order ship to after the freight promotion has been applied to the order. If freight is not being charged for the order ship to, the freight amount is 0.00. This value is only populated for the FF (free freight) and FO (freight override) promotion types. From the Promotion freight amt field in the Order Discount Audit file.
promotion_ addl_charge_ code	numeric	2	The additional charge code that was added to the order as a result of the promotion. This value is only populated for the following promotion types: • FA (additional charge on freight promotion) • AA (additional charge on additional freight promotion) • OA (additional charge on order promotion) • TA (additional charge on tiered promotion) • RA (additional charge on offer promotion) • SA (additional charge on source promotion) From the Add’l chg code field in the Additional Charge file. Based on the OAC seq # field in the Order Discount Audit file.
promotion_ addl_charge_ code_desc	alphanumeric	30	The description of the additional charge code that was added to the order as a result of the promotion. From the Description field in the Additional Charge file.
original_ shipping_ method	numeric	2	The ship via for the order ship to before it was overridden by the promotion. This value is only populated for the following promotion types: • FV (ship via override on freight promotion) • AV (ship via override on additional freight promotion) • OV (ship via override on order promotion) From the Original ship via field in the Order Discount Audit file.
original_ shipping_ method_desc	alphanumeric	30	The description of the ship via that was assigned to the order before it was overridden by the promotion. From the Shipper name field in the Ship Via file.
promotion_ shipping_ method	numeric	2	The ship via for the order ship to after the promotion has been applied to the order. This value is only populated for the following promotion types: • FV (ship via override on freight promotion) • AV (ship via override on additional freight promotion) • OV (ship via override on order promotion) From the Promotion ship via field in the Order Discount Audit file.
promotion_ shipping_ method_desc	alphanumeric	30	The description of the ship via that was assigned to the order as a result of the promotion. From the Shipper name field in the Ship Via file.
promotion_ item_id	alphanumeric	12	A code for the item that was added to the order as a result of a free gift, premium, or package insert. This value is only populated for the following promotion types: • TG (free gift on tiered promotion) • RG (free gift on offer promotion) • SG (free gift on source promotion) • PI (package insert) • PT (premium) From the ITM number field in the Order Detail file. Based on the ODT seq # field in the Order Discount Audit file.
promotion_ item_desc	alphanumeric	40	A description of the item that was added to the order as a result of a free gift, premium, or package insert. From the Description field in the Item file.
promotion_ sku	alphanumeric	14	A code for the SKU of the item that was added to the order as a result of a free gift, premium, or package insert. This value is only populated for the following promotion types: • TG (free gift on tiered promotion) • RG (free gift on offer promotion) • SG (free gift on source promotion) • PI (package insert) • PT (premium) From the SKU code field in the Order Detail file. Based on the ODT seq # field in the Order Discount Audit file.
promotion_ sku_desc	alphanumeric	40	A description of the SKU that was added to the order as a result of a free gift, premium, or package insert. From the Description field in the SKU file.
promotion_ offer_price	numeric	7.2	The offer price for the order detail line associated with the promotion, if one exists. This value is only populated for the following promotion types: • TG (free gift on tiered promotion) • RG (free gift on offer promotion) • SG (free gift on source promotion) • PI (package insert) • PT (premium) From the Offer price field in the Order Detail file.
promotion_ price	numeric	7.2	The selling price of the order detail line associated with the promotion. If the item is free of charge, the price is 0.00. This value is only populated for the following promotion types: • TG (free gift on tiered promotion) • RG (free gift on offer promotion) • SG (free gift on source promotion) • PI (package insert) • PT (premium) From the ODT price field in the Order Detail file.
promotion_ addl_charge_ amt	numeric	7.2	The amount of the additional charge that was applied to the order as a result of the promotion. Typically, this amount is a negative amount. This value is only populated for the following promotion types: • FA (additional charge on freight promotion) • AA (additional charge on additional freight promotion) • OA (additional charge on order promotion) • TA (additional charge on tiered promotion) • RA (additional charge on offer promotion) • SA (additional charge on source promotion) From the OAC Add’l charges field in the Order Discount Audit file.
promotion_ line_seq_nbr	numeric	5	The sequence number of the order line associated with the promotion. From the ODT seq # field in the Order Discount Audit file.
Ord_Msg The Ord_Msg element lists each order message whose Print flag is set to G (gift message). See Adding Order Messages for background. Available in XML version: The Ord_Msg and each of its attributes are available in version 5.0 (release 17.0 of CWDirect).
ord_msg_code	alphanumeric	1	Always set to G (gift message). Only gift messages are included in the CWORDEROUT message.
ord_msg_text	alphanumeric	60	A gift message entered for the order.

Detailed Order Inquiry Response Message: Sample XML

A sample of the Detailed Customer History Response XML Message (CWORDEROUT) is presented below. The CUST_HIST job generates this message if the Customer History Request XML Message (CustHistIn) specifies either the direct_order_number or the alternate_order_number and the send_detail flag is set to Y.

</Payments>

</Detail>

</Details>

<Ord_Msgs>

<Ord_Msg ord_msg_code="G" ord_msg_text="Merry Christmas and Happy New Year">

</Ord_Msg>

</Ord_Msgs>

</ShipTo>

</ShipTos>

</Header>

</Message>

Summary Order Inquiry Response XML Message (CWORDEROUT)

When the Customer History Request XML Message (CustHistIn) includes order information, the send_detail attribute is set to N, and the Customer History Outbound Message Type (J84) system control value is blank, the CUST_HIST job generates an XML response laid out as follows.

See Detailed Customer History Response XML Message (CWORDEROUT) for information on the response generated when the Customer History Request XML Message (CustHistIn) includes order information and the send_detail attribute is set to Y.

For more information: See:

• Detailed Customer History Response XML Message (CWORDEROUT) for descriptions of each attribute.

• Typical Customer History Flow: Different Response Message Types for a discussion of when you might use this message.

• XML Messages for a table that provides links to the DTD, schema, and a sample XML layout for each XML message.

Message

• source

• target

• type

Header

• company_code

• order_id

• reference_order_number

• customer_number

• alternate_sold_to_id

• bill_to_number

• order_date

• order_channel

• bill_me_later_ind

Summary Order Inquiry Response Message: Sample XML

A sample of the Summary Order Inquiry Response XML Message (CWORDEROUT) is presented below. The CUST_HIST job generates this message if the Customer History Request XML Message (CustHistIn) specifies either the direct_order_number or the alternate_order_number and the send_detail flag is set to N.

</Header>

</Message>

Store21 Customer History Response XML Message (CWCUSTHISTOUTSTORE21)

When the Customer History Outbound Message Type (J84) system control value is set to STORE21, the CUST_HIST job generates an XML response laid out as follows.