From NewHaven Software Wiki

Contents 1 Overview 2 Matching orders to existing customers during order import 3 Multi-recipient and Gift orders 4 Customer Duplicate Report

Overview

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

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

Matching orders to existing customers during order import

When importing orders from any source, CMS will attempt to find that order's customer in the mail list so it can be added to that customer's history. This document will explain how and where CMS does this matching and what controls you have over it.

Presently all imported orders must go through a verification process (Fulfillment>Verify Imports) so you can ensure 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.
2. Most sources of orders will not be able to establish and/or pass the proper customer number so it is 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 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 and abbreviations. Here is an example:

William Smith
123 Main Street Apt 3
Evanston, IL 60202

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 which 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. This is handled 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, 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) 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 changes, however, in CMS 9.0 (Summer 2012) where you will be able to have the same recipient on the order multiple times.

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 zipcode, 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 total 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 diff 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.)