Adding a Customer using the Customer API
When CWSerenade determines the Inbound Customer Message (CWCustomerIn) is an Add request (see Determining Whether to Add or Change a Customer), the system creates the customer based on the information provided in the message.
• Required Attributes for Add Requests
• Duplicate Checking for Add Requests
• Duplicate Check S: If Single Match Found, Update Customer
• Duplicate Check A: If Multiple Matches Found, Update Best Match Customer
• Duplicate Check Y: If Any Match Found, Do Not Update Customer
• Duplicate Check N: Do Not Perform Duplicate Checking
• Error Checking for Add Requests
• Send Response for Add Request?
• Fixing Errors and Reprocessing an Add Request
Bypass validation? If the Bypass Customer API Edit (L93) system control value is selected, customer API transactions bypass validation when creating or changing a customer with an original source code of XSTORE. For Add requests, the system bypasses all edits except Duplicate Checking for Add Requests.
Required Attributes for Add Requests
To create a customer, at minimum you must define the following attributes in the Inbound Customer Message (CWCustomerIn):
• type = CWCustomerIn
• cst_lname or cst_company_name
• cst_city
• cst_state if the cst_country requires a state; otherwise, optional
• cst_zip if the cst_country requires a postal code; otherwise, optional
• cst_country unless a default is defined in the Default Country for Customer Address (B17) system control value
• cst_cust_class if the Require Customer Class in OE, WCAT, and WCST (H85) system control value is selected; otherwise, optional
• cst_email_status unless a default is defined in the Default Opt In/Opt Out Flag (G97) system control value
QAS address interface: The system first submits a customer address to QAS for address standardization if the Perform Address Standardization in Customer API (I99) system control value is selected and you are Using the QAS Address Interface. The address standardization is applied before any duplicate checking or other edits, and takes place only if there is a single matching address (the QAS Address Response Match Level is Verified). See Using the QAS Address Interface for an overview and required setup.
Duplicate Checking for Add Requests
Before creating a customer, the system determines whether the customer information in an Add request matches an existing customer.
Types of duplicate checking: The cst_duplicate flag defines how the system checks for duplicates:
• Duplicate Check S: If Single Match Found, Update Customer
• Duplicate Check A: If Multiple Matches Found, Update Best Match Customer
• Duplicate Check Y: If Any Match Found, Do Not Update Customer
• Duplicate Check N: Do Not Perform Duplicate Checking
Duplicate Check S: If Single Match Found, Update Customer
The system performs the following logic when the cst_duplicate flag is set to S.
1. |
Check for duplicates: The system determines whether the customer information specified in the Add request matches an existing customer using: • Match code: The system checks for duplicates using the match code. If there are no existing customers with the same match code as the customer information in the Add request, the system does not consider the Add request a duplicate and proceeds to check the message for errors (see Error Checking for Add Requests); otherwise, • Phone interface values: If there are existing customers with the same match code as the customer information in the Add request, the system uses the Phone Interface Values (F70) as a guideline to check for duplicates. For example, if these values indicate that the customer’s first name does not need to be an exact match, the system does not consider this type of customer information to constitute a match, and continues to the next step. Note: When matching on street address or address line 2, the system does not include the roadway descriptive in the match if it is the last word in the address line; see Exact Match Required on Street Address for Phone Interface and Exact Match Required on Address Line 2 for Phone Interface for a list of road descriptives the system excludes. |
2. |
Single match found? If a single duplicate match is found, the system updates the existing customer with the information in the Inbound Customer Message (CWCustomerIn). See Changing a Customer using the Customer API. If the cst_send_response flag in the request is set to: • Y: the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Success. The updated customer information is provided in the CustSoldTo element. See Sample Customer API XML Messages. • N: the system does not send the CWCustomerOut message. |
3. |
Multiple matches found? If the system finds multiple duplicate existing customers based on the match code and Phone Interface Values (F70), the system does not create or update any customers. If the cst_send_response flag in the request is set to: • Y: the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Duplicate. The first duplicate customer record that the system found is provided in the CustSoldTo element, and any additional duplicate customers are provided in a Duplicate element. See Sample Customer API XML Messages. • N: the system does not send the CWCustomerOut message. |
Duplicate Check S Example: The Inbound Customer Message (CWCustomerIn) contains the following customer information:
Julie Robinson
100 Example Street
Westborough, MA 01581
Email jrobinsexample.com
508-555-0100
CWSerenade finds a single customer with the same match code and an exact match based on the Phone Interface Values (F70).
Customer 13962:
Juliette Robinson
100 Example Street
Westborough, MA 01581
Email jrobison@example.com
508-555-0101
Because a single match is found and the cst_duplicate flag is set to S, the system validates the information in the Inbound Customer Message (CWCustomerIn) and updates customer 13962 if the validation is successful. If the cst_send_response flag in the request is set to Y, the system sends the updated customer information in the Outbound Customer Response Message (CWCustomerOut).
Duplicate Check S Flowchart:
Duplicate Check A: If Multiple Matches Found, Update Best Match Customer
The system performs the following logic when the cst_duplicate flag is set to A.
1. |
Check for duplicates: The system determines whether the customer information specified in the Add request matches an existing customer using: • Match code: The system checks for duplicates using the match code. If there are no existing customers with the same match code as the customer information in the Add request, the system does not consider the Add request a duplicate and proceeds to check the message for errors (see Error Checking for Add Requests); otherwise, • Phone interface values: If there are existing customers with the same match code as the customer information in the Add request, the system uses the Phone Interface Values (F70) as a guideline to check for duplicates. For example, if these values indicate that the customer’s first name does not need to be an exact match, the system does not consider this type of customer information to constitute a match, and continues to the next step. |
2. |
Single match found? If a single duplicate match is found, the system updates the existing customer with the information in the Inbound Customer Message (CWCustomerIn). See Changing a Customer using the Customer API. If the cst_send_response flag in the request is set to: • Y: the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Success. The updated customer information is provided in the CustSoldTo element. See Sample Customer API XML Messages. • N: the system does not send the CWCustomerOut message. |
3. |
Multiple matches found? If the system finds multiple duplicate existing customers based on the match code and Phone Interface Values (F70), the system updates the first customer match (this is the customer with the highest customer number) with the information in the Inbound Customer Message (CWCustomerIn). See Changing a Customer using the Customer API. If the cst_send_response flag in the request is set to: • Y: the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Success. The updated customer information is provided in the CustSoldTo element. See Sample Customer API XML Messages. • N: the system does not send the CWCustomerOut message. |
Duplicate Check A Example: The Inbound Customer Message (CWCustomerIn) contains the following customer information:
Robert Dryer
100 Example Street
Westborough, MA 01581
Email rdryer@example.com
508-555-0100
CWSerenade finds multiple customers with the same match code and exact match based on the Phone Interface Values (F70). The first customer match (the customer with the highest customer number) is customer 14551:
Bob Dryer
100 Example Street
Westborough, MA 01581
Email rdryer@example.com
508-555-0100
Because customer 14551 has been identified as the best match and the cst_duplicate flag is set to A, the system validates the information in the Inbound Customer Message (CWCustomerIn) and updates customer 14551 if the validation is successful. If the cst_send_response flag in the request is set to Y, the system sends the updated customer information in the Outbound Customer Response Message (CWCustomerOut).
Duplicate Check A Flowchart:
Duplicate Check Y: If Any Match Found, Do Not Update Customer
The system performs the following logic when the cst_duplicate flag is set to Y.
1. |
Check for duplicates: The system determines whether the customer information specified in the Add request matches an existing customer using: • Match code: The system checks for duplicates using the match code. If there are no existing customers with the same match code as the customer information in the Add request, the system does not consider the Add request a duplicate and proceeds to check the message for errors (see Error Checking for Add Requests); otherwise, • Phone interface values: If there are existing customers with the same match code as the customer information in the Add request, the system uses the Phone Interface Values (F70) as a guideline to check for duplicates. For example, if these values indicate that the customer’s first name does not need to be an exact match, the system does not consider this type of customer information to constitute a match, and continues to the next step. |
2. |
Duplicates found? If the system finds one or more duplicate existing customers based on the match code and Phone Interface Values (F70), the system does not create or update any customers. If the cst_send_response flag in the request is set to: • Y: the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Duplicate. The first duplicate customer record (this is the duplicate with the highest customer number) that the system found is provided in the CustSoldTo element, and any additional duplicate customers are provided in a Duplicate element. See Sample Customer API XML Messages. • N: the system does not send the CWCustomerOut message. |
Duplicate Check Y Flowchart:
Duplicate Check N: Do Not Perform Duplicate Checking
If the cst_duplicate flag is N or any other value, the system does not perform any duplicate checking based on name and address.
Error Checking for Add Requests
After completing any duplicate checking, or if the cst_duplicate setting in the Add request is N, the system determines if the Add request contains any errors:
• No errors: The system creates the customer. If the cst_send_response flag in the request is Y, the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Success. The response indicates the customer name, address, and customer number created. See Sample Customer API XML Messages.
• Errors: If any of the required values for a customer are missing or invalid, the system places the message in error in Working with Customer API (WCAI). If the cst_send_response flag in the request is Y, the system generates the Outbound Customer Response Message (CWCustomerOut) with a cst_action_result of Failure. See Sample Customer API XML Messages.
For more information: See the Inbound Customer Message (CWCustomerIn) for complete information on field edits and possible errors.
Error Checking for Add Requests:
Send Response for Add Request?
If the cst_send_response flag is Y, the system generates an Outbound Customer Response Message (CWCustomerOut) such as the following:
• Customer Message: Successful Add Request if the add request was successful
• Customer Message: Duplicate Add Request if the add request failed duplicate checking
• Customer Message: Failure Add Request if the add request failed
Fixing Errors and Reprocessing an Add Request
You can use the Change Customer API Screen in Working with Customer API (WCAI) to identify and correct errors related to an Add request. When you advance to the Change Customer API screen and select OK, the system indicates any errors in the Add request. You can then correct the error and reprocess the request to create the customer, or delete the request if you do not want to create the new customer.
