Changing a Customer using the Customer API

When CWSerenade determines the Inbound Customer Message (CWCustomerIn) is a Change request (see Determining Whether to Add or Change a Customer), the system updates the customer based on the information provided in the message.

• Required Attributes for Change Requests

• Determining the Customer to Update

• Using a Default Customer as a Guideline for Change Requests

• Error Checking for Change Requests

• Send Response for Change Request?

• Fixing Errors and Reprocessing a Change 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 Change requests, the system bypasses all edits except Customer Does not Exist.

Required Attributes for Change Requests

To change a customer, at minimum you must define the following attributes in the Inbound Customer Message (CWCustomerIn):

• type = CWCustomerIn

• cst_cust_nbr, cst_relate_id, OR cst_interface_cust_nbr; see Determining the Customer to Update

• If a Default Customer for Customer API (I90) is defined and you do not define a value for an attribute, the system uses this customer to determine whether to update the field for the customer to blank or to retain the customer’s existing value. See Using a Default Customer as a Guideline for Change Requests.

If a Default Customer for Customer API (I90) is not defined, you must also define the following attributes:

• cst_ company

• cst_lname or cst_company_name

• cst_street_addr

• 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.

Determining the Customer to Update

The system uses the cst_cust_nbr, cst_interface_cust_nbr, and cst_relate_id included in the Inbound Customer Message (CWCustomerIn) to determine the customer to update.

If the message includes a customer number only: If the message includes a cst_cust_nbr but no cst_interface_cust_nbr or cst_relate_id:

• Match: If the cst_cust_nbr matches an existing customer, CWSerenade selects this customer for update.

• No match: If the cst_cust_nbr does not match an existing customer, CWSerenade places the request in E (error) status. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).

If the message includes a customer number and alternate customer number: If the message includes a cst_cust_nbr and cst_interface_cust_nbr but no cst_relate_id:

• Match: If the cst_cust_nbr matches an existing customer, CWSerenade selects this customer for update and adds the cst_interface_cust_nbr to the Customer Sold To Xref table if it does not already exist.

• No match: If the cst_cust_nbr does not match an existing customer, CWSerenade places the request in E (error) status. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).

If the message includes a customer number and Relate ID: If the message includes a cst_cust_nbr and cst_relate_id, the system uses the following logic.

Does matching CWSerenade customer have Relate ID?	Do other CWSerenade customers have Relate ID?	Results:
If the cst_cust_nbr matches an existing customer, but the customer is not associated with the specified cst_relate_id...	and other customers are not associated with the specified cst_relate_id...	CWSerenade selects this customer for update and updates the Relate ID in the Customer Sold To table with the cst_relate_id included in the message. If the message also contains a cst_interface_cust_nbr, the system adds the cst_interface_cust_nbr to the Customer Sold To Xref table if it does not already exist.
	and one or more other customers are associated with the specified cst_relate_id...	CWSerenade places the message in E Error status for the reason Relate ID matched multiple customers. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).
If the cst_cust_nbr matches an existing customer, and the customer is associated with the specified cst_relate_id...	regardless of whether other customers are associated with the specified cst_relate_id...	CWSerenade selects this customer for update and retains the Relate ID in the Customer Sold To table since it matches the cst_relate_id included in the message. If the message also contains a cst_interface_cust_nbr, the system adds the cst_interface_cust_nbr to the Customer Sold To Xref table if it does not already exist.
If the cst_cust_nbr matches an existing customer, but the customer’s Relate ID does not match the specified cst_relate_id...	and other customers are not associated with the specified cst_relate_id...	CWSerenade selects this customer for update and updates the Relate ID in the Customer Sold To table with the cst_relate_id included in the message. If the message also contains a cst_interface_cust_nbr, the system adds the cst_interface_cust_nbr to the Customer Sold To Xref table if it does not already exist.
	and other customers are associated with the specified cst_relate_id...	CWSerenade places the message in E Error status for the reason Relate ID matched multiple customers. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).
If the cst_cust_nbr does not match an existing customer...	regardless of whether other customers are associated with the specified cst_relate_id...	CWSerenade places the request in E (error) status. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).

