Receiving First and Last Names for Buyers and Shipping Recipients

Overview

This document explains a Google Checkout feature that enables merchants to receive names of buyers and order recipients in structured fields that identify the first and last name of those people. This feature is designed to help merchants more easily identify and reconcile duplicate customer accounts.

The following instructions explain how to enable this feature for your account. Please note that you must complete these steps for your sandbox and production accounts:

• Log in to your merchant account.
• Click on the Settings tab.
• Click the Integration link on the left side of the page.
• Expand the list of advanced settings and check the box next to the setting that says, "Provide the first name, last name and full name of the buyer and order recipient in separate fields in the new order notification."
• Click the Save button to update your settings.

After you enable this setting, Google will include structured names in your new order notifications. A structured name consists of a first and last name. The structured name is provided in addition to the contact name that is already included in your new order notifications.

This document contains the following sections.

• The Receiving Structured Names section explains how structured names appear in new order notifications.

• The Matching Names in Notifications to Names in Your Database section discusses some of the rules that Google uses to parse the first and last name from a contact name. These rules may help you to better reconcile names with the names in your database.

• The XML Tag Definitions section defines the XML tags used for the structured name feature.

Receiving Structured Names

Google sends structured names in new order notifications. To receive new order notifications, you must have implemented the Notification API.

If you opt to receive structured names, your new order notifications will contain a <structured-name> tag within both the <buyer-billing-address> and <buyer-shipping-address> tags. Each <structured-name> tag, in turn, has two subtags, <first-name> and <last-name>. Your new order notifications will still continue to use the <contact-name> tag to communicate the full name of the buyer or order recipient.

The following XML example shows the basic structure of a new order notification. Several tags have been removed from the example to highlight the change described in this document. Omitted tags are represented by ellipses (...). In addition, new tags that contain structured names are shown in bold text.

<?xml version="1.0" encoding="UTF-8"?>
<new-order-notification xmlns="http://checkout.google.com/schema/"
    serial-number="85f54628-538a-44fc-8605-ae62364f6c71">
    ...
    <buyer-billing-address>
        <contact-name>Bill Hu</contact-name>
        ...
        <structured-name>
            <first-name>Bill</first-name>
            <last-name>Hu</last-name>
        </structured-name>
    </buyer-billing-address>
    <buyer-shipping-address>
        <contact-name>Will Shipp-Toomey</contact-name>
        ...
        <structured-name>
            <first-name>Will</first-name>
            <last-name>Shipp-Toomey</last-name>
        </structured-name>
    </buyer-shipping-address>
    ...
</new-order-notification>

Matching Names in Notifications to Names in Your Database

Please note that you should only use structured name information to identify duplicate customer accounts. Since name parsing cannot be executed with 100 percent accuracy, we recommend that you avoid using the first and last names for shipping orders, marketing emails or other communications.

We recommend that you reconcile duplicate accounts by comparing a structured name and the corresponding billing or shipping address against your customer database. The name should only be considered a duplicate of a user in your database if the name and address both match an account in your database.

Google applies several rules to parse the first name and last name from the <contact-name> value. Understanding these rules may help you to match structured names to names in your database.

• If the structured name feature is enabled and there is a contact name for the buyer and/or recipient of an order, the new order notification for the order will contain the <structured-name> tag for each of those contacts. However, if Google cannot determine how to split the contact name into a first and last name, the <first-name> tag, <last-name> tag or even both of those tags may contain empty values.

• Google removes common prefixes, such as "Mr.", "Mrs." and "Dr.", from the contact name before identifying the first and last name.

• Google removes common suffixes, such as "Jr.", "Sr." and "Ph.D." from the contact name before identifying the first and last name.

• Google appends additional words and characters between a first and last name to the first name with the exception of common last name prefixes like "del" and "von". For example, if the contact name is John K. Smith, the <first-name> value will be John K. and the <last-name> value will be Smith. However, if the contact name is Benicio del Toro, the <first-name> value will be Benicio and the <last-name> value will be del Toro.

Since Google's name-splitting rules may not directly correlate to the way you store names in your database, you may want to test different methods for matching the names in new order notifications to the names in your database. Specifically, we recommend that you use case-insensitive matching for both names and addresses. You can also adjust matching rules to account for capitalization, punctuation, and other nonalphanumeric characters, such as spaces. For example, it may be easier to match the name johnksmith than John K. Smith.

XML Tag Definitions