Skip to content

Shopify Customer XML

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

We recommend that the external_id field be populated with the unique ID of the customers from the external system, Zynk uses this field to track customers already imported to prevent duplicates being created in Shopify.

XML

Any fields not documented below are not supported by our Shopify connector. Examples of where in the XML the fields should appear are shown in the samples below.

<?xml version="1.0" encoding="utf-8"?>
<customers>
  <customer address-id-validation="Error">
    <id>959687688281</id>
    <email>[email protected]</email>
    <addresses>
      <address>
        <address1>Office 16</address1>
        <address2>6-8 Charlotte Square</address2>
        <city>Newcaslte upon Type/city>
        <company>Zynk Software</company>
        <country>United Kingdom</country>
        <country-code>GB</country-code>
        <default>true</default>
        <first-name>John</first-name>
        <id>207119551</id>
        <last-name>Smith</last-name>
        <name>John Smith</name>
        <phone>0191 820 1484</phone>
        <province>Tyne and Wear</province>
        <zip>NE1 4XF</zip>
      </address>
    </addresses>
    <email-marketing-consent>
      <state>subscribed</state>
      <opt-in-level>confirmed_opt_in</opt-in-level>
      <consent-updated-at>2023-01-01T00:00:00</consent-updated-at>
    </email-marketing-consent>
    <first-name>John</first-name>
    <last-name>Smith</last-name>
    <metafields>
      <metafield>
        <id>8576298526</id> <!-- Matches an existing metafield by ID -->
        <key>sage_account_code</key> <!-- Matches an existing metafield by key and namespace -->
        <namespace>custom</namespace> <!-- Matches an existing metafield by key and namespace -->
        <value>ZYNK0001</value>
        <type>single_line_text_field</type> <!-- Required when creating a new metafield -->
      </metafield>
    </metafields>
    <multipass-identifier>14152562462</multipass-identifier>
    <note>Placed an order that had a fraud warning</note>
    <password>password</password>
    <password-confirmation>password_confirmation</password-confirmation>
    <phone>+441913037279</phone>
    <sms-marketing-consent>
      <state>subscribed</state>
      <opt-in-level>single_opt_in</opt-in-level>
      <consent-updated-at>2023-01-01T00:00:00</consent-updated-at>
      <consent-collected-from>OTHER</consent-collected-from>
    </sms-marketing-consent>
    <tags>loyal,b2b</tags>
    <tax-exempt>true</tax-exempt>
    <tax-exemptions>
      <tax-exemption>CA_STATUS_CARD_EXEMPTION</tax-exemption>
      <tax-exemption>CA_BC_RESELLER_EXEMPTION</tax-exemption>
    </tax-exemptions>
  </customer>
</customers>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the customers schema is used below as a reference of where fields should be in the object model.

Customer

The following information can be found within the 'Customer' section.

Shopify Field XML Field  Type  Input  Notes
ID id long Optional Used for matching existing customers
- external_id string Optional Stored in Zynk's internal DB and used for matching existing customers
Email email string Required Used for matching existing customers
Marketing > Email email-marketing-consent/state string Optional
Marketing > Email email-marketing-consent/opt-in-level string Optional
Marketing > Email email-marketing-consent/consent-updated-at DateTime Optional
First Name first-name string Optional
Last Name last-name string Optional
- multipass-identifier string Optional
- password string Optional
- password-confirmation string Optional
Phone Number phone string Optional Must be in E.164 Format
Marketing > SMS sms-marketing-consent/state string Optional
Marketing > SMS sms-marketing-consent/opt-in-level string Optional
Marketing > SMS sms-marketing-consent/consent-updated-at DateTime Optional
Marketing > SMS sms-marketing-consent/consent-collected-from string Optional
Tax exemptions tax-exempt bool Optional
Tax exemptions tax-exemptions/tax-exemption enum Optional Valid values are listed below
  • tax-exemption - Valid values: EXEMPT_ALL, CA_STATUS_CARD_EXEMPTION, CA_DIPLOMAT_EXEMPTION, CA_BC_RESELLER_EXEMPTION, CA_MB_RESELLER_EXEMPTION, CA_SK_RESELLER_EXEMPTION, CA_BC_COMMERCIAL_FISHERY_EXEMPTION, CA_MB_COMMERCIAL_FISHERY_EXEMPTION, CA_NS_COMMERCIAL_FISHERY_EXEMPTION, CA_PE_COMMERCIAL_FISHERY_EXEMPTION, CA_SK_COMMERCIAL_FISHERY_EXEMPTION, CA_BC_PRODUCTION_AND_MACHINERY_EXEMPTION, CA_SK_PRODUCTION_AND_MACHINERY_EXEMPTION, CA_BC_SUB_CONTRACTOR_EXEMPTION, CA_SK_SUB_CONTRACTOR_EXEMPTION, CA_BC_CONTRACTOR_EXEMPTION, CA_SK_CONTRACTOR_EXEMPTION, CA_ON_PURCHASE_EXEMPTION, CA_MB_FARMER_EXEMPTION, CA_NS_FARMER_EXEMPTION, CA_SK_FARMER_EXEMPTION
