Supported Feed Formats

CatalogRelay supports four feed source types: CSV, XML, JSON, and API.

CSV

Comma-separated values — the most common supplier format.

Configuration options:

Option	Default	Description
Delimiter	,	Field separator — also supports ;, \t, `
Quote character	"	Character used to wrap fields containing the delimiter
Encoding	UTF-8	File encoding (UTF-8, ISO-8859-1, Windows-1252)
Has header row	Yes	Whether the first row contains column names
Skip rows	0	Number of rows to skip before the header

Example CSV:

sku,name,price,stock,ean
ABC123,Widget Pro,29.99,45,5901234123457
DEF456,Gadget Plus,49.99,0,5901234123464

CatalogRelay reads the header row and makes each column available for attribute mapping.

XML

XML feeds are common from larger distributors and ERP exports.

Configuration options:

Option	Description
Row element XPath	XPath to the repeating product element — e.g. //products/product or //item
Namespace	XML namespace prefix if needed

Example XML:

<catalog>
  <products>
    <product>
      <sku>ABC123</sku>
      <name>Widget Pro</name>
      <price>29.99</price>
      <stock>45</stock>
      <ean>5901234123457</ean>
    </product>
  </products>
</catalog>

For this feed, the row element XPath would be //products/product. CatalogRelay flattens each product element’s children into columns.

JSON

JSON feeds are typical from modern supplier APIs that offer file exports.

Configuration options:

Option	Description
Products path	Dot-notation path to the products array — e.g. data.products or items

Example JSON:

{
  "meta": { "total": 2 },
  "data": {
    "products": [
      { "sku": "ABC123", "name": "Widget Pro", "price": 29.99, "stock": 45 },
      { "sku": "DEF456", "name": "Gadget Plus", "price": 49.99, "stock": 0 }
    ]
  }
}

For this feed, the products path would be data.products.

API

For suppliers that don’t offer a file download but do offer a REST or GraphQL API with pagination.

The API source type uses a flexible source_config JSON to describe how to fetch and paginate the data.

Example source_config for REST API with cursor pagination:

{
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {SUPPLIER_TOKEN}"
  },
  "params": {
    "per_page": 500
  },
  "pagination": {
    "type": "cursor",
    "cursor_field": "next_cursor",
    "cursor_param": "cursor"
  },
  "products_path": "data"
}

Example source_config for REST API with page-based pagination:

{
  "method": "GET",
  "pagination": {
    "type": "page",
    "page_param": "page",
    "per_page_param": "per_page",
    "per_page": 1000,
    "stop_when_empty": true
  },
  "products_path": "items"
}

Contact support if your supplier’s API has a non-standard pagination scheme.

Feed size limits

There are no file size limits. CatalogRelay streams the download to disk and processes in chunks. Tested with CSV files up to 2 GB and XML files with 5 million rows.

Encoding

All feeds are read as UTF-8. If your supplier’s feed uses a different encoding (ISO-8859-1, Windows-1252), configure this in the feed settings. CatalogRelay will transcode to UTF-8 before processing.

Compression

Gzip-compressed feeds (.csv.gz, .xml.gz) are automatically detected and decompressed. Zip archives are not yet supported — contact support if your supplier only offers zipped exports.