Shopify Catalog XML (GraphQL)

Important

This task is only available for Shopify Plus.

The XML format documented here is used for the import of B2B catalogs into Shopify, via the Import Catalogs task. A catalog links a price list and a publication to one or more company locations.

We recommend that the ZynkExternalId field be populated with the unique ID of the catalog from the external system. When a catalog is created, Zynk stores the Shopify ID against this value, so later imports of the same catalog 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"?>
<Catalogs>
  <Catalog>
    <ZynkExternalId>ACME0001</ZynkExternalId>
    <Title>ACME Ltd</Title>
    <Status>ACTIVE</Status>
    <PriceList>
      <Name>ACME Ltd Prices</Name>
    </PriceList>
    <Publication>
      <Id>gid://shopify/Publication/123181826137</Id>
    </Publication>
    <CompanyLocations>
      <CompanyLocation>
        <ExternalId>ACME0001-1</ExternalId>
      </CompanyLocation>
      <CompanyLocation>
        <Name>ACME Ltd - Warehouse</Name>
      </CompanyLocation>
    </CompanyLocations>
  </Catalog>
</Catalogs>

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

Catalog

The following information can be provided at the catalog level.

The catalog 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 catalog with the given Title. If more than one catalog has that title, 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 catalog on later imports, and in conjunction with the 'Prevent Reprocessing' setting
id	Id	string	Dependant	Required if `Title` is not provided. GraphQL ID, e.g. `gid://shopify/CompanyLocationCatalog/123`
title	Title	string	Dependant	Required if `Id` is not provided, and always required by Shopify when creating a catalog. Used to find an existing catalog when no ID is known
status	Status	string	Dependant	`ACTIVE`, `ARCHIVED` or `DRAFT`. Required by Shopify when creating a catalog
priceListId	PriceList/Id	string	Optional	GraphQL ID, e.g. `gid://shopify/PriceList/123`
priceListId	PriceList/Name	string	Optional	Only used if `PriceList/Id` is not provided. Must exactly match the name of an existing price list (case sensitive), otherwise the record will fail
publicationId	Publication/Id	string	Optional	GraphQL ID, e.g. `gid://shopify/Publication/123`

<?xml version="1.0" encoding="utf-8"?>
<Catalogs>
  <Catalog>
    <ZynkExternalId>ACME0001</ZynkExternalId>
    <Title>ACME Ltd</Title>
    <Status>ACTIVE</Status>
    <PriceList>
      <Id>gid://shopify/PriceList/18434064473</Id>
    </PriceList>
    <Publication>
      <Id>gid://shopify/Publication/123181826137</Id>
    </Publication>
  </Catalog>
</Catalogs>

Company Locations

The company locations the catalog applies to. Shopify requires at least one company location when creating a catalog. When updating a catalog, omit CompanyLocations to leave the catalog's locations unchanged.

Each location is identified by one of Id, ExternalId or Name, in that order of precedence. ExternalId and Name are searched for across all companies in the store, so the record will fail if no location, or more than one location, matches.

Shopify Field	XML Field	Type	Input	Notes
context.companyLocationIds	Id	string	Dependant	Required if `ExternalId` and `Name` are not provided. GraphQL ID, e.g. `gid://shopify/CompanyLocation/123`
context.companyLocationIds	ExternalId	string	Dependant	Required if `Id` and `Name` are not provided
context.companyLocationIds	Name	string	Dependant	Required if `Id` and `ExternalId` are not provided

<?xml version="1.0" encoding="utf-8"?>
<Catalogs>
  <Catalog>
    <CompanyLocations>
      <CompanyLocation>
        <Id>gid://shopify/CompanyLocation/4870439001</Id>
      </CompanyLocation>
      <CompanyLocation>
        <ExternalId>ACME0001-1</ExternalId>
      </CompanyLocation>
      <CompanyLocation>
        <Name>ACME Ltd - Warehouse</Name>
      </CompanyLocation>
    </CompanyLocations>
  </Catalog>
</Catalogs>