Shopify Company XML (GraphQL)

Important

This task is only available for Shopify Plus.

The XML format documented here is used for the import of B2B companies into Shopify, via the Import Companies task. Contacts, locations and metafields can be imported along with each company.

We recommend that the ZynkExternalId field be populated with the unique ID of the company from the external system. Zynk uses this field to track companies already imported, in conjunction with the 'Prevent Reprocessing' setting, which 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"?>
<Companies>
  <Company>
    <ZynkExternalId>ACME0001</ZynkExternalId>
    <ExternalId>ACME0001</ExternalId>
    <Name>ACME Ltd</Name>
    <Note>A great company</Note>
    <CustomerSince>2023-09-14T11:55:17Z</CustomerSince>
    <Contacts>
      <Record>
        <Customer>
          <DefaultEmailAddress>
            <EmailAddress>[email protected]</EmailAddress>
          </DefaultEmailAddress>
        </Customer>
        <IsMainContact>true</IsMainContact>
      </Record>
    </Contacts>
    <Locations>
      <Record>
        <ExternalId>ACME0001-1</ExternalId>
        <Name>Head Office</Name>
        <Phone>+441918201484</Phone>
        <Locale>en</Locale>
        <Note>Deliveries to goods in</Note>
        <BillingSameAsShipping>false</BillingSameAsShipping>
        <BillingAddress>
          <Recipient>Accounts Department</Recipient>
          <FirstName>John</FirstName>
          <LastName>Smith</LastName>
          <Address1>i6 Building</Address1>
          <Address2>6-8 Charlotte Square</Address2>
          <City>Newcastle</City>
          <ZoneCode>ENG</ZoneCode>
          <Zip>NE1 4XF</Zip>
          <CountryCode>GB</CountryCode>
          <Phone>+441918201484</Phone>
        </BillingAddress>
        <ShippingAddress>
          <Recipient>Goods In</Recipient>
          <Address1>Unit 4</Address1>
          <Address2>Riverside Park</Address2>
          <City>Sunderland</City>
          <ZoneCode>ENG</ZoneCode>
          <Zip>SR1 2AB</Zip>
          <CountryCode>GB</CountryCode>
        </ShippingAddress>
        <BuyerExperienceConfiguration>
          <CheckoutToDraft>false</CheckoutToDraft>
          <EditableShippingAddress>true</EditableShippingAddress>
          <Deposit>
            <Percentage>10</Percentage>
          </Deposit>
          <PaymentTermsTemplate>
            <Id>gid://shopify/PaymentTermsTemplate/4</Id>
          </PaymentTermsTemplate>
        </BuyerExperienceConfiguration>
        <TaxSettings>
          <TaxExempt>false</TaxExempt>
          <TaxRegistrationId>GB012345678</TaxRegistrationId>
        </TaxSettings>
        <Metafields>
          <Record>
            <Namespace>custom</Namespace>
            <Key>salesforce_id</Key>
            <Type>single_line_text_field</Type>
            <Value>a124120000010452DEI</Value>
          </Record>
        </Metafields>
      </Record>
    </Locations>
    <Metafields>
      <Record>
        <Namespace>custom</Namespace>
        <Key>number_of_employees</Key>
        <Type>number_integer</Type>
        <Value>10</Value>
      </Record>
    </Metafields>
  </Company>
</Companies>

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 Companies schema is used above as a reference of where fields should be in the object model.

Company

The following information can be provided at the company level.

The company is matched in Shopify by Id if provided, otherwise by ExternalId. If a match is found the company is updated, otherwise it is created. ZynkExternalId does not replace Id or ExternalId: one of them must always be provided.

