Commerce

8.5.x

Customer Related Object Types

Customer

Customer records can have various types:

  • SINGLE_SESSION_USER: Represents a shopper who browsed the site and may have added to cart or even made a purchase but did not register or login.
  • REGISTERED_USER: Represents a shopper who has created an account in the store.
  • ACCOUNT: Represents an organization that shoppers can transact on behalf-of, if they are associated to it.

The customer XML file contains standard customer data (name, street, address, etc) and Customer Profile Attributes.

note

Customers of type SINGLE_SESSION_USER can be imported, but are not normally exported unless the shopper made a purchase.

Sample XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customers>
    <customer shared_id="81038963-880d-4df1-a2b8-eeee1ae57223" guid="43a62961-a4e3-4194-81be-f3ecd8d221ed" store_code="SNAPITUP">
        <customer_type>REGISTERED_USER</customer_type>
        <status>1</status>
        <first_time_buyer>false</first_time_buyer>
        <creationDate>2010-06-16T00:00:00-07:00</creationDate>
        <last_edited>2010-06-16T00:00:00-07:00</last_edited>
        <username>alana.abercombie@elasticpath.com</username>
        <password>f9708c2c03e485b937d430c479e88cb579871f15f97a4fb28e7c3b1f9d669fc1</password>
        <salt>c8a03968f60a1e94db8718eea7529f7bf2a5263ff1d5c4d660014cabc5643f1d</salt>
        <oidc_subject>cc7a2266-f681-11ed-b67e-0242ac120002</oidc_subject>
        <addresses>
            <address guid="2B057A60-C6C3-24B0-163F-20D8965E8A41">
                <last_name>Abercombie</last_name>
                <first_name>Alana</first_name>
                <phone_number>4313895083</phone_number>
                <street1>1020 Main Street</street1>
                <street2></street2>
                <city>Santa Cruz</city>
                <subCountry>CA</subCountry>
                <zip_postal_code>52844</zip_postal_code>
                <country>US</country>
                <commercial>false</commercial>
            </address>
        </addresses>
        <groups>
            <group>400</group>
        </groups>
        <preferred_shipping_address>2B057A60-C6C3-24B0-163F-20D8965E8A41</preferred_shipping_address>
        <preferred_billing_address>2B057A60-C6C3-24B0-163F-20D8965E8A41</preferred_billing_address>
        <customer_profile>
            <profile_value type="AttributeType_ShortText" key="CP_EMAIL">alana.abercombie@elasticpath.com</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_FIRST_NAME">Alana</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_LAST_NAME">Abercombie</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_PREF_LOCALE">en</profile_value>
            <profile_value type="AttributeType_Date" key="CP_DOB">1941-02-23</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_PHONE">4313895083</profile_value>
        </customer_profile>
    </customer>
    <customer shared_id="395f0b80-4ce5-4db3-bcf2-72f2e815a541" guid="0cd0da1d-0d8f-4da0-b7f4-a3bb99f4e43a" store_code="SNAPITUP">
        <customer_type>SINGLE_SESSION_USER</customer_type>
        <status>1</status>
        <creationDate>2020-06-16T00:00:00-07:00</creationDate>
        <last_edited>2020-06-16T00:00:00-07:00</last_edited>
        <addresses>
            <address guid="79848dde-bd97-4a19-8e6e-bf946ff58f02">
                <last_name>Barker</last_name>
                <first_name>Bob</first_name>
                <phone_number>1234567890</phone_number>
                <street1>123 Main Street</street1>
                <street2></street2>
                <city>Seattle</city>
                <subCountry>WA</subCountry>
                <zip_postal_code>80001</zip_postal_code>
                <country>US</country>
                <commercial>false</commercial>
            </address>
        </addresses>
        <groups>
            <group>400</group>
        </groups>
        <preferred_shipping_address>79848dde-bd97-4a19-8e6e-bf946ff58f02</preferred_shipping_address>
        <preferred_billing_address>79848dde-bd97-4a19-8e6e-bf946ff58f021</preferred_billing_address>
        <customer_profile>
            <profile_value type="AttributeType_ShortText" key="CP_EMAIL">bob.barker@elasticpath.com</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_FIRST_NAME">Bob</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_LAST_NAME">Barker</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_PREF_LOCALE">en</profile_value>
            <profile_value type="AttributeType_ShortText" key="CP_PHONE">1234567890</profile_value>
        </customer_profile>
    </customer>
    <customer shared_id="55214037-db81-4ee8-a6fc-5d8664a0e383" guid="f8d95101-ac48-4758-960c-a14dc7ba2fcf" parent_guid="1b5853ff-6f7e-42a2-8054-eabcbbc9f437">
        <customer_type>ACCOUNT</customer_type>
        <status>1</status>
        <creationDate>2020-07-01T00:00:00-07:00</creationDate>
        <last_edited>2020-07-01T00:00:00-07:00</last_edited>
        <addresses>
            <address guid="f7310642-0d13-404f-b732-bb7f0e208b62">
                <last_name>Yeager</last_name>
                <first_name>Chuck</first_name>
                <phone_number>9876543210</phone_number>
                <street1>1 Flight Street</street1>
                <street2></street2>
                <city>New York</city>
                <subCountry>NY</subCountry>
                <zip_postal_code>12345</zip_postal_code>
                <country>US</country>
                <commercial>false</commercial>
            </address>
        </addresses>
        <groups>
            <group>400</group>
        </groups>
        <preferred_shipping_address>f7310642-0d13-404f-b732-bb7f0e208b62</preferred_shipping_address>
        <preferred_billing_address>f7310642-0d13-404f-b732-bb7f0e208b62</preferred_billing_address>
        <customer_profile>
            <profile_value type="AttributeType_ShortText" key="AP_NAME">Flights Inc.</profile_value>
            <profile_value type="AttributeType_ShortText" key="AP_PHONE">9876543210</profile_value>
        </customer_profile>
    </customer>