If the message includes a Relate ID and no customer number: If the message includes a cst_relate_id but no cst_cust_nbr:

• No match: If the cst_relate_id does not match an existing customer, CWSerenade considers the message an Add request; see Adding a Customer using the Customer API.

• Single match: If the cst_relate_id matches a single customer, CWSerenade selects this customer for update. If the message also contains a cst_interface_cust_nbr, the system adds the cst_interface_cust_nbr to the Customer Sold To Xref table if it does not already exist.

• Multiple match: If the cst_relate_id matches more than one customer, CWSerenade places the request in E Error status for the reason Relate ID matched multiple customers. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).

If the message includes an alternate customer number and no customer number or Relate ID: If the message includes a cst_interface_cust_nbr but no cst_cust_nbr or cst_relate_id:

• No match: If the cst_interface_cust_nbr does not match an existing customer based on the records in the Customer Sold To Xref table, CWSerenade considers the message an Add request; see Adding a Customer using the Customer API.

• Single match: If the cst_interface_cust_nbr matches a single customer based on the records in the Customer Sold To Xref table, CWSerenade selects this customer for update.

• Multiple match: If the cst_interface_cust_nbr matches multiple customers based on the records in the Customer Sold To Xref table, CWSerenade places the request in E Error status for the reason Alternate customer # matched multiple customers. You cannot correct this type of error through Working with Customer API (WCAI); you must delete the message in error and either resend the message or manually update the customer in Creating and Updating Sold-to Customers (WCST).

Note: Regardless of the setting of the Display Alternate Customer Cross Reference Window (I84) system control value, the system attempts to match the cst_interface_cust_nbr to any of the alternate customer numbers stored in the Customer Sold To Xref table and does not try to match the cst_interface_cust_nbr to the alternate customer number stored in the Customer Sold To table.

For more information: See Working with Alternate Customer Number Cross-References for more information on the Customer Sold To Xref table.

Using a Default Customer as a Guideline for Change Requests

The system uses the customer defined in the Default Customer for Customer API (I90) system control value to identify which fields can be cleared if they are not specified in a Change request.

For each field that is not provided in the Inbound Customer Message (CWCustomerIn), the Customer API checks the corresponding field for the default customer.

• If that field contains any data in the default customer record, then the Customer API does not clear the information in that field for the customer being updated.

• If that field does not contain data in the default customer record, then the Customer API clears that field when updating the customer.

Note: It does not matter what the data is in the corresponding field for the default customer record; the process simply checks to see whether there is any data.

Default Customer Examples:

If the Default Customer has:	and the Change Request:	The system:
The first, middle and last name populated	does not include a first, middle or last name	Retains the first, middle, and last name of the customer being updated in the Change request
	includes a last name but no first or middle name	Updates the last name and retains the first and middle name of the customer being updated in the Change request
The last name populated, but the first and middle name are blank	does not include a first, middle or last name	Retains the last name and clears the first and middle name of the customer being updated in the Change request
	includes a last name but no first or middle name	Updates the last name and clears the first and middle name of the customer being updated in the Change request

For more information: See the Default Customer for Customer API (I90) for a discussion.

Error Checking for Change Requests

After Determining the Customer to Update, the system determines if the Change request contains any errors:

• No errors: The system updates 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 updated. 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.

Note: A Change request does not normally go into error status because of missing information, because the use of the Default Customer for Customer API (I90) usually prevents essential information from being cleared from an existing customer record.

For more information: See the Inbound Customer Message (CWCustomerIn) for complete information on field edits and possible errors.

Error Checking for Change Requests:

Send Response for Change 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 Change Request if the change request was successful

• Customer Message: Failure Change Request if the change request failed

Fixing Errors and Reprocessing a Change Request

You can use the Change Customer API Screen in Working with Customer API (WCAI) to identify and correct errors related to a Change request. When you advance to the Change Customer API screen and select OK, the system indicates any errors in the Change request. You can then correct the error and reprocess the request to update the customer, or delete the request if you do not want to process the update.