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

This article exposes the logic CMS uses when trying to match an order to a customer during import or when trying to determine if a recipient for an order is the same as the buyer.

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 made 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 with no further scrutiny.
2. Most sources of orders will not be able to establish and/or pass the proper customer number so CMS then has to look to 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-1234

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 case 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 spec, 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 the address_id to uniquely identify the recipient in an order. This means the same customer/recipient cannot appear more than once in the recipient list but otherwise there is no reason why you cannot have two recipients with the same name (as long as they are different customers.)

Customer Duplicate Report

Also worthy of note is this Customer Duplicate report that was added to version 5 for finding possible duplicates. His logic is a bit different than ours so can be a good tool to find those that made it past CMS's logic. Most notably, it is matching on address and not 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. 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 is considerably different than the logic CMS uses so should prove to be a good tool to find those that escaped CMS's customer matching.