Skip to content

Magento V2 Customer XML

The XML format documented here is used for the import of customer records into Magento, via the Import Customers to Magento V2 task.

If the <id> element is supplied the customer with that ID is updated, otherwise the customer is matched on email. To match on any other field, e.g. an account code held in a custom attribute, see Matching Records in Magento v2.

We recommend that the external_id field be populated with the unique ID of the customer from the external system. Zynk uses this field to track customers already imported when the Prevent Reprocessing setting is enabled.

Required Fields

XML Field Notes
email Also used for matching existing customers when no id is supplied
firstname
lastname
website_id The website the customer account belongs to. 1 on a standard Magento installation
group_id The customer group. 1 is the General group on a standard installation

On each address, Magento requires firstname, lastname, street, city, postcode, telephone and country_id. A region is also required for countries where Magento holds a region list, e.g. the US, and the import will fail if the region cannot be resolved.

Sample XML

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfCustomer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Customer>
    <external_id>WARD0001</external_id>
    <group_id>1</group_id>
    <email>[email protected]</email>
    <firstname>Adam</firstname>
    <lastname>Wardle</lastname>
    <gender>1</gender>
    <store_id>1</store_id>
    <website_id>1</website_id>
    <taxvat>GB123456789</taxvat>
    <addresses>
      <address>
        <firstname>Adam</firstname>
        <lastname>Wardle</lastname>
        <company>Zynk Software</company>
        <street>
          <string>Nelson House</string>
          <string>Jesmond</string>
        </street>
        <city>Newcastle</city>
        <postcode>NE2 3AE</postcode>
        <region>
          <region>Tyne &amp; Wear</region>
        </region>
        <country_id>GB</country_id>
        <telephone>214153215</telephone>
        <default_billing>true</default_billing>
        <default_shipping>true</default_shipping>
      </address>
    </addresses>
    <custom_attributes>
      <custom_attribute>
        <attribute_code>sage_account_number</attribute_code>
        <value>WARD0001</value>
      </custom_attribute>
    </custom_attributes>
  </Customer>
</ArrayOfCustomer>

Customer

Magento Field XML Field Type Input Notes
ID id int Optional The Magento customer ID. When supplied, the customer with this ID is updated
Group group_id int Required Use Export Customer Groups to find the group IDs on your store
Email email string Required Used for matching existing customers when no id is supplied
First Name firstname string Required
Last Name lastname string Required
Middle Name/Initial middlename string Optional
Prefix prefix string Optional
Suffix suffix string Optional
Date of Birth dob DateTime Optional
Gender gender int Optional 1 for Male, 2 for Female, 3 for Not Specified
Tax/VAT Number taxvat string Optional
Associate to Website website_id int Required
Store View store_id int Optional
- created_in string Optional The store view name the account was created in
- confirmation string Optional
Disable Automatic Group Change Based on VAT ID disable_auto_group_change int Optional 0 for false, 1 for true
Default Billing Address default_billing string Optional The ID of the address to use. Normally set with default_billing on the address itself instead
Default Shipping Address default_shipping string Optional The ID of the address to use. Normally set with default_shipping on the address itself instead
- created_at DateTime Optional
- updated_at DateTime Optional

Addresses

Magento Field XML Field Type Input Notes
- id int Optional The ID of an existing address to update
- customer_id int Optional
First Name firstname string Required
Last Name lastname string Required
Middle Name/Initial middlename string Optional
Prefix prefix string Optional
Suffix suffix string Optional
Company company string Optional
Street Address street/string string Required One string element per address line
City city string Required
Zip/Postal Code postcode string Required
State/Province region/region* string Conditional The name of the region, e.g. Tyne & Wear. Zynk resolves this to a Magento region ID where the country has a region list
State/Province region/region_code* string Conditional The code of the region, e.g. CA
State/Province region/region_id* int Conditional The Magento region ID
State/Province region_id* int Conditional As region/region_id, at the top level of the address
Country country_id string Required The two letter ISO country code, e.g. GB
Phone Number telephone string Required
Fax fax string Optional
VAT Number vat_id string Optional
Default Billing Address default_billing bool Optional
Default Shipping Address default_shipping bool Optional
- custom_attributes element Optional Address level custom attributes, in the same format as the customer level attributes below
  • region/region*, region/region_code*, region/region_id*, region_id* - Required for countries where Magento holds a region list, e.g. the United States. Send one of these to set the region

Custom Attributes

Any customer attribute which is not one of the elements above is sent as a custom attribute, including any attribute added to your own Magento installation.

Magento Field XML Field Type Input Notes
Attribute Code attribute_code string Required The code of the Magento attribute
Value value string Required The value to set. For a select or multiselect attribute this is the option ID, unless lookup_option_label is used

The lookup_option_label, case_sensitive_option_lookup, create_new_option_label and option_label_separator XML attributes can be used to look up options by their label, as described in Magento V2 Product XML.

<custom_attributes>
  <custom_attribute>
    <attribute_code>sage_account_number</attribute_code>
    <value>WARD0001</value>
  </custom_attribute>
</custom_attributes>

Common Fields

The following fields are supported on every record we import into Magento. They are used by Zynk rather than sent to Magento.

XML Field Type Input Notes
external_id string Optional The unique ID of the record in the external system. Stored in Zynk's internal DB and used to track records already imported. Required when the Prevent Reprocessing setting is enabled on the task
store_code string Optional The store view code to send this record to, overriding the Store View Code setting on the task for this record only
match element Optional Match an existing record on a field and value other than the default. See Matching Records in Magento v2
matches element Optional As match, but matching on more than one field. See Matching Records in Magento v2

Errors

Records which fail to import are written to the Fail File in the same format as the input file, with the reason for the failure added in an errors element. There is no need to send this element yourself.

The name of each error tells you at which stage the record failed:

Name Meaning
Pre-Validation Zynk checked the record before sending it and found a problem, e.g. a required field is missing or a related record could not be found. The record was not sent to Magento
Prevent Reprocessing A record with the same external_id has already been imported, and the Prevent Reprocessing setting is enabled on the task
Error Magento rejected the record, or Zynk could not match the record to the data already in Magento. The description contains the message returned by Magento
Upload Error An unexpected error occurred while sending the record to Magento 
<Customer>
  <firstname>Adam</firstname>
  <lastname>Wardle</lastname>
  <errors>
    <error>
      <name>Pre-Validation</name>
      <description>email must be provided for new customer</description>
    </error>
  </errors>
</Customer>