<?xml version="1.0" encoding="utf-8"?>
<customers>
  <customer>
    <id>959687688281</id>
    <external_id></external_id>
    <email>[email protected]</email>
    <email-marketing-consent>
      <state>subscribed</state>
      <opt-in-level>confirmed_opt_in</opt-in-level>
      <consent-updated-at>2023-01-01T00:00:00</consent-updated-at>
    </email-marketing-consent>
    <first-name>John</first-name>
    <last-name>Smith</last-name>
    <multipass-identifier>14152562462</multipass-identifier>
    <password>password</password>
    <password-confirmation>password_confirmation</password-confirmation>
    <phone>+441913037279</phone>
    <sms-marketing-consent>
      <state>subscribed</state>
      <opt-in-level>single_opt_in</opt-in-level>
      <consent-updated-at>2023-01-01T00:00:00</consent-updated-at>
      <consent-collected-from>OTHER</consent-collected-from>
    </sms-marketing-consent>
    <tax-exempt>true</tax-exempt>
    <tax-exemptions>
      <tax-exemption>CA_STATUS_CARD_EXEMPTION</tax-exemption>
      <tax-exemption>CA_BC_RESELLER_EXEMPTION</tax-exemption>
    </tax-exemptions>
  </customer>
</customers>

Manage Addresses

The following information can be found within the 'Manage Addresses' screen.

Shopify Field XML Field  Type  Input  Notes
- @address-id-validation enum Optional Controls how address IDs are validated, see below for more details
Apartment, suite, etc address1 string Optional
Address address2 string Optional
City city string Optional
Company company string Optional
Country/Region country string Optional
Country/Region country-code string Optional Use the 2 letter ISO code
- default bool Optional Set to true to make this address the customer's default
First name first-name string Optional
- id string Optional Used for matching addresses
Last name last-name string Optional
First name/Last name name string Optional
Phone phone string Optional
Province province string Optional
Province province-code string Optional
Postcode zip string Optional
  • address-id-validation - This attribute controls whether or not address IDs should be validated, and what action should be taken when an invalid ID is found. The following options are available:
  • Error - Validation of address IDs will be enabled. On detection of an invalid ID, Zynk will log an error and prevent the whole customer record from being created or updated. This is the default setting.
  • Warning - Validation of address IDs will be enabled. On detection of an invalid ID, Zynk will log a warning and won't upload the affected address to Shopify. The rest of the customer data will still be created or updated.
  • Create - Validation of address IDs will be enabled. On detection of an invalid ID, Zynk will ignore the ID that was provided and create a new address in Shopify instead.
  • None - Validation of address IDs will be disabled. If any invalid address IDs are present, Shopify is likely to return a 'Not Found' error, and prevent the whole customer record from being created or updated.
<customers>
  <customer address-id-validation="Warning">
    <addresses>
      <address>
        <address1>Office 16</address1>
        <address2>6-8 Charlotte Square</address2>
        <city>Newcaslte upon Type/city>
        <company>Zynk Software</company>
        <country>United Kingdom</country>
        <country-code>GB</country-code>
        <default>true</default>
        <first-name>John</first-name>
        <id>207119551</id>
        <last-name>Smith</last-name>
        <name>John Smith</name>
        <phone>0191 820 1484</phone>
        <province>Tyne and Wear</province>
        <province-code>QC</province-code>
        <zip>NE1 4XF</zip>
      </address>
    </addresses>
  </customer>
</customers>

Notes

The following information can be found within the 'Notes' section.

Shopify Field XML Field  Type  Input  Notes
Notes note string Optional 
<?xml version="1.0" encoding="utf-8"?>
<customers>
  <customer>
    <note>Placed an order that had a fraud warning</note>
  </customer>
</customers>

Metafields

The following information can be found within the 'Metafields' section. The task will attempt to create a new metafield if a matching field doesn't already exist in Shopify.

Shopify Field XML Field  Type  Input  Notes
Definition id long Dependant Used for matching existing metafields. An id or key must be provided.
Namespace namespace string Optional Used in conjunction with key for matching existing metafields
Key key string Dependant Used in conjunction with namespace for matching existing metafields. An id or key must be provided.
Metafield value string Required
Content Type type enum Optional Required to create a new metafield. Valid values are listed below.
  • type - Valid values: boolean, color, date, date_time, dimension, json, money, multi_line_text_field, number_decimal, number_integer, rating, rich_text_field, single_line_text_field, url, volume, weight
<?xml version="1.0" encoding="utf-8"?>
<customers>
  <customer>
    <metafields>
      <metafield>
        <id>8576298526</id>
        <key>sage_account_code</key>
        <namespace>custom</namespace>
        <value>ZYNK0001</value>
        <type>single_line_text_field</type>
      </metafield>
    </metafields>
  </customer>
</customers>

Tags

The following information can be found within the 'Tags' section.

Shopify Field XML Field  Type  Input  Notes
Tags tags string Optional Provide a comma separated list of tags 
<?xml version="1.0" encoding="utf-8"?>
<customers>
  <customer>
    <tags>loyal,b2b</tags>
  </customer>
</customers>