</customers>

Payment Methods

Generic Payment Methods

The payment_methods collection element has the ability to take a mixture of payment methods. Currently we support both credit cards and payment tokens. The credit card element specified in the collection is identical to the legacy credit card element in the collection of credit_card elements. The default value on a credit card specified in the payment_methods collection element is ignored because a default_payment_method element now exists on customer.

Default Payment Method

The default payment method element wraps a default payment method which can currently be either a payment_token or credit_card. This payment method is set as the default payment method on a customer imported into the system.

Backwards Compatibility

The legacy credit_cards collection element is still supported and can be used to import credit cards on a customer. An exported customer will however populate the payment_methods collection element with all customer payment methods and the credit_cards collection element will always be empty for newly exported customers.

The billing address on customer credit cards is no longer supported. Thus, the billing_address_guid element is deprecated. If used, it will be ignored by the Import-Export tool.

Customer Group

Customer groups (also known as customer segments) are markers that can be associated to customers and used to activate special price lists or promotions.

Sample XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customer_groups>
    <customer_group guid="9e724e26-53ed-47cc-b445-cbf25a4ed16e" name="Segment1" description="customer segment 1">
        <enabled>true</enabled>
        <customer_roles>
            <customer_role authority="ROLE_CUSTOMER"/>
        </customer_roles>
    </customer_group>
    <customer_group guid="8a70ebf0-4afb-4402-b8e7-00aaee5d89b5" name="Segment2" description="customer segment 2">
        <enabled>true</enabled>
        <customer_roles>
            <customer_role authority="ROLE_CUSTOMER"/>
        </customer_roles>
    </customer_group>
</customer_groups>

Customer Profile Attribute

Customer profile are a set of information collected by the store for customer.

For example, the customer attribute CP_DOB, shown below, is the attribute for storing the customer’s date of birth. See how the CP_DOB customer profile attribute is used in the customer XML file example.

Sample XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customerprofile_attributes>
    <attribute>
        <key>CP_DOB</key>
        <name>Date of Birth</name>
        <usage>CustomerProfile</usage>
        <type>Date</type>
        <multilanguage>false</multilanguage>
        <required>false</required>
        <multivalue>false</multivalue>
        <global>false</global>
    </attribute>
</customerprofile_attributes>

User Account Associations

User account associations allow buyers to be associated with accounts, indicating that they can transact on behalf of that account, and defining the role that they have.

Field definitions:

  • guid: The unique identifier for the association. If an association with that guid already exists, the association is updated.
  • account_guid: The guid of a customer of type ACCOUNT.
  • user_guid: The guid of a customer of type REGISTERED_USER.
  • role: A valid role that defines what permissions the user has.

Sample XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<useraccountassociations>
    <useraccountassociation guid="2ff75be7-8c6a-4a68-9a5e-f9d68e42fe1a">
        <account_guid>50203697-bf26-40ce-9f53-ed19337639ef</account_guid>
        <user_guid>eeb2970b-7bfa-45a5-84f3-d17f48a7381d</user_guid>
        <role>BUYER</role>
    </useraccountassociation>
    <useraccountassociation guid="89900ace-3c3b-4da1-b9c7-12af9cf7aab9">
        <account_guid>e1d89fff-b408-434a-9e3d-06eece97a829</account_guid>
        <user_guid>eeb2970b-7bfa-45a5-84f3-d17f48a7381d</user_guid>
        <role>BUYER</role>
    </useraccountassociation>
</useraccountassociations>
Last updated on 6/1/2024
← Commerce ManagerData Policies →