XML Format specification (Admin v3)¶
The format specification of the data feed describes how the product data needs to be formatted and structured to be imported into Voyado Elevate. This data feed is an XML-file encoded using UTF-8. For full examples of the file syntax, see Import examples.
Newer format specification
The xml format is the data import format used in version 3 of the Admin API. For newer versions, use the JSON lines format and look here for the specification.
Attribute and element highlighting
- Required fields must be provided for the import to be accepted.
- Conditionally required fields are only required as stated by the conditions.
- Recommended fields are important to very central features and are highly recommended to supply when possible.
- Fields that are not highlighted are optional but may be required to enable specific features or performance gains. It is recommended to provide this information when easily accessible, or when needed for specific features. This information can often favorably be added iteratively once a data feed with required and recommended elements are in place.
Market identifiers and key conventions
Market identifiers and keys for product groups, products, and variants must be consistent across the data feed, the order notifications, and the order history. All keys within a market must be unique and are case sensitive.
Product data¶
Product data consist of product groups that include products that in turn include variants. Maximum length of an element value is 2 000 000 characters.
Product group¶
The first level of the data model is the product group (the overall article). The product group holds attributes that are common for all its products and variants. A product group must contain at least one product.
<product_group key="1001">
<brand>Gazelle</brand>
<department>Men</department>
<products suppress_duplicates="true">
... <!-- As described in the product section -->
</products>
</product_group>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
key | string | The key of this product group, must be unique within all key attributes for the market.Required Type restrictions: Maximum length is 50 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
brand | string | The brand of the product group e.g. Calvin Klein or Bosch. It is searchable, used as an autocomplete phrase, and supports faceting. Recommended |
department | string | Element used to filter on department. This supports faceting and search. Supports multiple pipe-separated ( |) values, see Escaping special characters. |
size_type | string | Enables manually defined grouping of sizes in the size facet. Can be any value. |
products | product | Group element for products. Requires at least one product. Required element for data import. |
suppress_duplicates | boolean | An optional attribute set on the products element. If set to true, e.g. <products suppress_duplicates="true">, this product group will only show up once in a product listing. Useful for visually similar product groups. Will default to false if omitted in the data feed. |
Product¶
A product is a color or style variation of a product group and contains attributes that are specific to this variation. Each product in turn must contain at least one variant and is strongly recommended to have at least one image.
<product key="1001-100">
<title>Linen T-shirt</title>
<url>/products/1001-100</url>
<release_date>2019-10-27T00:00:00Z</release_date>
<description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
<categories>men > clothing > t-shirts & polos > t-shirts</categories>
<images>
... <!-- As described in the images section -->
</images>
<custom_attributes>
<season>Summer</season>
<style>Casual</style>
<material>Cotton</material>
</custom_attributes>
<custom>
<lengths>
<package_width>
<amount>37.5</amount>
<unit>cm</unit>
</package_width>
</lengths>
</custom>
<variants>
... <!-- As described in the variant section -->
</variants>
</product>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
key | string | The key of this product, must be unique within all key attributes for the market.Required Type restrictions: Maximum length is 50 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
title | string | The title of the product. Searchable and used as an autocomplete phrase. The title is usually displayed on the product card together with a brand and name to quickly describe the product to the visitor. Examples: "Plate 28 cm, red" "Teddy-lined suede jacket". Required |
url | string | The URL to the product page of this product. If a shared page is used for the product group, ensure that the correct style/color is preselected. Required Type restrictions: Must be relative to page root, i.e. start with /. Relative path example: /products/1001-100 |
categories | string | The categories of the product. Used to define pages in the apps and to help Elevate understand the product. Recommended Use the greater than symbol ( >) to specify hierarchy if this information is available, e.g. Clothing > Trousers > Chinos. Spaces are optional but should be consistent.Supports multiple pipe-separated ( |) values. Supports attribute names. For more information about categories, see Categories. |
variants | variant | Group element for variants. Requires at least one variant. Required element for data import. |
release_date | ISO 8601 | Used for ranking and adding badges to new items and for sorting by newest first. Recommended Type restrictions: Time is in the ISO 8601 format. The only accepted decimal separator is a dot, ., and it is only allowed after seconds. The minimum required precision is a day but it is recommended to set it as precise as possible. |
description | string | The description of the product, used for automatic data extraction. The description is not directly searchable by default. To enable search hits in the description element, contact Voyado Support. Recommended |
images | images | Group element for images. Requires at least one image if present. Recommended |
custom_attributes | custom attributes | Group element for custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app. Recommended Supports multiple pipe-separated ( |) values, see Escaping special characters.Supports attribute names. Type restrictions: Maximum length of custom element names is 2 000 characters. |
custom | typed custom attributes | Group element for typed custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app. |
pattern | string | The pattern of the product, such as Dotted or Striped. This supports faceting and search.Supports multiple pipe-separated ( |) values, see Escaping special characters. |
rating | double | A product rating. Enables ratings in product cards. For more information about ratings, see Additional features. Type restrictions: Ratings must be a decimal number from 0.0 to 5.0. |
color_default | color code | The default color of the product, used until automatic color analysis can be performed. Recommended for products with metallic properties. For more information about color analysis, see Image and data analysis. Supports multiple pipe-separated (|) values.Type restrictions: Valid color codes are provided as hex, e.g. #ffffff. Additional valid values are Gold, Silver, or Multi. |
color_override | color code | An override of the product color, used to override the color analysis and the color_default attribute. For more information about color analysis, see Image and data analysis. Supports multiple pipe-separated (|) values.Type restrictions: Valid color codes are provided as hex, e.g. #ffffff. Additional valid values are Gold, Silver, or Multi. |
product_type_default | string | Used as a strong hint to the automatic product type analysis in identifying the product type. Especially useful when a product falls into multiple categories or lacks explicit mention of its type. Examples: truckercap, book or potato peeler. Key pointers: Avoid broad and general terms like tools, headwear, library or clothing, opt for single specific product type terms, avoid broader categories or multiple products, such as t-shirts/tops or beds & mattresses. |
style_with | string | A list of product keys for products that should appear in the Style with recommendation on a product page. Supports multiple pipe-separated (|) product keys. There can be a maximum of 20 product keys. |
series | string | The name of the series that this product belongs to, if any. This is mainly used for recommendations and is a recommended attribute to use as it facilitates the use of filters, improves site performance, and SEO. Examples: iPhone 15, Air Jordan. Recommended Supports attribute names. We recommend using attribute names for series in order to allow different series to have the same name, yet not show up as recommendations to each other. For more information on recommendations regarding the series attribute, see More from series. |
name | string | The product's name, if any. These are generally proper names given to products by the vendor. They are often identical to the series name. If the product doesn't have a name, this attribute should be omitted. The name should not be confused with title or brand. Examples: iPhone, Corolla, KALLAX. |
width | length | The width of the product, e.g. width of a book shelf. Supports faceting, search, and sorting. |
height | length | The height of the product, e.g. height of a miniature statue. Supports faceting, search, and sorting. |
length | length | The length of the product, e.g. length of a wire-lock. Supports faceting, search, and sorting. |
depth | length | The depth of the product, e.g. depth of a moving box. Supports faceting, search, and sorting. |
volume | volume | The volume of the product, e.g. how much a shampoo bottle contains. Supports faceting, search, and sorting. |
weight | weight | The weight of the product, e.g. how heavy an item is. Supports faceting, search, and sorting. |
Images¶
The images element is a part of the product element and contains one or more image elements. The image element defines a single image which may have URLs with different resolutions of the same image. Multiple resolutions are used for saving bandwidth and are especially useful for thumbnails. An image element must have an urls element which must have at least one URL and URLs must be unique within a product. If relative image resolutions are known, the image URLs should be ordered by ascending width, i.e. smallest first, otherwise it can lead to inconsistencies before it is analyzed automatically. There can be a maximum of 25 images on a product.
<images>
<image>
<urls>
<url>//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
<url>//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
</urls>
</image>
<image>
<urls>
<url>//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
<url>//cdn.example.com/images/1001-100_cutout.jpg</url>
</urls>
</image>
</images>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
image | element | A group element for one image. Contains advanced image attributes and urls. Required |
urls | element | A group element for the url elements of one image.Required |
url | string | The URL to the image. Multiple url elements containing different resolutions of the same product image may be provided for optimal performance.Required Type restrictions: URL:s must be absolute and start with http://, https://, or //. Using // is good practice, as it will use the same scheme as the site.Absolute path: //cdn.example.com/images/1001-100_cutout.jpg |
Advanced image imports¶
Advanced image imports
Additional attributes regarding image tags, widths, and types can be set in the import. These attributes are mainly for use before the automatic image analysis is complete. There is also support for custom image attributes and the alt and caption elements.
<images>
<image>
<type_default>model</type_default>
<tags>Hero|Good</tags>
<alt>A woman wearing a white t-shirt</alt>
<caption>The model is 176 cm tall and is wearing size S</caption>
<urls>
<url width="200">//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
<url width="600">//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
</urls>
</image>
<image>
<type_override>cutout</type_override>
<alt>A white t-shirt</alt>
<urls>
<url width="40">//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
<url width="600">//cdn.example.com/images/1001-100_cutout.jpg</url>
</urls>
</image>
<image>
<type_override>misc</type_override>
<custom_attributes>
<user>John Doe</user>
<type>Instagram</type>
</custom_attributes>
<urls>
<url width="600">//cdn.example.com/images/1001-100_influencer.jpg</url>
</urls>
</image>
</images>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
tags | string | Element of image that allows custom tagging of images for image prioritization in the product cards set in the Elevate apps. Supports multiple pipe-separated (|) values, see Escaping special characters. |
width | integer | Attribute of url that specifies the pixel width of the target image. Used until automatic image analysis can be performed. For more information about image analysis, see Image and data analysis. Type restrictions: Must be a positive integer. |
type_default | string | Element of image describing the type of image, used until automatic image analysis can be performed. For more information about image analysis, see Image and data analysis. Type restrictions: Can be either model, cutout, or misc. |
type_override | string | Element of image overriding the analyzed image type. For more information about image analysis, see Image and data analysis. Type restrictions: Can be either model, cutout, or misc. |
alt | string | Element of image specifying the alt text of an image. The alt text should describe the image. Always returned along with the image. |
caption | string | Element of image specifying the caption for the image, only returned on the product page (or content information for content). |
custom_attributes | custom attributes | Group element for custom user-defined attributes which is always returned with the image. Name restrictions: Maximum length of custom names is 100 characters. Names may only contain letters, digits, dash (-) and/or underscore (_). Supports attribute names. |
type | N/A | Replaced by type_default. |
resolution | N/A | Replaced by width. |
Attribute names¶
The categories attribute, series attribute and custom attributes on products and variants can have a name attribute. The name is used to link a human-friendly name to an identifier to simplify merchandising without breaking the site when values change.
<custom_attributes>
<season name="Summer">m_678</season>
<style name="Casual|Baggy">m_c_349|m_c_333</style>
</custom_attributes>
<categories name="men > t-shirts">c102</categories>
<series name="Professional">Professional-Skeppshult</series>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
name | string | Attribute that contains the human-friendly value that is displayed instead of the identifier. Supports multiple pipe-separated ( |) values, see Escaping special characters. Type restrictions: The number of identifiers must match the provided number of names when multiple pipe-separated values are used. The identifier must be unique and not associated to more than one name within an import. |
Additional information
It is strongly advised to use stable IDs when creating pages and/or boost/bury but it is hard for merchandisers to work with IDs. To solve this problem a name can be used to tie a name and an ID together. An attribute with a name will work just as an attribute with the name as its value in all aspects, except for filtering and making product selections. When making product selections in the apps the name will be shown but the ID will be saved. This means that if the name changes no pages or boost/bury will stop working.
Names are supplied as an XML attribute to the attribute element. Below is an example:
<custom_attributes>
<season name="Summer">m_678</season>
<style name="Casual|Baggy">m_c_349|m_c_333</style>
<material name="Cotton">349</material>
</custom_attributes>
<categories name="men>t-shirts">c102<categories>
In this example, for the first element season is the attribute, Summer is the name, and m_678 is the ID. The name Summer will be searchable and used by Elevate to understand the product. Summer will also be shown in the apps, but if chosen, the ID m_678 will be saved instead of the name Summer.
Import rules for name:
- The number of pipe-separated values supplied must match the number of names. The first name represents the first value and so on. In the example above,
Baggyis the name of the style with the IDm_c_333. If a custom attribute has multiple values and only some of them have names, then the ID should be entered as the name for the ID's which are missing a name. It is recommended to use names for either all values or none within one attribute. - IDs must only have one name. If an ID is associated with multiple names in the same import, the import will fail.
- If two IDs within the same custom attribute share the same name, faceting will consider them to be the same but product selections will consider them separate. In the apps names with multiple IDs will be represented as
name (ID). - Setting or changing a name on one product will apply the name to all instances of that ID on all products in the import and previously existing products. If an ID has a name it is recommended to always include the name alongside the ID.
- If a value that has had a name since a previous import is only mentioned without name in a new import, the name will be removed from all previously existing products.
Typed custom attributes¶
The custom element allows custom attributes of specific types to be imported. Supplying types on custom attributes enables type specific features, such as range facets for lengths and numbers.
The supported types are lengths and numbers.
Length custom attributes
Custom attributes of type lengths can be used to define secondary measurement attributes, such as the package size. Within the lengths element, the name of the custom length attribute is specified, followed by the length information.
<custom>
<lengths>
<package_width>
<amount>37.5</amount>
<unit>cm</unit>
</package_width>
<package_height>
<amount>10</amount>
<unit>cm</unit>
</package_height>
<package_depth>
<amount>25</amount>
<unit>cm</unit>
</package_depth>
</lengths>
</custom>
Number custom attributes
Custom attributes of type numbers can be used to define number attributes, such as the number of items in a package. Negative numbers are supported.
<custom>
<numbers>
<items_in_package>12</items_in_package>
</numbers>
</custom>
Predefined measurements¶
Predefined measurements like width, height, length, depth, weight, and volume share product and variant values in facets, product selections and sorting. This means that there is a single facet for e.g. width that holds all width values regardless of whether they are provided at product or variant level.
In the import, each product must have predefined measurements specified, either at product level or variant level. When provided at variant level, all the variants of a product must specify the predefined measurement.
Lengths¶
Length properties consist of an amount and a unit describing a specific length. Lengths can be predefined measurements or supplied as typed custom attributes.
Length format
<amount>10</amount>
<unit>cm</unit>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
amount | double | The amount of the length. Must be a positive value. |
unit | string | The unit of the length. Must be one of mm, cm, dm, m, in, ft, yd. |
Volume¶
Volume is a property type consisting of an amount and a unit describing a specific volume. Volume is a predefined measurement.
Volume format
<amount>10</amount>
<unit>cl</unit>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
amount | double | The amount of the volume. Must be a positive value. |
unit | string | The unit of the volume. Must be one of ml, cl, dl, l, oz, gal. |
Weight¶
Weight is a property type consisting of an amount and a unit describing a specific weight. Weight is a predefined measurement.
Weight format
<amount>10</amount>
<unit>kg</unit>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
amount | double | The amount of the weight. Must be a positive value. |
unit | string | The unit of the weight. Must be one of mg, g, hg, kg, lb, oz. |
Variant¶
A variant is a stock-keeping-unit (SKU) and contains attributes that are specific to the SKU. A variant typically represents a single physical size, and a physical size can be expressed in several formats, see Sizes, section Advanced size import.
<variant key="1001-100-1">
<stock_number>12</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=XS</url>
<length>
<amount>68</amount>
<unit>cm</unit>
</length>
<sizes>
<size>XS</size>
</sizes>
<custom_attributes>
<ean_code>1234567890123</ean_code>
</custom_attributes>
</variant>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
key | string | The key of the variant element, must be unique within all key attributes for the market.Required When using Voyado Elevate with Voyado Engage, the key must be the same as the article SKU in Voyado Engage, sku. Type restrictions: Maximum length is 50 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
stock_number | integer | Number of items in the online (default) stock, used in ranking and marking the variant as out-of-stock. Negative values are treated as 0. Required Type restrictions: Must be an integer. |
selling_price | double | The price that the customer pays. When the variant is on sale, the selling_price is lower than the list_price.Required Type restrictions: Must be a decimal number, less than or equal to the list_price. |
list_price | double | The standard price. Required Type restrictions: Must be a decimal number, greater than or equal to the selling_price. |
sizes | sizes | A group element for the size element of this variant. Requires at least one size if present.Do not use label or sizes if there is only one variant per product.Conditionally required Required under the following circumstances: * The product has more than one variant. * label is not used. |
cost | double | The cost of the product. Can also be provided in payment notifications, in which case the notification cost has precedence. Used for reports and is required for utilizing profit-optimizing algorithms. Never sent client side. Recommended Type restrictions: Must be a decimal number. Must be a non-zero value less than the sellingPrice |
url | string | The URL to the product page with this size preselected. Enables more specific link targets in product listings. Recommended Type restrictions: Must be relative to page root, i.e. start with /. Relative path: /variant?variant_key=123-B-S. |
label | string | The title of the variant. Used to represent the variant from the product page. Defaults to a size if not supplied. Useful if sizes are not being used or there are multiple size formats available and there is a specific size format or a size format combination that should be shown. E.g. on a shoe with size 40 in EU and size 7 in US, the label could be "40 (US 7) or "40". Do not use label or sizes if there is only one variant per product.Conditionally required Required under the following circumstances: * The product has more than one variant. * sizes are not used. |
custom_prices | custom prices | A group element for custom prices. Enables custom prices for specific visitors or prices in multiple currencies within the same market. For more information about custom prices, see Additional features. |
stores | stores | A group element for stores. Enables store specific stock numbers to be stored on each variant. For more information about stores, see Store specific stock numbers. |
custom_attributes | custom attributes | Group element for custom user-defined attributes on variant level. These support faceting and search and can be selected for use as facets in the Settings tab in the Experience app. It is recommended to use custom attributes on product level whenever applicable, and only use variant level custom attributes when required. Supports multiple pipe-separated ( |) values, see Escaping special characters.Supports attribute names. Type restrictions: Maximum number of custom attributes per variant is 20. Maximum number of unique custom attributes on variants across a market-locale combination is 1 000. Maximum length of custom element names is 2 000 characters. |
custom | typed custom attributes | Group element for typed custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app. It is recommended to use custom attributes on product level whenever applicable, and only use variant level custom attributes when required. |
order | integer | An override of the variants' position within the parent Product response object. The position is evaluated by the order value in ascending order. Required on all variants within a product if used. |
width | length | The width of the variant, e.g. width of a book shelf. Supports faceting, search, and sorting. |
height | length | The height of the variant, e.g. height of a miniature statue. Supports faceting, search, and sorting. |
length | length | The length of the variant, e.g. length of a wire-lock. Supports faceting, search, and sorting. |
depth | length | The depth of the variant, e.g. depth of a moving box. Supports faceting, search, and sorting. |
volume | volume | The volume of the variant, e.g. how much a shampoo bottle contains. Supports faceting, search, and sorting. |
weight | weight | The weight of the product, e.g. how heavy an item is. Supports faceting, search and sorting. |
Sizes¶
Sizes is a part of the variant element and contains one or more size elements.
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
size | string | The size of a variant. Required if sizes is present. Supports multiple pipe-separated (|) values, see Escaping special characters. See also: Sizes - fraction handling. Type restrictions:Duplicate values are not allowed. |
Advanced size import
Each variant has a single physical size, but the size can be expressed in several formats. For example, a shirt can be considered both a size S and sizes 34 and 36 simultaneously. If multiple formats are known, all should be provided.
The format of the size is specified as an attribute and the actual size is provided as the value of the size element.
<sizes>
<size custom_format="SML">S</size>
<size custom_format="EU">34|36</size>
</sizes>
Multiple variants with the same format and value are allowed, as long as there is one format with a unique single value. For example, the snippet below shares the value 36 in the format EU with the example above, but may be imported as sizes for another variant as the sizes have unique values in the format SML.
<sizes>
<size custom_format="SML">M</size>
<size custom_format="EU">36|38</size>
</sizes>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
custom_format | string | Attribute to the size element that describes the format that the size is provided in. It should follow key conventions and is required if multiple sizes are provided. |
Custom prices¶
The custom_prices element is a part of the variant element and contains one or more price elements. The maximum number of price elements for a variant is 1 000.
Advanced price import
For more information about custom prices, see Additional features.
<custom_prices>
<price id="EUR">
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
</price>
<price id="SEK">
<selling_price>99.90</selling_price>
<list_price>129.90</list_price>
</price>
<price id="VIP_SEK">
<selling_price>69.90</selling_price>
<list_price>129.90</list_price>
</price>
</custom_prices>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
price | element | Contains selling_price and list_price for a specific id. Required |
id | string | Attribute to the price element. The id indicates which price should be displayed. If a custom price with a specific id has been provided to a variant, all variants within that product must be provided with price information for that price id. Products with price inconsistencies among variants will cause the import to fail. Required |
selling_price | double | The price that the customer pays. When the variant is on sale, the selling_price is lower than the list_price. Displayed on the product card and used for badges.Required Type restrictions: Must be a decimal number, and be less than or equal to the list_price. |
list_price | double | The price displayed in the shop as the standard price. Required Type restrictions: Must be a decimal number, and be greater than or equal to the selling_price. |
Stores¶
The stores element is a part of the variant element and contains one or more store elements and their stock numbers.
Advanced stores import
For more information about stores, see Store specific stock numbers.
<stores>
<store key="240">
<stock_number>5</stock_number>
</store>
<store key="100">
<stock_number>0</stock_number>
</store>
</stores>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
store | element | Contains stock_number for a specific store. |
key | string | Attribute on the store element. The key identifies the store. Required Type restrictions: Maximum length is 50 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
stock_number | integer | Number of items of this variant in stock in the store, used in ranking and marking the variant as out-of-stock. Negative values are treated as 0. Required Type restrictions: Must be an integer. |
Content¶
The content element enable visitors to find editorial content items on a site, such as FAQs, shipping, and contact information. Content items are usually placed after the product groups in the import files.
<content key="842">
<type>article</type>
<title>It's finally sweater season</title>
<link>/uk/articles/its-finally-sweater-season-2020-11-20/</link>
<release_date>2020-11-20T00:00:00Z</release_date>
<description>As the holiday season approaches, temperatures start to fall
and skies begin to darken. It is time to embrace the clothes that will
get you through the chilliest days and nights of the year - the sweater.
Warm, comfortable, and stylish when it matters the most.</description>
<image>
<urls>
<url>//cdn.example.com/images/content/sweater_season_2020.jpg?preset=800x400</url>
</urls>
</image>
<custom_attributes>
<tags>Winter|Fashion</tags>
</custom_attributes>
</content>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
key | string | The key of this content, must be unique for the market. Required Type restrictions: Maximum length is 50 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
type | string | The type of the content. Used for grouping and filtering content mainly. Required Type restrictions: A maximum of 25 different types can be used. |
title | string | Title of the content item. Required |
link | string | URL to the page on this topic. Can be relative or absolute. Relative URLs must be relative to page root, i.e. start with /. Absolute URLs must start with http://, https://, or //. Using // for absolute URLs is good practice, as it will use the same scheme as the site.Relative path: /uk/customer-service/shippingAbsolute path: //cdn.example.com/uk/customer-service/shippingRequired |
release_date | ISO 8601 | Used for sorting by newest first. Type restrictions: Time is in the ISO 8601 format. The only accepted decimal separator is a dot, ., and it is only allowed after seconds. The minimum required precision is a day but it is recommended to set it as precise as possible. |
description | string | The description of the content. Used for search but valued less than other attributes when evaluating a match. |
image | image | One image representing the content. |
custom_attributes | custom attributes | Group element for custom user-defined attributes. These supports search and are returned with the content item in the results. The user-friendly name attribute is not supported for custom attributes for content. Supports multiple pipe-separated ( |) values, see Escaping special characters.Supports attribute names. Type restrictions: Maximum length of custom element names is 2 000 characters. |
Old content link format
The old content link import format is still supported for backwards compatibility. The new and old format can not be mixed in an import. The old format is shown below.
<modify market="UK" locale="en-GB">
<content_links>
<add_or_replace>
<content_link key="871">
<title>Shipping</title>
<url>/uk/customer-service/shipping</url>
</content_link>
...
</add_or_replace>
</content_links>
Elements and attributes¶
| Name | Type | Description |
|---|---|---|
key | string | The key of this content link, must be unique for the market. Required Type restrictions: Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and #+./_-. |
title | string | Title to be displayed as text completion. Required |
url | string | URL to the page on this topic. Can be relative or absolute. Relative URLs must be relative to page root, i.e. start with /. Absolute URLs must start with http://, https://, or //. Using // for absolute URLs is good practice, as it will use the same scheme as the site.Relative path: /uk/customer-service/shippingAbsolute path: //cdn.example.com/uk/customer-service/shippingRequired |
Imports¶
An import can be either a full, a partial, or an attribute modification import. The import type is based on the root element of the import file. The import file type is XML and must be encoded using UTF-8.
A full import is used to set the complete state of the product and content data for all markets. Partial updates are used to add, replace, or remove product or content items.
The attribute modification import has a different root element than full and partial imports. It is used for frequent updates of item attributes such as selling_price and stock_number. Only attributes defined in the import will be modified. The attribute modification import can also add new attributes to existing items.
For more information on when to use full, partial, or attribute modifications imports, see Scheduled imports.
Data import¶
The data import is either full or partial and is the root element of an import XML file. Three elements, remove_all, remove, and add_or_replace, in the XML file define what Elevate will do with the data in the file.
The full import sets the complete state of the data, thus anything that is not declared in the import will be deleted from Elevate, regardless of market. This enables a retailer to do a full synchronization between their systems and Elevate. Data is added into Elevate by using the add_or_replace element.
A partial import have the type attribute set to partial. This means that no data is automatically removed at the beginning of the import unless remove or remove_all are present in the file before using add_or_replace. Note that partial updates of product groups replaces the entire group. This means that the product group is expected to be complete as it replaces all information about the product group and any connected products and variants. To only modify information, use Attribute modification.
Elements and attributes¶
| Name | Description |
|---|---|
type | Defines the type of import when using data_import. Valid values are full and partial. Required |
modify | Element that defines the market and locale to perform import operations on.Required |
add_or_replace | Operation that adds new, or update existing, product_groups or content_items for the market that is modified by the import. |
remove | Operation that allows removal of an individual product_group or content_items. Requires a key value for each element that is to be removed. |
remove_all | Operation that removes all product_groups or content_items for the market that is modified by the import. |
Modify¶
The modify element is used by the full and partial import methods. It defines the market and locale that is being imported. Multiple markets can be modified in the same import. A market and locale combination can only be modified once during an import.
<modify market="UK" locale="en-GB">
<!-- Product groups and content for the market UK -->
</modify>
<modify market="BE" locale="nl-NL">
<!-- Product groups and content for the market BE in Dutch -->
</modify>
<modify market="BE" locale="fr-FR">
<!-- Product groups and content for the market BE in French -->
</modify>
Elements and attributes¶
| Name | Description |
|---|---|
market Details | A market key. Required Type restrictions: Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-. |
locale | Locale for searching, used when matching items in the market. Also defines which synonyms will be used. Given on the format <language>-<COUNTRY>, e.g. en-GB. An important thing to note is that setting the locale will change the locale for all items in the market, including previously imported items. Current supported locales:bg-BG, cs-CZ, da-DK, de-AT, de-CH, de-DE, el-GR, en-001, en-150, en-AU, en-CA, en-GB, en-IE, en-IN, en-PH, en-HK, en-TW, en-MO, en-US, es-ES, es-MX, et-EE, fi-FI, fr-BE, fr-CA, fr-CH, fr-FR, he-IL, hr-HR, hu-HU, is-IS, it-CH, it-IT, ja-JP, ko-KR, lt-LT, lv-LV, nb-NO, nn-NO, no-NO, nl-BE, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sr-RS, sv-FI, sv-SE, tr-TR, vi-VN, zh-CN, zh-HK, zh-TW and zh-MO.Required |
Attribute modification¶
The attribute modification import has the root element attribute_modification in the import XML file. It is used to modify attributes within individual items, as well as to add new attributes to existing items.
All items that are to be modified, such as product_groups, product, variant, and content are identified by their key attribute values. If an item cannot be identified, e.g. due to an incorrect or nonexistent key, that item will be ignored, a warning will be logged, and the rest of items are imported normally. Nesting of products within product groups and variants within products in the XML is not allowed.
The modify_attributes element is used by the attribute modification. It defines what existing market and locale that content will be operated on. Multiple markets and locales can be modified in the same import. A market and locale combination can only be modified once during an import.
For markets with exactly one locale, the locale may be omitted. For markets with multiple locales, the locale must be specified except for Cross-locale attribute modifications, see below.
Product groups, products, variants, and content are modified separately when performing a attribute modification.
<attribute_modification>
<modify_attributes market="CA" locale="en-CA">
<product_groups>
<!-- Modifications on the Product groups level for the market CA and locale en-CA -->
</product_groups>
<products>
<!-- Modifications on the Products level for the market CA and locale en-CA -->
</products>
<variants>
<!-- Modifications on the Variants level for the market CA and locale en-CA -->
</variants>
<content_items>
<!-- Modifications of Content for the market CA and locale en-CA -->
</content_items>
</modify_attributes>
<modify_attributes market="CA" locale="fr-CA">
<product_groups>
<!-- Modifications on the Product groups level for the market CA and locale fr-CA -->
</product_groups>
<products>
<!-- Modifications on the Products level for the market CA and locale fr-CA -->
</products>
<variants>
<!-- Modifications on the Variants level for the market CA and locale fr-CA -->
</variants>
<content_items>
<!-- Modifications of Content for the market CA and locale fr-CA -->
</content_items>
</modify_attributes>
</attribute_modification>
Elements and attributes¶
| Name | Description |
|---|---|
modify_attributes | Element that defines the market to perform updates on. Required |
market Details | A market key. Required Type restrictions: Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-. |
locale | Locale for searching, used when matching items in the market. Also defines which synonyms will be used. Given on the format <language>-<COUNTRY>, e.g. en-GB. Locale is optional for single-locale markets and for cross-locale attribute modifications. |
product_groups | Element that contains the product groups that are to be modified. |
products | Element that contains the products that are to be modified. |
variants | Element that contains the variants that are to be modified. |
content_items | Element that contains the content that are to be |
Cross-locale attribute modifications¶
On markets with multiple languages, stock, cost, and price may be modified across all locales in a market. A cross-locale attribute modification is specified by omitting the locale in the modify_attributes element.
Warning
Cross-locale attribute modifications cannot be combined with normal attribute modifications on the same market in the same import. For more information, see Multilingual markets.
Import examples¶
Full import¶
The following example will add items to a site with market set to UK and locale set to en-GB. Any previous data not included in the import will be deleted from Elevate, regardless of market.
Full import example with basic information
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="full">
<modify market="UK" locale="en-GB">
<product_groups>
<add_or_replace>
<product_group key="1001">
<brand>Gazelle</brand>
<department>Men</department>
<products>
<product key="1001-100">
<title>Linen T-shirt</title>
<url>/products/1001-100</url>
<release_date>2019-10-27T00:00:00Z</release_date>
<description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
<images>
<image>
<urls>
<url>//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
<url>//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
</urls>
</image>
<image>
<urls>
<url>//cdn.example.com/images/1001-100_cutout.jpg?preset=200x200</url>
<url>//cdn.example.com/images/1001-100_cutout.jpg?preset=600x600</url>
</urls>
</image>
</images>
<custom_attributes>
<season>Summer</season>
<style>Casual</style>
<material>Cotton</material>
</custom_attributes>
<variants>
<variant key="1001-100-1">
<stock_number>12</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=S</url>
<sizes>
<size>S</size>
</sizes>
</variant>
<variant key="1001-100-2">
<stock_number>0</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=M</url>
<sizes>
<size>M</size>
</sizes>
</variant>
<variant key="1001-100-3">
<stock_number>5</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=L</url>
<sizes>
<size>L</size>
</sizes>
</variant>
</variants>
</product>
</products>
</product_group>
</add_or_replace>
</product_groups>
<content_items>
<add_or_replace>
<content key="871">
<type>link</type>
<title>Shipping</title>
<link>/uk/customer-service/shipping</link>
</content>
<content key="872">
<type>link</type>
<title>Contact</title>
<link>/uk/contact</link>
</content>
</add_or_replace>
</content_items>
</modify>
</data_import>
Full import example with advanced feature usage
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="full">
<modify market="UK" locale="en-GB">
<product_groups>
<add_or_replace>
<product_group key="1001">
<brand>Gazelle</brand>
<department>Men</department>
<products>
<product key="1001-100">
<title>Linen T-shirt</title>
<url>/products/1001-100</url>
<release_date>2019-10-27T00:00:00Z</release_date>
<description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
<images>
<image>
<type_default>model</type_default>
<tags>Hero</tags>
<urls>
<url width="200">//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
<url width="600">//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
</urls>
</image>
<image>
<type_override>cutout</type_override>
<urls>
<url width="40">//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
<url width="600">//cdn.example.com/images/1001-100_cutout.jpg</url>
</urls>
</image>
</images>
<custom_attributes>
<season name="Summer">m_678</season>
<style name="Casual">m_c_349</style>
<material name="T-shirts">349</material>
</custom_attributes>
<pattern>striped</pattern>
<rating>4.3</rating>
<color_default>#0000ff|#ffffff</color_default>
<product_type_default>t-shirt</product_type_default>
<variants>
<variant key="1001-100-1">
<stock_number>12</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=S</url>
<sizes>
<size custom_format="SML">S</size>
<size custom_format="EU">36</size>
</sizes>
<custom_prices>
<price id="EUR">
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
</price>
<price id="SEK">
<selling_price>99.90</selling_price>
<list_price>129.90</list_price>
</price>
<price id="VIP_SEK">
<selling_price>69.90</selling_price>
<list_price>129.90</list_price>
</price>
</custom_prices>
</variant>
<variant key="1001-100-2">
<stock_number>0</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=M</url>
<sizes>
<size custom_format="SML">M</size>
<size custom_format="EU">38</size>
</sizes>
<custom_prices>
<price id="EUR">
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
</price>
<price id="SEK">
<selling_price>99.90</selling_price>
<list_price>129.90</list_price>
</price>
<price id="VIP_SEK">
<selling_price>69.90</selling_price>
<list_price>129.90</list_price>
</price>
</custom_prices>
</variant>
<variant key="1001-100-3">
<stock_number>5</stock_number>
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
<cost>8.00</cost>
<url>/products/1001-100?size=L</url>
<sizes>
<size custom_format="SML">L</size>
<size custom_format="EU">40</size>
</sizes>
<custom_prices>
<price id="EUR">
<selling_price>9.99</selling_price>
<list_price>12.99</list_price>
</price>
<price id="SEK">
<selling_price>99.90</selling_price>
<list_price>129.90</list_price>
</price>
<price id="VIP_SEK">
<selling_price>69.90</selling_price>
<list_price>129.90</list_price>
</price>
</custom_prices>
</variant>
</variants>
</product>
</products>
</product_group>
</add_or_replace>
</product_groups>
<content_items>
<add_or_replace>
<content key="871">
<type>link</type>
<title>Shipping</title>
<link>/uk/customer-service/shipping</link>
</content>
<content key="872">
<type>link</type>
<title>Contact</title>
<link>/uk/contact</link>
</content>
<content key="901">
<type>faq</type>
<title>How do I return clothes?</title>
<link>/uk/faq/returns</link>
<release_date>2020-12-01T00:00:00Z</release_date>
<image>
<urls>
<url width="400">//cdn.example.com/images/returns-pic-11204</url>
</urls>
</image>
<custom_attributes>
<keywords>replace|swap|take back</keywords>
</custom_attributes>
</content>
</add_or_replace>
</content_items>
</modify>
</data_import>
Partial import¶
The following example of a partial import that will add or replace one or more product groups, products, variants and content in an existing market with the key UK. The items are identified using their key-values.
Must contain whole product groups
Partial updates of product groups replaces the entire group. This means that the product group is expected to be complete as it replaces all information about the product group and any connected products and variants. To only modify information, use Attribute modification.
Partial import example with add or replace
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
<modify market="UK" locale="en-GB">
<product_groups>
<add_or_replace>
<product_group key="1001">
<!-- attributes omitted for brevity -->
<products>
<product key="1001-100">
<!-- attributes omitted for brevity -->
<variants>
<variant key="1001-100-1">
<!-- attributes omitted for brevity -->
</variant>
</variants>
</product>
</products>
</product_group>
<product_group key="1024">
<!-- ... -->
</product_group>
</add_or_replace>
</product_groups>
<content_items>
<add_or_replace>
<content key="871">
<!-- attributes omitted for brevity -->
</content>
</add_or_replace>
</content_items>
</modify>
</data_import>
The following example of a partial import will remove all product_groups and content_items from an existing market with the key UK.
Partial import example with remove all
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
<modify market="UK" locale="en-GB">
<product_groups>
<remove_all/>
</product_groups>
<content_items>
<remove_all/>
</content_items>
</modify>
</data_import>
The following example of a partial import will remove a specific product_group and content from an existing market with the key UK. The items are identified using their key-values.
Partial import example with remove
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
<modify market="UK" locale="en-GB">
<product_groups>
<remove>
<!-- Removes product group with key = 1002 from market UK-->
<product_group key="1002"/>
</remove>
</product_groups>
<content_items>
<remove>
<!-- Removes content with key 984 from market UK -->
<content key="873"/>
</remove>
</content_items>
</modify>
</data_import>
Attribute modification¶
The common use case for attribute modifications is when updating prices and stock numbers.
The following example of an attribute modification import will update specific values for a product_group, a product, a variant, and a content item on an existing market with the key UK. The items are identified using their key-values.
Attribute modification import example
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
<modify_attributes market="CA" locale="en-CA">
<product_groups>
<!-- Update product group with key 1032,
changing only its brand and leaving everything else untouched -->
<product_group key="1032">
<brand>Armani</brand>
</product_group>
</product_groups>
<products>
<!-- Update product with key 1051-110,
changing only its title, custom attribute season, and adding a product type to it -->
<product key="1051-110">
<title>Jane Insulated Boot</title>
<custom_attributes>
<season>Winter</season>
</custom_attributes>
<product_type_default>chelsea boot</product_type_default>
</product>
</products>
<variants>
<!-- Update variant with key 1157-120-1,
changing only its stock_number and selling_price -->
<variant key="1157-120-1">
<stock_number>20</stock_number>
<selling_price>8.99</selling_price>
</variant>
</variants>
<content_items>
<!-- Update conent with key c1,
changing only its title and its custom attribute author -->
<content key="c1">
<title>returns</title>
<custom_attributes>
<author>Pelle</author>
</custom_attributes>
</content>
</content_items>
</modify_attributes>
<modify_attributes market="CA" locale="fr-CA">
<product_groups>
<!-- Update product group with key 1032,
changing only its brand and leaving everything else untouched -->
<product_group key="1032">
<brand>Armani</brand>
</product_group>
</product_groups>
<products>
<!-- Update product with key 1051-110,
changing only its title, custom attribute season, and adding a product type to it -->
<product key="1051-110">
<title>Bottes isolées Jane</title>
<custom_attributes>
<season>Hiver</season>
</custom_attributes>
<product_type_default>chelsea boot</product_type_default>
</product>
</products>
<variants>
<!-- Update variant with key 1157-120-1,
changing only its stock_number and selling_price -->
<variant key="1157-120-1">
<stock_number>20</stock_number>
<selling_price>8.99</selling_price>
</variant>
</variants>
<content_items>
<!-- Update conent with key c1,
changing only its title and its custom attribute author -->
<content key="c1">
<title>retours</title>
<custom_attributes>
<author>Pelle</author>
</custom_attributes>
</content>
</content_items>
</modify_attributes>
</attribute_modification>
Cross-locale attribute modification import example with store specific stock numbers and custom prices
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
<!-- Locale is not specified so this applies to all locales for CA -->
<modify_attributes market="CA">
<variants>
<!-- Update variant with key 1157-120-1,
changing the stock_number for store "240" and no other store -->
<variant key="1157-120-1">
<stores>
<store key="240">
<stock_number>3</stock_number>
</store>
</stores>
</variant>
<!-- Update variant with key 1190-110-2,
changing the selling_price for price id "SEK" -->
<variant key="1190-110-2">
<custom_prices>
<price id="SEK">
<selling_price>33.00</selling_price>
</price>
</custom_prices>
</variant>
</variants>
</modify_attributes>
</attribute_modification>
Escaping special characters¶
Some elements in the data model can take multiple pipe-separated (|) values. Therefore, if the pipe character is part of the data, such as in a category name, it must be escaped using backslash, \, before the actual character, \|. Using backslash in the data must also be escaped using another backslash \\.
Escaping must be done for values in all elements, including single-value elements.
Character escaping example
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
<modify_attributes market="UK">
<products>
<product key="1051-110">
<custom_attributes>
<!-- This results in two values as the pipe is not escaped-->
<tags>Shoes|Boots</tags>
<!-- This results in escaped characters-->
<escaped_pipe>This is a vertical bar, a.k.a. pipe: \|</escaped_pipe>
<escaped_slash>This is a backslash: \\</escaped_slash>
</custom_attributes>
</product>
</products>
</modify_attributes>
</attribute_modification>