Skip to content

Format Specification

The format specification of the data feed describes how the product data needs to be formatted and structured to be imported into eSales Lifestyle. The data feed is an XML-file encoded using UTF-8.

Basic file syntax example
<?xml version="1.0" encoding="UTF-8" ?>
<lifestyle_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>
                            <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>
                            <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.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <urls>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=200x200</url>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                            </images>
                            <custom_attributes>
                                <season>Summer</season>
                                <style>Casual</style>
                                <category>T-Shirts</category>
                            </custom_attributes>
                        </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>
</lifestyle_data_import>
Advanced file syntax example
<?xml version="1.0" encoding="UTF-8" ?>
<lifestyle_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>
                            <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>
                            <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.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url width="600">//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <type_override>cutout</type_override>
                                    <urls>
                                        <url width="40">//cdn.esalesdrivensite.com/images/1001-100_cutout_thumbnail.jpg</url>
                                        <url width="600">//cdn.esalesdrivensite.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>
                                <category name="T-shirts">349</category>
                            </custom_attributes>
                            <pattern>striped</pattern>
                            <rating>4.3</rating>
                            <color_default>#0000ff|#ffffff</color_default>
                        </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">http://returns-pic-11204.com</url>
                        </urls>
                    </image>
                    <custom_attributes>
                        <keywords>replace|swap|take back</keywords>
                    </custom_attributes>
                </content>
            </add_or_replace>
        </content_items>
    </modify>
</lifestyle_data_import>

Attribute and element highlighting

  • Required fields must be provided for the import to be accepted.
  • 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 favourably 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>
        ... <!-- 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 200 characters and allowed characters are A-Z, a-z, 0-9, and #+-./_-.
brand string The brand appears in the product card. It is searchable and visible as an autocomplete phrase. This supports faceting and search.
Recommended
department string Element used to filter on department. This supports faceting and search. Supports multiple pipe-separated (|) values.
Required
products product Group element for products. Requires at least one product.
Required element for Lifestyle data import.
Not allowed for Lifestyle attribute modification.
size_type string Enables manually defined grouping of sizes in the size facet. Can be any value.

Product

A product is a colour 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>
    <images>
        ... <!-- As described in the images section -->
    </images>
    <custom_attributes>
        <season>Summer</season>
        <style>Casual</style>
        <category>T-Shirts</category>
    </custom_attributes>
    <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 200 characters and allowed characters are A-Z, a-z, 0-9, and #+-./_-.
title string The title of the product. Searchable and shown in product cards, and completions.
Required
url string The URL to the product page with this colour/style preselected.
Required

Type restrictions:
Must be relative to page root, i.e. start with /. Relative path example: /products/1001-100
variants variant Group element for variants. Requires at least one variant.
Required element for Lifestyle data import.
Not allowed for Lifestyle attribute modification.
release_date ISO 8601 timestamp Used for ranking and adding badges to new items and for sorting by newest first.
Recommended

Type restrictions:
The time is in the ISO 8601 format, including offset.
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 Apptus 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 supports faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app.
Recommended

Type restrictions:
Maximum length of custom element names is 2 000 characters. Supports multiple pipe-separated (|) values.
pattern string The pattern of the product such as Dotted or Striped. This supports faceting and search. Supports multiple pipe-separated (|) values.
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 colour code The default colour of the product, used until automatic colour analysis can be performed. Recommended for products with metallic properties. For more information about colour analysis, see Image and Data Analysis.

Type restrictions:
Valid colour codes are provided as hex, e.g. #ffffff. Additional valid values are Gold, Silver, or Multi. Supports multiple pipe-separated (|) values.
color_override colour code An override of the product colour, used to override the colour analysis and the color_default attribute. For more information about colour analysis, see Image and Data Analysis.

Type restrictions:
Valid colour codes are provided as hex, e.g. #ffffff. Additional valid values are Gold, Silver, or Multi. Supports multiple pipe-separated (|) values.
product_type_default string The default product type, used until the automatic product type analysis can be performed. Supports multiple pipe-separated (|) values.
style_with string A list of products that should appear in the Style with recommendation zone on a product page. Supports multiple pipe-separated (|) product keys.

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 analysed automatically.

