Catalog import examples¶
This section contains examples of catalog imports for different use cases and workflows.
Not all use cases are relevant for every retailer. The easiest approach for each retailer will depend on the number of markets and locales, and how the setup of sources communicating with Elevate looks like.
JSON lines
Note that the operations in most examples below are expanded as JSON entities for improved readability. When provided in imports, each operation must be provided as a single JSON line.
Adding entities¶
New product groups, content and translations are added or replaced using replace. The replace instruction replaces the entity with the new state, removing all previous information about it.
New entities can also be added through edit, given that the edit instruction contains full and valid entities, and that the instruction specifies a non-existing keys. Note that this will not remove any unedited information if the entity exists.
Adding product groups¶
The following examples assumes the usage of translations, see Adding translations for examples of how to connect id:s to values.
Add basic product group
This import will add or replace product group pg1 making it available in uk. No overrides are provided and all valid request contexts will result in the data provided at default level. Only providing data at default level is applicable for retailers with a single market containing a single locale.
{
"replace" : {
"key" : "pg1",
"productGroup" : {
"products" : {
"p1" : {
"markets" : ["uk"],
"colorInitial" : ["#FF0000"],
"defaults" : {
"dataLocale" : "en-GB",
"url" : "/products/p1",
"title" : "Louisa black coat",
"ontology" : "Clothing > Outerwear > Coats & Jackets",
"category" : ["c1", "c2"],
"brand" : "Luis Vitton",
"sizeType" : "Clothing",
"description" : "A fine coat for any occasion",
"releaseDate" : "2023-06-20T00:00:00+02:00",
"rating" : 5,
"styleWith" : ["p2", "p3"],
"customLabels" : {
"season" : ["S1", "S2"],
"material" : ["M1"]
}
},
"images" : {
"i1": {
"defaults" : {
"urls" : [{
"url" : "//cdn.example.com/products/p1?preset=200x200"
}]
}
}
},
"variants" : {
"p1-v1" : {
"defaults" : {
"url" : "/products/p1-v1",
"stock" : 2,
"sellingPrice" : 129.0,
"listPrice" : 199.0,
"cost" : 55.0,
"size" : ["S"]
}
},
"p1-v2" : {
"defaults" : {
"url" : "/products/p1-v2",
"stock" : 0,
"sellingPrice" : 129.0,
"listPrice" : 199.0,
"cost" : 55.0,
"size" : ["M"]
}
},
"p1-v3" : {
"defaults" : {
"url" : "/products/p1-v3",
"stock" : 4,
"sellingPrice" : 129.0,
"listPrice" : 199.0,
"cost" : 55.0,
"size" : ["L"]
}
}
}
}
}
}
}
}
This example could be further simplified by inlining the translation values, as there's only one locale configured for the market. This is an option if no id:s for the values exist in the retailers data. This is however not recommended when avoidable, as filters and product selections built directly on values are less stable then when using id:s.
Add product group with advanced feature usage
This import will add or replace product group pg1 making it available in uk and se.
- For all requests using
sv-SEas locale, defaults and overrides for*|sv-SEwill apply. - For all requests using
seas market, defaults and overrides forse|*will apply. - For all requests using
ukas market, defaults and overrides foruk|*will apply. - For all other requests, only defaults will apply.
{
"replace": {
"key": "pg1",
"productGroup": {
"suppressDuplicates": true,
"products": {
"p1": {
"markets": ["uk", "se"],
"colorInitial": ["#FF0000"],
"defaults": {
"dataLocale": "en-GB",
"url": "/products/p1",
"title": "Louisa black coat",
"ontology": "Clothing > Outerwear > Coats",
"category": ["c1", "c2"],
"brand": "Luis Vitton",
"sizeType": "Clothing",
"description": "A fine coat for any occasion",
"releaseDate": "2023-06-20T00:00:00+02:00",
"rating": 5,
"styleWith": ["p2", "p3"],
"customLabels": {
"season": ["S1", "S2"],
"material": ["M1"]
},
"customLengths": {
"coat-length": {
"amount": 160,
"unit": "cm"
}
}
},
"overrides": {
"*|sv-SE": {
"title": "Louisa svart kappa",
"description": "En vacker kappa för alla tillfällen"
},
"se|*": {
"url": "/se/products/p1",
"rating": 3,
"customLabels": {
"campaign": ["christmas-leftovers"]
}
}
},
"images": {
"i1": {
"typeInitial": "model",
"defaults": {
"urls": [
{ "url": "//cdn.example.com/products/p1?preset=200x200", "widthInitial": 200 },
{ "url": "//cdn.example.com/products/p1?preset=600x600", "widthInitial": 600 }
],
"caption": "The model is 176 cm tall and is wearing size S",
"alt": "The model is 176 cm tall and is wearing size S",
"tags": ["hero"],
"customData": {
"user": "u1",
"type": "Instagram"
}
},
"overrides": {
"*|sv-SE": {
"caption": "Modellen är 176 cm och har storlek S",
"alt": "Modellen är 176 cm och har storlek S"
}
}
}
},
"variants": {
"p1-v1": {
"defaults": {
"url": "/products/p1-v1",
"stock": 2,
"sellingPrice": 129.0,
"listPrice": 199.0,
"cost": 55.0,
"sizeFormats": {
"sml": ["S"],
"eu": ["34", "36"]
}
},
"overrides": {
"uk|*": {
"url": "/uk/products/p1-v1",
"stock": 2,
"storeStock": {
"london": 4
}
},
"se|*": {
"url": "/se/products/p1-v1",
"stock": 21,
"sellingPrice": 1129,
"listPrice": 1199,
"cost": 555.0,
"customPrices": {
"VIP": {
"sellingPrice": 999.0,
"listPrice": 1199.0
}
},
"customLabels": {
"badge": ["svanen"]
},
"storeStock": {
"stockholm": 23
}
}
}
}
}
}
}
}
}
}
Adding translations¶
Add translation
This import will add or replace a translation in en-GB for id M1 in the custom label attribute material.
{
"replace": {
"translation": {
"locale": "en-GB",
"attribute": "customLabels.material",
"id": "M1",
"value": "Wool"
}
}
}
Add all translation for product group example
Here is an unexpanded import example of adding translations for all id:s used in the "Add basic product group" example.
{"replace": {"translation": {"locale": "en-GB", "attribute": "category", "id": "c1", "value": "Clothing > Outerwear > Coats & Jackets"}}}
{"replace": {"translation": {"locale": "en-GB", "attribute": "category", "id": "c2", "value": "Women > Outlet"}}}
{"replace": {"translation": {"locale": "en-GB", "attribute": "customLabels.season", "id": "S1", "value": "Winter"}}}
{"replace": {"translation": {"locale": "en-GB", "attribute": "customLabels.season", "id": "S2", "value": "Autumn"}}}
{"replace": {"translation": {"locale": "en-GB", "attribute": "customLabels.material", "id": "M1", "value": "Wool"}}}
Adding content¶
Add content with advanced feature usage
This import will add or replace content c1 making it available in se and uk.
- For all requests using
sv-SEas locale, defaults and overrides for*|sv-SEwill apply. - For all requests using
seas market, defaults and overrides forse|*will apply. - For all other requests, defaults will apply.
{
"replace": {
"key": "c1",
"content": {
"markets": ["se", "uk"],
"type": "article",
"defaults": {
"dataLocale": "en-GB",
"url": "/content/c1",
"title": "It's finally sweater season",
"releaseDate" : "2023-08-20",
"description": "Warm, comfortable, and stylish when it matters the most.",
"customLabels": {
"season": ["S1"]
}
},
"overrides": {
"*|sv-SE": {
"title": "Äntligen tröjsäsong!",
"description": "Varm, skön och väldigt snygg."
},
"se|*": {
"releaseDate": "2023-09-20"
}
},
"image": {
"defaults": {
"urls": [
{ "url": "//cdn.example.com/products/p1?preset=200x200", "widthInitial": 200 },
{ "url": "//cdn.example.com/products/p1?preset=600x600", "widthInitial": 600 }
],
"tags": ["mainframe"]
}
}
}
}
}
Adding products and variants¶
Products and variants are inner entities and can only be added to already existing parent entities. Inner entities are added via edit of the parent entity. When editing a prior non-exising inner entity key, the edit instruction must contain all mandatory entity information or the import will fail.
Add new product to existing product group
Assuming p2 and p2-v1 do not previously exist, this import will add them to the product group pg1 without affecting any other properties or inner entities of pg1. Note that a new product must contain at least one variant to be valid.
{
"edit": {
"key": "pg1",
"productGroup": {
"products": {
"p2": {
"markets": ["uk"],
"colorInitial": ["#FF0000"],
"defaults": {
"dataLocale": "en-GB",
"url": "/products/p2",
"title": "Louisa blue coat",
"category": ["c1"],
"brand": "Luis Vitton",
"sizeType": "Clothing",
"description": "A fine coat for any occasion",
"releaseDate": "2023-06-20T00:00:00+02:00",
"rating": 5,
"styleWith": ["p2", "p3"]
},
"images": {
"i1": {
"defaults": {
"urls": [ { "url": "//cdn.example.com/products/p1?preset=200x200" } ]
}
}
},
"variants": {
"p2-v1": {
"defaults": {
"url": "/products/p2-v1",
"stock": 2,
"sellingPrice": 129.0,
"listPrice": 199.0,
"cost": 55.0,
"size": ["S"]
}
}
}
}
}
}
}
}
Add new variant to existing product
Assuming p2-v2 does not previously exist, this import will add it to the product p1 without affecting any other properties or inner entities of p1 or pg1.
{
"edit": {
"key": "pg1",
"productGroup": {
"products": {
"p2": {
"variants": {
"p2-v2": {
"defaults": {
"url": "/products/p2-v2",
"stock": 2,
"sellingPrice": 129.0,
"listPrice": 199.0,
"cost": 55.0,
"size": ["M"]
}
}
}
}
}
}
}
}
Editing entities¶
When editing entities, all previously imported information is retained unless explicitly edited. This can be used to alter properties but also to add single products or variants to existing product groups. It can also be used to add market and locale overrides for existing entities.
Extending markets support¶
Existing entities can be made available in additional markets by adding a new market identifier to the market array. If no market overrides are supplied, this however means that all the default values provided are the ones that will be applicable for the new market as well. This is typically only relevant when inventory is shared across multiple markets.
As utility support, market availability can also be extended by simply adding an override for the new market without explicitly updating the markets array. This will automatically append the new market in the override to the markets array.
Add existing product and variants to new markets
The following import will make the product p1 and all its variants additionally available for us, given that they were available in se and uk before.
{
"edit": {
"key": "pg1",
"productGroup": {
"products": {
"p1": {
"markets": ["se", "uk", "us"]
}
}
}
}
}
{
"edit": {
"key": "pg1",
"productGroup": {
"products": {
"p1": {
"overrides": {
"us|*": {
"rating": 4,
"releaseDate": "2023-10-01"
}
}
}
}
}
}
}
Add existing content to new markets
The following import will make the content c1 additionally available for us, given that it was available in se and uk before.
{
"edit": {
"key": "c1",
"content": {
"markets": [ "se", "uk", "us" ]
}
}
}
{
"edit": {
"key": "c1",
"content": {
"overrides": {
"us|*": {
"url": "/us/content/c1"
}
}
}
}
}
Extending locale support¶
All entities are by default available on all locales in the markets they are available for. The applicable locales of a market is determined by the configured market definitions. Adding locale support for a market is thus made though a configuration import.
The data which is returned for a particular locale however depends on the available entity data as well as the imported translations. Apart from Adding translations, locale data can also be added through adding new overrides.
Add locale data for product
The following import adds locale overrides for the locale fi-FI on product p1.
{
"edit": {
"key": "pg1",
"productGroup": {
"products": {
"p1": {
"overrides": {
"*|fi-FI": {
"description": "Kaunis takki joka tilanteeseen",
"title": "Louisa viininpunainen takki"
}
}
}
}
}
}
}
Add locale data for content
The following import adds locale overrides for the locale fi-FI on content c1.
{
"edit": {
"key": "c1",
"content": {
"overrides": {
"*|fi-FI": {
"description": "Kaunis takki joka tilanteeseen",
"title": "Louisa viininpunainen takki"
}
}
}
}
}
Changing specific properties¶
The edit instruction allows both modifications of specific properties and structural changes, such as adding variants and extending market availability. It also supports adding new entities.
This however means that for product and variant changes, all parent keys must be provided. Furthermore, minor changes to non-existing products or variants will likely result in failed imports as that implies adding a new invalid entity.
For simple changes, the instruction editAttributes can be used instead. Such instructions will be ignored when targeting non existing keys, and supports editing products and variants directly.
Update variant price and stock level
{
"editAttributes": {
"key": "p1-v1",
"variant": {
"overrides": {
"se|*": {
"stock": 4,
"sellingPrice": 129.0
}
}
}
}
}
Add custom label to product
{
"editAttributes": {
"key": "p1",
"product": {
"defaults": {
"customLabels": {
"campaign": ["30-OFF"]
}
}
}
}
}
Edit content type
{
"edit": {
"key": "c1",
"content": {
"type": "link"
}
}
}
Removing data¶
Replacing the catalog completely removes all catalog data and adds the new data defined in the import file. To fully remove all catalog data, perform such an import with an empty file. This is however likely only a relevant use case during development and testing.
To remove specific data, remove and clear instructions when updating the catalog can be used.
Remove entities completely¶
Remove product groups
{ "remove" : { "productGroup": "pg1" } }
{ "remove" : { "productGroup": "pg1" } }
{ "remove" : { "productGroup": "pg2" } }
{ "remove" : { "productGroup": "pg3" } }
Remove content
{ "remove" : { "content": "c1" } }
Remove entity market data¶
Removing entity market data means that the entity no longer is available for the market. All overrides targeting the specified market identifier is removed along with altering the markets array for the entity.
If the entity is only available for the market to remove, the entire entity will be completely removed from the catalog including all default data.
Remove product group from market
{ "removePartial" : { "productGroup": "pg1", "market": "se"} }
Remove content from market
{ "removePartial" : { "content": "c1", "market": "se"} }
Remove all product groups from market
{ "clearProductGroups" : { "market": "se"} }
Remove all content from market
{ "clearContent" : { "market": "se"} }
Remove translations for locale¶
Remove all translations for a locale
{ "clearTranslations" : { "locale": "sv-SE"} }