Catalog import examples - Voyado Elevate Docs

Here you’ll find examples of catalog imports for different use cases and workflows. Not all use cases are relevant for every retailer. The easiest approach depends on the number of markets and locales, and how the sources communicating with Elevate are set up.

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, provided that the edit instruction contains full and valid entities, and that the instruction specifies non-existing keys. This will not remove any unedited information if the entity already exists.

Adding product groups

The following examples assume the use of translations. See Adding translations for examples of how to connect IDs to values.

Add basic product group

This import adds or replaces product group pg1, making it available in uk. No overrides are provided, and all valid request contexts will use the data provided at default level. Providing data only 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": {
            "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"]
              }
            }
          }
        }
      }
    }
  }
}

{"replace":{"key":"pg1","productGroup":{"products":{"p1":{"markets":["uk"],"colorInitial":["#FF0000"],"defaults":{"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, because only one locale is configured for the market. This is an option if no IDs for the values exist in the retailer’s data. However, this is not recommended when avoidable, because filters and product selections built directly on values are less stable than those using IDs.

Add product group with advanced feature usage

This import adds or replaces product group pg1, making it available in uk and se.

For all requests using sv-SE as locale, defaults and overrides for *|sv-SE apply.
For all requests using se as market, defaults and overrides for se|* apply.
For all requests using uk as market, defaults and overrides for uk|* apply.
For all other requests, only defaults apply.

{
  "replace": {
    "key": "pg1",
    "productGroup": {
      "suppressDuplicates": true,
      "products": {
        "p1": {
          "markets": ["uk", "se"],
          "colorInitial": ["#FF0000"],
          "defaults": {
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{"replace":{"key":"pg1","productGroup":{"suppressDuplicates":true,"products":{"p1":{"markets":["uk","se"],"colorInitial":["#FF0000"],"defaults":{"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 adds or replaces 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"
    }
  }
}

{"replace":{"translation":{"locale":"en-GB","attribute":"customLabels.material","id":"M1","value":"Wool"}}}

Add all translations for product group example

Here is an unexpanded import example of adding translations for all IDs 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 adds or replaces content c1, making it available in se and uk.

For all requests using sv-SE as locale, defaults and overrides for *|sv-SE apply.
For all requests using se as market, defaults and overrides for se|* apply.
For all other requests, defaults apply.

{
  "replace": {
    "key": "c1",
    "content": {
      "markets": ["se", "uk"],
      "type": "article",
      "defaults": {
        "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"]
        }
      }
    }
  }
}

{"replace":{"key":"c1","content":{"markets":["se","uk"],"type":"article","defaults":{"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 existing parent entities. Inner entities are added through edit of the parent entity. When editing a previously non-existing 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 adds them to product group pg1 without affecting any other properties or inner entities of pg1. A new product must contain at least one variant to be valid.

{
  "edit": {
    "key": "pg1",
    "productGroup": {
      "products": {
        "p2": {
          "markets": ["uk"],
          "colorInitial": ["#FF0000"],
          "defaults": {
            "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"]
              }
            }
          }
        }
      }
    }
  }
}

{"edit":{"key":"pg1","productGroup":{"products":{"p2":{"markets":["uk"],"colorInitial":["#FF0000"],"defaults":{"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 adds it to 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"]
              }
            }
          }
        }
      }
    }
  }
}

{"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, add single products or variants to existing product groups, or add market and locale overrides for existing entities.

Extending market support

Existing entities can be made available in additional markets by adding a new market identifier to the markets array. If no market overrides are supplied, all default values will apply 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 adding an override for the new market without explicitly updating the markets array. This automatically appends the new market from the override to the markets array.

Add existing product and variants to new markets

The following import makes product p1 and all its variants additionally available for us, given that they were available in se and uk before.

Add market through the `markets` array

{
  "edit": {
    "key": "pg1",
    "productGroup": {
      "products": {
        "p1": {
          "markets": ["se", "uk", "us"]
        }
      }
    }
  }
}

{"edit":{"key":"pg1","productGroup":{"products":{"p1":{"markets":["se","uk","us"]}}}}}

Add market through a new override

{
  "edit": {
    "key": "pg1",
    "productGroup": {
      "products": {
        "p1": {
          "overrides": {
            "us|*": {
              "rating": 4,
              "releaseDate": "2023-10-01"
            }
          }
        }
      }
    }
  }
}

{"edit":{"key":"pg1","productGroup":{"products":{"p1":{"overrides":{"us|*":{"rating":4,"releaseDate":"2023-10-01"}}}}}}}

Add existing content to new markets

The following import makes content c1 additionally available for us, given that it was available in se and uk before.

Add market through the `markets` array

{
  "edit": {
    "key": "c1",
    "content": {
      "markets": ["se", "uk", "us"]
    }
  }
}

{"edit":{"key":"c1","content":{"markets":["se","uk","us"]}}}

Add market through a new override

{
  "edit": {
    "key": "c1",
    "content": {
      "overrides": {
        "us|*": {
          "url": "/us/content/c1"
        }
      }
    }
  }
}

{"edit":{"key":"c1","content":{"overrides":{"us|*":{"url":"/us/content/c1"}}}}}

Extending locale support

All entities are available by default on all locales in the markets they are available for. The applicable locales of a market are determined by the configured market definitions. Adding locale support for a market is therefore done with a configuration import. The data returned for a particular locale depends on available entity data and imported translations. In addition to adding translations, locale data can also be added through new overrides.

Add locale data for product

The following import adds locale overrides for locale fi-FI on product p1.

{
  "edit": {
    "key": "pg1",
    "productGroup": {
      "products": {
        "p1": {
          "overrides": {
            "*|fi-FI": {
              "description": "Kaunis takki joka tilanteeseen",
              "title": "Louisa viininpunainen takki"
            }
          }
        }
      }
    }
  }
}

{"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 locale fi-FI on content c1.

{
  "edit": {
    "key": "c1",
    "content": {
      "overrides": {
        "*|fi-FI": {
          "description": "Kaunis takki joka tilanteeseen",
          "title": "Louisa viininpunainen takki"
        }
      }
    }
  }
}

{"edit":{"key":"c1","content":{"overrides":{"*|fi-FI":{"description":"Kaunis takki joka tilanteeseen","title":"Louisa viininpunainen takki"}}}}}

Changing specific properties

The edit instruction allows modifications of specific properties and structural changes, such as adding variants and extending market availability. It also supports adding new entities. For product and variant changes, all parent keys must be provided. Minor changes to non-existing products or variants will likely result in failed imports, because that implies adding a new invalid entity. For simple changes, use editAttributes. These instructions are ignored when targeting non-existing keys, and support editing products and variants directly.

Update variant price and stock level

{
  "editAttributes": {
    "key": "p1-v1",
    "variant": {
      "overrides": {
        "se|*": {
          "stock": 4,
          "sellingPrice": 129.0
        }
      }
    }
  }
}

{"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"]
        }
      }
    }
  }
}

{"editAttributes":{"key":"p1","product":{"defaults":{"customLabels":{"campaign":["30-OFF"]}}}}}

Edit content type

{
  "edit": {
    "key": "c1",
    "content": {
      "type": "link"
    }
  }
}

{"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 usually only relevant during development and testing. To remove specific data, use remove and clear instructions when updating the catalog.

Removing a product group automatically removes all products and variants within it. Similarly, removing all products within a product group also removes the group, and removing the last variant of a product also removes the product.

Remove entities completely

Remove product groups

Remove pg1

{ "remove": { "productGroup": "pg1" } }

Remove multiple groups

{ "remove": { "productGroup": "pg1" } }
{ "remove": { "productGroup": "pg2" } }
{ "remove": { "productGroup": "pg3" } }

Remove products

Remove p1

{ "remove": { "product": "p1" } }

Remove variants

Remove p1-v1

{ "remove": { "variant": "p1-v1" } }

Remove content

{ "remove": { "content": "c1" } }

Remove image

{ "remove": { "image": { "product": "p1", "key": "i1" } } }

Remove entity market data

Removing entity market data means that the entity is no longer available for the market. All overrides targeting the specified market identifier are removed, and the entity’s markets array is updated. If the entity is only available for the market being removed, the entire entity is removed from the catalog, including all default data. Variants cannot be removed on a per-market level. In the rare case that a variant should not be available in all markets its parent product is available in, use the limitedMarkets variant attribute.

Remove product group from market

{ "removePartial": { "productGroup": "pg1", "market": "se" } }

Remove product from market

{ "removePartial": { "product": "p1", "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" } }

​Adding entities

​Adding product groups

​Add basic product group

​Add product group with advanced feature usage

​Adding translations

​Add translation

​Add all translations for product group example

​Adding content

​Add content with advanced feature usage

​Adding products and variants

​Add new product to existing product group

​Add new variant to existing product

​Editing entities

​Extending market support

​Add existing product and variants to new markets

Add market through the markets array

Add market through a new override

​Add existing content to new markets

Add market through the markets array

Add market through a new override

​Extending locale support

​Add locale data for product

​Add locale data for content

​Changing specific properties

​Update variant price and stock level

​Add custom label to product

​Edit content type

​Removing data

​Remove entities completely

​Remove product groups

​Remove products

​Remove variants

​Remove content

​Remove image

​Remove entity market data

​Remove translations for locale

Adding entities

Adding product groups

Add basic product group

Add product group with advanced feature usage

Adding translations

Add translation

Add all translations for product group example

Adding content

Add content with advanced feature usage

Adding products and variants

Add new product to existing product group

Add new variant to existing product

Editing entities

Extending market support

Add existing product and variants to new markets

Add market through the `markets` array

Add existing content to new markets

Add market through the `markets` array

Extending locale support

Add locale data for product

Add locale data for content

Changing specific properties

Update variant price and stock level

Add custom label to product

Edit content type

Removing data

Remove entities completely

Remove product groups

Remove products

Remove variants

Remove content

Remove image

Remove entity market data

Remove translations for locale