<images>
    <image>
        <urls>
            <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
            <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
        </urls>
    </image>
    <image>
        <urls>
            <url>//cdn.esalesdrivensite.com/images/1001-100_cutout_thumbnail.jpg</url>
            <url>//cdn.esalesdrivensite.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.esalesdrivensite.com/images/1001-100_cutout.jpg
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 are two advanced image elements with no component support yet: alt and caption. There is also support for custom image attributes.

<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.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
            <url width="600">//cdn.esalesdrivensite.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.esalesdrivensite.com/images/1001-100_cutout_thumbnail.jpg</url>
            <url width="600">//cdn.esalesdrivensite.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.esalesdrivensite.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. Supports multiple pipe-separated (|) values.
Not allowed on a content image.
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.
Not allowed on a content image.

Type restrictions:
Can be either model, cutout, or misc.
type_override string Element of image overriding the analysed image type. For more information about image analysis, see Image and Data Analysis.
Not allowed on a content image.

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. No component support yet.
caption string Element of image specifying the caption for the image, only returned on the product page (or content information for content). No component support yet.
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 (_).
type N/A Replaced by type_default.
Deprecated
resolution N/A Replaced by width.
Deprecated

Custom attributes

Custom attributes can have an additional name attribute if the identifier is not human friendly for use with products. Content accepts custom attributes, but not the additional name attribute.

Advanced custom attributes

Since all attribute values used for product selections must be based on stable values, there are occasions where a merchandiser may have to work with system generated numbers or codes.

To facilitate working with product selections with impractical values as identifiers, a display name can be supplied to the attribute. This means that the product selection remains stable, while it is possible to work with readable names in the apps.

Supply an additional field with the identifier and display name for attributes with non human friendly values. The following example illustrates providing an additional information about an external id 349 to the category T-shirts.

Updating advanced custom attributes

When performing an import containing advanced attributes, each identifier must always be related to the same name for all products within the import. Relations are permitted to differ from already imported products that are not included in the current import. In this case, the latest id to name relation will be interpreted as an override, and apply for all products in the catalogue.

<custom_attributes>
    <season name="Summer">m_678</season>
    <style name="Casual|Baggy">m_c_349|m_c_333</style>
    <category name="T-shirts">349</category>
</custom_attributes>
Elements and attributes
Name Type Description
name string Attribute that contains the human friendly value that is displayed instead of the identifier.

Type restrictions:
Supports multiple pipe-separated (|) values.
The number of identifiers must match the provided number of names when multiple pipe-separated values are used.
An identifier must be unique and not associated to more than one name attribute.

Variant

A variant is a SKU (stock-keeping-unit) 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>
    <label>XS</label>
    <sizes>
        <size>XS</size>
    </sizes>
</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

Type restrictions:
Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and #+-./_-.
stock_number integer Number of items in stock, used in ranking and marking the variant as out-of-stock.
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. 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.
sizes sizes A group element for the size element of this variant. Requires at least one size if present. Required if there are more than one variant of the product. Should only be omitted for products without useful sizes.
Conditionally required
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 utilising profit-optimising algorithms. Never sent client side.
Recommended

Type restrictions:
Must be a decimal number.
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 label to show for this variant in the result listings.
If omitted the label will be the first size value.
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.

Sizes

The sizes is a part of the variant element element and contains one or more size elements.

Elements and attributes
Name Type Description
size string The actual size of a variant in a specific format. Required if sizes is present. Supports multiple pipe-separated (|) values.

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 a size 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">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.

<sizes>
    <size custom_format="UK">30L|30/34</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 element and contains one or more price elements.

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.

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.esalesdrivensite.com/images/content/sweater_season_2020.jpg?preset=800x400</url>
        </urls>
    </image>
</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 200 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. The type link must be used if content is to show up in the content suggestions component for auto complete.
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/shipping
Absolute path: //cdn.esalesdrivensite.com/uk/customer-service/shipping
Required
release_date ISO 8601 timestamp Used for sorting by newest first.

Type restrictions:
The time is in the ISO 8601 format, including offset.
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.

Type restrictions:
Maximum length of custom element names is 2 000 characters. Supports multiple pipe-separated (|) values.

Web component usage

Web components are not yet available for all of the content features. Only content with the type link will show up in the content suggestions part of autocomplete. Images representing content and content types other than link are currently only supported via the Web API.

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/shipping
Absolute path: //cdn.esalesdrivensite.com/uk/customer-service/shipping
Required

