From NewHaven Software Wiki

Contents 1 Overview 2 Matching orders to existing customers during order import 3 Multi-recipient and Gift orders 4 Address Display and Handling During Verify Imports 5 Customer Duplicate Report

Overview

When an order or catalog request is imported into CMS, from any source, CMS must take steps to identify if this is a new or existing customer. If it is a new customer, you'd want CMS to create a new customer record. On the other hand, if it is for an existing customer, you'd want CMS to attach the order or catalog request to its matching/existing customer record and not create a duplicate customer.

This article explains the logic used by CMS uses when trying to determine a customer match during an import. A similar process is used to determine if the recipient (ship-to) is different from the buyer and this is also covered here.

Matching orders to existing customers during order import

All imported orders that are not imported with the Automated Imports Module option must go through a verification process (Fulfillment->Verify Imports) so you can ensure that the imported order is one that should be converted into a real order. During that verification process, you can tell if a customer match was found by looking at the Cust# field on the View Invoice screen (the first screen you are presented with when verifying an order). If there is a number in this field, you know CMS has matched it up to a customer in your mail list. If no match was found, the Cust# field will instead say "<new>". The logic CMS uses to find such matches is as follows:

1. If a customer number was passed in the file, CMS will use that customer number to match against the customer number in CMS and will append to that customer. No further matching logic will be used. Most sources of orders will not be able to establish and/or pass the proper customer number so, while it will be considered the best match if present...it usually isn't.
2. The next matching will be done on email address (CMS 9.0.1 or later. To disable the option you need to be on CMS version 9.0.4 or later, and then remove the check on the setup option under Fulfillment Options->Import). CMS will match the order to a unique customer record it finds with the same email address. If more than one customer record is found with the same email address, no match will be made by email address. Note: in the XML only the <Order><Customer><ContactAddress><Address><Email> element is used for email address matching.
3. If no customer number or email match is found, it is then up to CMS to scrutinize the name and address to find a match. In this case CMS will match the last name and all of the numbers from the address and 5 digit ZIP code. (Note: this matching is done by comparing the customer's mailing address against the order's mailing/primary address, not billing or shipping.) Only when there is a perfect match will CMS link the imported order to a customer. The reason CMS uses numbers only for the address and only a last name is to ensure the match does not get tripped up by middle initials, misspellings, punctuation, or abbreviations. Here is an example:

William Smith
123 Main Street Apt 3
Evanston, IL 60202-1234

will still match

Bill P. Smith
123 Main St. #3
Evenston, IL 60202

If you should find that CMS has matched up an order to the wrong customer or did not find a customer that it should have, during the verification of the order you can still go to the first screen on the order (Customer) and retrieve the proper customer there. Be warned that when retrieving a customer in this manner, it will replace the billing and shipping addresses from the imported order with the default addresses from the retrieved customer record. We expect this behavior to change in the future so CMS will retain the addresses from the imported order or give you the option of which one(s) to use.

Multi-recipient and Gift orders

CMS is capable of handling and importing orders with multiple recipients and/or gift orders (where the recipient is different than the buyer). In either of the two scenarios, the purchaser may or may not be receiving merchandise themselves. When importing such orders, CMS needs to determine if the recipient(s) is the same as the purchaser or if they should be treated as someone else. The reason for this is CMS will/can (optionally) create new customer records for recipients. Additionally, when printing invoices/pick-tickets, CMS will suppress prices from showing so that the recipient will not see what you paid.

The logic used to determine if the recipient is the same as the buyer works in the following ways:

1. In our XML specification document (CMSxml.xsd) there is an attribute of the <Recipient> tag that reads "IsPurchaser". If the system that is generating the output for CMS to import is capable, our first recommendation would be to use this attribute. In use it looks like: <Recipient IsPurchaser="false"> In this example the value of "false" is telling CMS that the recipient is not the same as the purchaser and as such should treat this as a gift order, even if there are no gift notes. If the purchaser is shipping to themselves, even at a different address, this value should be "true".
2. If any gift notes are present, CMS assumes the buyer is not sending themselves a gift ,and will make the order a gift order (multiple ship-to, in this case with just one recipient.
3. If there are no gift notes and there is no "IsPurchaser" attribute passed in the import, CMS then has to determine if the recipient and purchaser are the same or not. In this case, CMS is only using the last name. If the last name matches exactly, CMS will treat the recipient as if they are the purchaser, even if the addresses or any other information is different. While there are a few scenarios where this logic fails (parents shipping to their kid at college, for example), it is the best CMS can do without having the information from 1 and 2 above. It does ensure, though, that the more common scenario of a person shipping to themselves at another address (work, vacation, etc.) will be handled correctly as a normal, non-gift type order.

Note: CMS uses an internal address_id to uniquely identify the recipient in an order. This means the same customer/recipient cannot appear more than once in the order but otherwise there is no reason why you cannot have two recipients with the same name (as long as they are different customers.) This has changed in CMS 9.0 where you can now have the same recipient on the order multiple times.

Address Display and Handling During Verify Imports

When cycling through orders in Verify Imports, you'll see an address displayed. This address is the address from the Customer node of the imported order's XML. This section explains in a bit more detail about how addresses are used during imports and verification.

In most order imports, including those from CommerceV3 (CV3), the order file only contains a customer and shipping address. Our XML allows for a separate billing address to be specified but is rarely done. As such CMS will use the Customer address from the XML as the billing address. Even if a billing address is included in the XML, CMS will still display the customer address.

The really important point to understand though is that you are looking at the XML data only at this point. No attempt has been made to match it to an existing customer yet (or allocate stock or anything else). That all happens at the moment you click Verify.

If CMS does match to an existing customer, particularly a match by email address, the Customer address from the customer list in CMS could be very different than the Customer address in the XML. Either way, the order will retain the original Customer address from the XML as its billing address.

It may also help at this point to reinforce that an order really only has two addresses, shipping and billing. The address you see on the Customer tab of Order Entry is the address from the purchasing customer record, essentially a mini version of the Contact Manager, and that data is stored with the customer, not the order. This is why on the View Invoice tab of order entry, we only show Sold-to (Billing) and Ship-to addresses.

Customer Duplicate Report

Also worthy of note is the Customer Duplicate report used for finding possible duplicates. This report is found in the Reports menu under the category Customers. The logic this report uses is a bit different than CMS's and can be a good tool to find those that made it past CMS's logic. The most notable difference in logic is that it is matching on physical or email address, not by name.

Matches are on state, city, 5-digit ZIP code, then first 10 digits of either the Address3 line or Address1 line, depending on which has data.

This system has a lot of merit in that it is totally independent of name spellings or most cases of address spellings (even St vs Street) since only the first 10 characters are considered. (UPDATE: As of CMS 8.0 this report now allows you to select how many characters to consider which allows you to control the level of sensitivity.) This system is really matching on the address vs. the customer, so if you had a husband and wife with different names at the same address, you'd find them as a possible dupe match. This should prove to be a good tool to find duplicates that escaped CMS's customer matching (or dupes created by operators for non-imported orders.)

Alternate search terms - customer matching, order imports, order importing, name matching