Shopify Field	XML Field	Type	Input	Notes
-	ZynkExternalId	string	Optional	Stored in Zynk's internal DB and used in conjunction with the 'Prevent Reprocessing' setting
id	Id	string	Dependant	Required if `ExternalId` is not provided. GraphQL ID (`gid://shopify/Company/123`) or the numeric company ID. Must be an existing company
externalId	ExternalId	string	Dependant	Required if `Id` is not provided. Used to find an existing company, and saved against the company in Shopify
name	Name	string	Dependant	Required when creating a company
note	Note	string	Optional
customerSince	CustomerSince	datetime	Optional	e.g. `2023-09-14T11:55:17Z`. Only used when creating a company, it is ignored when updating

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <ZynkExternalId>ACME0001</ZynkExternalId>
    <ExternalId>ACME0001</ExternalId>
    <Name>ACME Ltd</Name>
    <Note>A great company</Note>
    <CustomerSince>2023-09-14T11:55:17Z</CustomerSince>
  </Company>
</Companies>

Contacts

Contacts link existing Shopify customers to the company. The task does not create customers, so each customer must already exist in Shopify (see Shopify Customer XML). Customers that are already contacts of the company are left as they are. Contacts are not removed from the company if they are missing from the XML.

Shopify Field	XML Field	Type	Input	Notes
customer.id	Customer/Id	string	Dependant	Required if `Customer/DefaultEmailAddress/EmailAddress` is not provided. GraphQL ID, e.g. `gid://shopify/Customer/123`
customer.email	Customer/DefaultEmailAddress/EmailAddress	string	Dependant	Required if `Customer/Id` is not provided. The record fails if no customer, or more than one customer, has this email address
customer.email	Customer/Email	string	Optional	Deprecated, use `Customer/DefaultEmailAddress/EmailAddress` instead. Only used if `Customer/DefaultEmailAddress/EmailAddress` is empty
isMainContact	IsMainContact	bool	Optional	Set to `true` to make the contact the company's main contact. Only one contact per company can be `true`

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Contacts>
      <Record>
        <Customer>
          <Id>gid://shopify/Customer/6490770079810</Id>
        </Customer>
        <IsMainContact>true</IsMainContact>
      </Record>
      <Record>
        <Customer>
          <DefaultEmailAddress>
            <EmailAddress>[email protected]</EmailAddress>
          </DefaultEmailAddress>
        </Customer>
      </Record>
    </Contacts>
  </Company>
</Companies>

Locations

Multiple Record elements can be provided to import several locations for the company.

When updating an existing company, each location is matched against the company's existing locations by Id, then ExternalId, then Name, in that order of precedence. A matched location is updated, otherwise a new location is created. If an Id is provided that does not belong to the company, the record will fail. Locations are not removed from the company if they are missing from the XML.

Shopify Field	XML Field	Type	Input	Notes
id	Id	string	Dependant	Required if `ExternalId` and `Name` are not provided. GraphQL ID, e.g. `gid://shopify/CompanyLocation/123`
externalId	ExternalId	string	Dependant	Required if `Id` and `Name` are not provided
name	Name	string	Dependant	Required if `Id` and `ExternalId` are not provided. Matching is case sensitive
phone	Phone	string	Optional
locale	Locale	string	Optional	e.g. `en`
note	Note	string	Optional
billingSameAsShipping	BillingSameAsShipping	bool	Optional	Only used when creating a location

When an existing location is updated, BillingSameAsShipping and TaxSettings are ignored.

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Locations>
      <Record>
        <ExternalId>ACME0001-1</ExternalId>
        <Name>Head Office</Name>
        <Phone>+441918201484</Phone>
        <Locale>en</Locale>
        <Note>Deliveries to goods in</Note>
        <BillingSameAsShipping>false</BillingSameAsShipping>
      </Record>
    </Locations>
  </Company>
</Companies>

Billing and Shipping Address

The BillingAddress and ShippingAddress elements share the same fields.

Shopify Field	XML Field	Type	Input	Notes
recipient	Recipient	string	Optional
firstName	FirstName	string	Optional
lastName	LastName	string	Optional
address1	Address1	string	Optional
address2	Address2	string	Optional
city	City	string	Optional
zoneCode	ZoneCode	string	Optional	Province or state code
zip	Zip	string	Optional
countryCode	CountryCode	string	Optional	Two letter ISO country code, e.g. `GB`
phone	Phone	string	Optional

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Locations>
      <Record>
        <BillingAddress>
          <Recipient>Accounts Department</Recipient>
          <FirstName>John</FirstName>
          <LastName>Smith</LastName>
          <Address1>i6 Building</Address1>
          <Address2>6-8 Charlotte Square</Address2>
          <City>Newcastle</City>
          <ZoneCode>ENG</ZoneCode>
          <Zip>NE1 4XF</Zip>
          <CountryCode>GB</CountryCode>
          <Phone>+441918201484</Phone>
        </BillingAddress>
        <ShippingAddress>
          <Recipient>Goods In</Recipient>
          <Address1>Unit 4</Address1>
          <Address2>Riverside Park</Address2>
          <City>Sunderland</City>
          <ZoneCode>ENG</ZoneCode>
          <Zip>SR1 2AB</Zip>
          <CountryCode>GB</CountryCode>
        </ShippingAddress>
      </Record>
    </Locations>
  </Company>
</Companies>

Buyer Experience Configuration

Shopify Field	XML Field	Type	Input	Notes
checkoutToDraft	CheckoutToDraft	bool	Optional	Whether checkouts at this location create draft orders for review
editableShippingAddress	EditableShippingAddress	bool	Optional	Whether the buyer can enter a different shipping address at checkout
deposit.percentage	Deposit/Percentage	decimal	Optional	Deposit required at checkout, as a percentage of the order total
paymentTermsTemplateId	PaymentTermsTemplate/Id	string	Optional	GraphQL ID, e.g. `gid://shopify/PaymentTermsTemplate/4`

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Locations>
      <Record>
        <BuyerExperienceConfiguration>
          <CheckoutToDraft>false</CheckoutToDraft>
          <EditableShippingAddress>true</EditableShippingAddress>
          <Deposit>
            <Percentage>10</Percentage>
          </Deposit>
          <PaymentTermsTemplate>
            <Id>gid://shopify/PaymentTermsTemplate/4</Id>
          </PaymentTermsTemplate>
        </BuyerExperienceConfiguration>
      </Record>
    </Locations>
  </Company>
</Companies>

Tax Settings

Tax settings are only applied when the location is created, and are ignored when updating an existing location.

Shopify Field	XML Field	Type	Input	Notes
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
taxRegistrationId	TaxRegistrationId	string	Optional

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Locations>
      <Record>
        <TaxSettings>
          <TaxExempt>false</TaxExempt>
          <TaxRegistrationId>GB012345678</TaxRegistrationId>
        </TaxSettings>
      </Record>
    </Locations>
  </Company>
</Companies>

Metafields

Metafields can be set on the company, and on each location, using the same fields. They are set after the company and its locations have been imported.

Shopify Field	XML Field	Type	Input	Notes
namespace	Namespace	string	Optional	Defaults to the app's reserved namespace if not provided
key	Key	string	Required
type	Type	string	Dependant	Required if the metafield has no definition, e.g. `single_line_text_field`
value	Value	string	Required
compareDigest	CompareDigest	string	Optional	Only update the metafield if its current value matches this digest

<?xml version="1.0" encoding="utf-8"?>
<Companies>
  <Company>
    <Locations>
      <Record>
        <Metafields>
          <Record>
            <Namespace>custom</Namespace>
            <Key>salesforce_id</Key>
            <Type>single_line_text_field</Type>
            <Value>a124120000010452DEI</Value>
          </Record>
        </Metafields>
      </Record>
    </Locations>
    <Metafields>
      <Record>
        <Namespace>custom</Namespace>
        <Key>number_of_employees</Key>
        <Type>number_integer</Type>
        <Value>10</Value>
      </Record>
    </Metafields>
  </Company>
</Companies>