Markets

Products, variants, content, and behavioural statistics are all tied to a market. A market has a locale (a language/country combination) to correctly handle the text content of its entities. A market cannot contain products in more than one language, so sites with one physical market with multiple languages must be treated as different markets in the data feed.

If a site is available in multiple languages, it must use different markets, each with their own products. When a web site queries eSales, it states which market to fetch content for. Behavioural statistics are collected, and can be viewed, by market.

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.

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 of a market. 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 Continuous product feed.

Lifestyle data import

The lifestyle 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 eSales 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 eSales, regardless of market. This enables a retailer to do a full synchronisation between their systems and eSales. Data is added into eSales 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.

Elements and attributes

Name Description
type Defines the type of import when using lifestyle_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 of an import. Multiple markets can be modified in the same import. A market 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="SE" locale="sv-SE">
    <!-- Product groups and content for the market SE -->
</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: da-DK, de-DE, en-GB, en-US, fi-FI, nb-NO, nn-NO, and sv-SE.
Required

Lifestyle attribute modification

The lifestyle attribute modification import has the root element lifestyle_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. Nesting of products within product groups and variants within products in the XML is not allowed.

The modify_attributes element is used by the Lifestyle attribute modification. It defines what existing market that content will be operated on. Multiple markets can be modified in the same import. A market can only be modified once during an import.

Product groups, products, variants, and content are modified separately when performing a Lifestyle attribute modification.

<lifestyle_attribute_modification>
    <modify_attributes market="UK">
        <product_groups>
            <!-- Modifications on the Product groups level for the market UK -->
        </product_groups>
        <products>
            <!-- Modifications on the Products level for the market UK -->
        </products>
        <variants>
            <!-- Modifications on the Variants level for the market UK -->
        </variants>
        <content_items>
            <!-- Modifications of Content for the market UK -->
        </content_items>
    </modify_attributes>
</lifestyle_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 _-.
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 modified.

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 eSales, regardless of market.

Full import example with basic information
<?xml version="1.0" encoding="UTF-8" ?>
<lifestyle_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>
                            <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>
                            <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.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <urls>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=200x200</url>
                                        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                            </images>
                            <custom_attributes>
                                <season>Summer</season>
                                <style>Casual</style>
                                <category>T-Shirts</category>
                            </custom_attributes>
                        </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>
</lifestyle_data_import>
Full import example with advanced feature usage
<?xml version="1.0" encoding="UTF-8" ?>
<lifestyle_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>
                            <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>
                            <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.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url width="600">//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <type_override>cutout</type_override>
                                    <urls>
                                        <url width="40">//cdn.esalesdrivensite.com/images/1001-100_cutout_thumbnail.jpg</url>
                                        <url width="600">//cdn.esalesdrivensite.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>
                                <category name="T-shirts">349</category>
                            </custom_attributes>
                            <pattern>striped</pattern>
                            <rating>4.3</rating>
                            <color_default>#0000ff|#ffffff</color_default>
                        </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">http://returns-pic-11204.com</url>
                        </urls>
                    </image>
                    <custom_attributes>
                        <keywords>replace|swap|take back</keywords>
                    </custom_attributes>
                </content>
            </add_or_replace>
        </content_items>
    </modify>
</lifestyle_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" ?>
<lifestyle_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>
</lifestyle_data_import>

The following example of a partial import will remove an existing market with the key UK.

Partial import example with remove all
<?xml version="1.0" encoding="UTF-8" ?>
<lifestyle_data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove_all/>
        </product_groups>
        <content_items>
            <remove_all/>
        </content_items>
    </modify>
</lifestyle_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" ?>
<lifestyle_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>
</lifestyle_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 contentitem 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" ?>
<lifestyle_attribute_modification>
    <modify_attributes market="UK">
        <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 and its custom attribute season -->
            <product key="1051-110">
                <title>Brown Linen T-shirt</title>
                <custom_attributes>
                    <season>Winter</season>
                </custom_attributes>
            </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>
</lifestyle_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, 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" ?>
<lifestyle_attribute_modification>
    <modify_attributes market="UK">
        <products>
            <!-- Update product with key 1051-110,
            changing custom attributes -->
            <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>
</lifestyle_attribute_modification>

Last update: June 11, 2021
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE