Catalog import overview¶

Catalog imports enables product data, content and translations to be imported into Voyado Elevate. This section outlines an overview of format, methods, and instruction types required to perform successful catalog imports, with examples for both full replacements and partial updates.

Requirements¶

Catalog imports must be encoded using UTF-8.
Catalog imports must be sent with Content-Type: application/jsonlines.
Catalog imports must be sent with Content-Encoding: gzip
The request body must be compressed using gzip.
Catalog imports must consist of JSON lines with a single Operation on each line.
All referenced markets and locales must be configured prior to importing catalog data.

JSON Lines¶

JSON Lines (JSONL) is a format for storing JSON data where each line of the file contains a valid JSON object. These JSON objects are separated by newline characters, and each line can be treated as an independent JSON entity.

Catalog imports consists of one or more Operation objects, provided as separate JSON lines.

Import types¶

Two types of catalog imports are supported, one to replace all catalog data and one to update the catalog data. The request method and the requirements of the operations differ between these imports. If any import fails, the catalog data remains unchanged.

Replace catalog¶

HTTP method: PUT
Replacing the catalog data, fully deletes all previously loaded data and replaces it with the data in the import. Operations within these imports must only contain replace instructions.

Example¶

application/jsonlines

{"replace": {"key": "pg1", "productGroup": {"products": {"p1": {"markets": ["uk"], "defaults": {"url": "/uk/products/p1", "title": "Louisa black coat"}, "variants": {"p1-v1": {"defaults": {"stock": 2, "sellingPrice": 129.0, "listPrice": 199.0, "cost": 55.0}}}}}}}}
{"replace": {"key": "c1", "content": {"markets": ["uk"], "type": "link", "defaults": {"title": "Shipping and Delivery", "url": "/us/customer-service/shipping-and-delivery"}}}}

Update catalog¶

HTTP method: POST
Updates to the catalog data can be made in various ways by using different instructions. When updating the catalog, any of the available instructions can be used within an Operation.

Each operation is executed in the provided order, e.g. replace before remove of an object will result in a different state than remove before replace.

Example¶

application/jsonlines

{"remove": {"productGroup": "pg37"}}
{"remove": {"content": "c22"}}
{"replace": {"key": "pg1", "productGroup": {"products": {"p1": {"markets": ["uk"], "defaults": {"url": "/uk/products/p1", "title": "Louisa black coat"}, "variants": {"p1-v1": {"defaults": {"stock": 2, "sellingPrice": 129.0, "listPrice": 199.0, "cost": 55.0}}}}}}}}
{"edit": {"key": "c1", "content": {"defaults": {"title": "Returns"}}}}

Instructions¶

Each Operation in the import must contain a single instruction. The supported instructions depend on the import method, PUT to replace and POST to update. The format of each instruction varies. For example:

All removal instructions have a very basic structure, simply specifying the context of what to remove.
Instructions that can add or modify data such as replace and edit, contain complete entities or parts of the entities productGroup, content and translation.
editAttributes is a unique instruction for modifying inner objects and operates on the entities product and variant. This is typically used for stock and price updates.

Related articles

Format overview of referenced catalog entities in instructions: format overview.
Contextualized, complete examples for common import scenarios: import examples.