Shopify Customer XML (GraphQL)

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

We recommend that the ZynkExternalId field be populated with the unique ID of the customer from the external system. When a customer is created, Zynk stores the Shopify ID against this value, so later imports of the same customer update it rather than create a duplicate. The 'Prevent Reprocessing' setting is disabled by default on this task.

XML

Any fields not documented below are ignored by the task. 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>
    <ZynkExternalId>CUST-10001</ZynkExternalId>
    <Id>gid://shopify/Customer/7398802653250</Id>
    <DefaultEmailAddress>
      <EmailAddress>[email protected]</EmailAddress>
    </DefaultEmailAddress>
    <DefaultPhoneNumber>
      <PhoneNumber>+441918201484</PhoneNumber>
    </DefaultPhoneNumber>
    <FirstName>John</FirstName>
    <LastName>Smith</LastName>
    <Locale>en</Locale>
    <Note>A happy customer</Note>
    <MultipassIdentifier>CUST-10001</MultipassIdentifier>
    <TaxExempt>false</TaxExempt>
    <TaxExemptions>
      <TaxExemption>CA_BC_COMMERCIAL_FISHERY_EXEMPTION</TaxExemption>
    </TaxExemptions>
    <Tags>
      <Tag>b2b</Tag>
      <Tag>wholesale</Tag>
    </Tags>
    <EmailMarketingConsent>
      <ConsentUpdatedAt>2025-01-21T16:06:32Z</ConsentUpdatedAt>
      <MarketingOptInLevel>SINGLE_OPT_IN</MarketingOptInLevel>
      <MarketingState>SUBSCRIBED</MarketingState>
    </EmailMarketingConsent>
    <SmsMarketingConsent>
      <ConsentUpdatedAt>2025-01-21T16:06:32Z</ConsentUpdatedAt>
      <MarketingOptInLevel>SINGLE_OPT_IN</MarketingOptInLevel>
      <MarketingState>NOT_SUBSCRIBED</MarketingState>
    </SmsMarketingConsent>
    <AddressesV2>
      <Record>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
        <Company>Zynk Software</Company>
        <Address1>i6 Building</Address1>
        <Address2>6-8 Charlotte Square</Address2>
        <City>Newcastle</City>
        <ProvinceCode>TWR</ProvinceCode>
        <Zip>NE1 4XF</Zip>
        <CountryCodeV2>GB</CountryCodeV2>
        <Phone>+441911231231</Phone>
      </Record>
    </AddressesV2>
    <Metafields>
      <Record>
        <Namespace>custom</Namespace>
        <Key>account_balance</Key>
        <Type>number_decimal</Type>
        <Value>1000.0</Value>
      </Record>
    </Metafields>
  </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 above as a reference of where fields should be in the object model.

Customer

The following information can be provided at the customer level.

The customer is updated if an ID is found, otherwise it is created. The ID is taken from Id if provided, then from the Shopify ID stored against ZynkExternalId by a previous import, and finally by searching Shopify for a customer with the given email address. If more than one customer has that email address, the record will fail.

Shopify Field	XML Field	Type	Input	Notes
-	ZynkExternalId	string	Optional	Stored in Zynk's internal DB and used to find the customer on later imports, and in conjunction with the 'Prevent Reprocessing' setting
id	Id	string	Dependant	Required if `DefaultEmailAddress/EmailAddress` is not provided. GraphQL ID, e.g. `gid://shopify/Customer/123`. Providing an `Id` always updates that customer
email	DefaultEmailAddress/EmailAddress	string	Dependant	Required if `Id` is not provided. Used to find an existing customer when no ID is known
phone	DefaultPhoneNumber/PhoneNumber	string	Optional	E.164 format, e.g. `+441918201484`
email	Email	string	Optional	Deprecated, use `DefaultEmailAddress/EmailAddress` instead. Only used if `DefaultEmailAddress/EmailAddress` is empty
phone	Phone	string	Optional	Deprecated, use `DefaultPhoneNumber/PhoneNumber` instead. Only used if `DefaultPhoneNumber/PhoneNumber` is empty
firstName	FirstName	string	Optional
lastName	LastName	string	Optional
locale	Locale	string	Optional	The customer's language, e.g. `en` or `fr`
note	Note	string	Optional
multipassIdentifier	MultipassIdentifier	string	Optional
taxExempt	TaxExempt	bool	Optional
taxExemptions	TaxExemptions/TaxExemption	string	Optional	Shopify `TaxExemption` enum value, e.g. `CA_BC_COMMERCIAL_FISHERY_EXEMPTION`. Multiple `TaxExemption` elements can be provided
tags	Tags/Tag	string	Optional	Multiple `Tag` elements can be provided. On update, the tags provided replace the customer's existing tags

Either Id or DefaultEmailAddress/EmailAddress must be provided, otherwise the record will fail. A ZynkExternalId on its own is not enough.

<?xml version="1.0" encoding="utf-8"?>
<Customers>
  <Customer>
    <ZynkExternalId>CUST-10001</ZynkExternalId>
    <Id>gid://shopify/Customer/7398802653250</Id>
    <DefaultEmailAddress>
      <EmailAddress>[email protected]</EmailAddress>
    </DefaultEmailAddress>
    <DefaultPhoneNumber>
      <PhoneNumber>+441918201484</PhoneNumber>
    </DefaultPhoneNumber>
    <FirstName>John</FirstName>
    <LastName>Smith</LastName>
    <Locale>en</Locale>
    <Note>A happy customer</Note>
    <MultipassIdentifier>CUST-10001</MultipassIdentifier>
    <TaxExempt>false</TaxExempt>
    <TaxExemptions>
      <TaxExemption>CA_BC_COMMERCIAL_FISHERY_EXEMPTION</TaxExemption>
    </TaxExemptions>
    <Tags>
      <Tag>b2b</Tag>
      <Tag>wholesale</Tag>
    </Tags>
  </Customer>
</Customers>

Email and SMS marketing consent are provided in the EmailMarketingConsent and SmsMarketingConsent elements, which share the same fields. Shopify only accepts marketing consent when the customer is created, and requires an email address or phone number respectively.

Shopify Field	XML Field	Type	Input	Notes
consentUpdatedAt	ConsentUpdatedAt	datetime	Optional	When the customer gave or withdrew consent, e.g. `2025-01-21T16:06:32Z`
marketingOptInLevel	MarketingOptInLevel	string	Optional	`SINGLE_OPT_IN`, `CONFIRMED_OPT_IN` or `UNKNOWN`
marketingState	MarketingState	string	Required	e.g. `SUBSCRIBED`, `NOT_SUBSCRIBED`, `UNSUBSCRIBED` or `PENDING`

<?xml version="1.0" encoding="utf-8"?>
<Customers>
  <Customer>
    <EmailMarketingConsent>
      <ConsentUpdatedAt>2025-01-21T16:06:32Z</ConsentUpdatedAt>
      <MarketingOptInLevel>SINGLE_OPT_IN</MarketingOptInLevel>
      <MarketingState>SUBSCRIBED</MarketingState>
    </EmailMarketingConsent>
    <SmsMarketingConsent>
      <ConsentUpdatedAt>2025-01-21T16:06:32Z</ConsentUpdatedAt>
      <MarketingOptInLevel>SINGLE_OPT_IN</MarketingOptInLevel>
      <MarketingState>NOT_SUBSCRIBED</MarketingState>
    </SmsMarketingConsent>
  </Customer>
</Customers>

Addresses

Multiple Record elements can be provided to give the customer several addresses. All fields are optional.

Only the codes are read for the country and province; the Country and Province name fields, and the address Id, are ignored.

Shopify Field	XML Field	Type	Input	Notes
firstName	FirstName	string	Optional
lastName	LastName	string	Optional
company	Company	string	Optional
address1	Address1	string	Optional
address2	Address2	string	Optional
city	City	string	Optional
provinceCode	ProvinceCode	string	Optional
zip	Zip	string	Optional
countryCode	CountryCodeV2	string	Optional	Two letter ISO country code, e.g. `GB`
phone	Phone	string	Optional

<?xml version="1.0" encoding="utf-8"?>
<Customers>
  <Customer>
    <AddressesV2>
      <Record>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
        <Company>Zynk Software</Company>
        <Address1>i6 Building</Address1>
        <Address2>6-8 Charlotte Square</Address2>
        <City>Newcastle</City>
        <ProvinceCode>TWR</ProvinceCode>
        <Zip>NE1 4XF</Zip>
        <CountryCodeV2>GB</CountryCodeV2>
        <Phone>+441911231231</Phone>
      </Record>
    </AddressesV2>
  </Customer>
</Customers>

Metafields

Multiple Record elements can be provided to set several metafields on the customer.

Shopify Field	XML Field	Type	Input	Notes
id	Id	string	Optional	GraphQL ID of an existing metafield to update, e.g. `gid://shopify/Metafield/123`
namespace	Namespace	string	Optional	e.g. `custom`
key	Key	string	Dependant	Required if `Id` is not provided
type	Type	string	Dependant	Required if `Id` is not provided and the metafield has no definition, e.g. `single_line_text_field` or `number_decimal`
value	Value	string	Required

<?xml version="1.0" encoding="utf-8"?>
<Customers>
  <Customer>
    <Metafields>
      <Record>
        <Namespace>custom</Namespace>
        <Key>account_balance</Key>
        <Type>number_decimal</Type>
        <Value>1000.0</Value>
      </Record>
    </Metafields>
  </Customer>
</Customers>

Shopify Customer XML (GraphQL)

XML

Customer

Marketing Consent

Addresses

Metafields