Skip to content

Data Format Specification

The data format specification describes how products, variants, and related data is to be formatted and structured to comply with imports into eSales for Fashion.

The import file type is XML and must be encoded using UTF-8 and include the operations that is to be performed and all other data type related information.

Data model

The data model and file syntax includes what type of import is to be performed and what market/s that will be modified by the import. A market modifier includes product groups and content links. Different operations are performed on the contents of the product groups and content links.

The elements and components of the data model will be described from the inside out, from the variant to the import type. This is to build up the model from the individual SKUs (Stock Keeping Units) upwards to the markets the SKUs are imported to.

The following example presents the overall syntax of an XML-file for a full import.

File syntax example
<?xml version="1.0" encoding="utf-8" ?>
<fashion_data_import type="full">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove_all/>
            <add_or_replace>
                <product_group>
                    <product key="product1">
                        <variants>
                            <variant key="variant1">
                                <!-- Variant content -->
                            </variant>
                            <!-- More variants -->
                        </variants>
                        <images>
                            <!-- Content for images -->
                        </images>
                        <!-- More product content -->
                    </product>
                    <!-- Product group content -->
                </product_group>
                <!-- More product groups with the same add_or_replace operation -->
            </add_or_replace>
        </product_groups>
        <content_links>
            <remove_all/>
            <add_or_replace>
                <content_link key="contentlink1">
                    <!-- Content links content -->
                </content_link>
                 <!-- More content links with the same add_or_replace operation -->
            </add_or_replace>
        </content_links>
    </modify>
</fashion_data_import>

Market

Products, variants, content links, and behavioural statistics are all tied to a market. A market have 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 market with two languages must be treated as two different markets.

If a site is available in different countries and languages, it must use different markets for the different 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.

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 \. 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.

Data restrictions

The data format includes a few restrictions.

  • No empty elements or attributes are allowed, i.e. <element></element>, attribute="".
  • Maximum length of an element value is 2 000 000 characters.
  • Maximum length of the name of a custom element is 2 000 characters.
  • A product group must contain at least one (1) product.
  • A product must contain at least one (1) variant.
  • Variants must have a size if its parent product group has a size_type.
  • Variants cannot have a size if its parent product group does not have size_type.
  • Multiple variants with the same size value are not allowed within a product.
  • Only one (1) variant is allowed per product when size is missing.

Product data

Product data consist of product groups that include products and variants.

A product is a colour or style variation of a product group and contains attributes, variants, and images that are specific to this colour or style variation. The variant contains attributes such as the size and price of a product.

A product group is a base item that is used to show different colours or styles of a product under the same product card. The product group holds attributes that are common for all its products and variants, and also defines the included products.

Variant

A variant is a SKU (stock-keeping-unit) and contains attributes that are specific to the SKU, such as the size of a product.

The sizes element contains one or more size elements, which define the same size in different formats. Either format or custom_format must be set on the size element. The size value is given in the text value of the element.

<variant key="123-B-S">
    <sizes>
        <size format="SML">S</size>
        <size custom_format="US">6</size>
    </sizes>
    <stock_number>27</stock_number>
    <selling_price>9.99</selling_price>
    <list_price>12.99</list_price>
    <cost>8.00</cost>
    <url>/variant?variant_key=123-B-S</url>
</variant>

Elements and attributes

Name Description
key The key of the variant element. Must be unique for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required attribute.
sizes A group element for the size element of this variant. Includes a list of sizes in one or more formats.
Required element.
size The actual size of a variant in a specific format.
Required element.
format Attribute to the size element. The format is a pre-defined format. Currently only SML (small-medium-large) is defined with sizes between 9XS and 9XL. Sizes can be writen with both letters and numbers, such as 3XL and XXXL, and include combined sizes such as XS/S and M/L. Formats help eSales to sort the value of size correctly and to group different formats together in facets. See also size_type in Product group.
custom_format Attribute to the size element. If the size is on a different format than any of the pre-defined formats, the custom_format attribute can be set to any desired format. Different formats should be used when the size is on a different format than the pre-defined formats. This is to avoid that the size facet get mixed values.
stock_number Number of items in stock, used for optionally demoting products out-of-stock, and marking the variant as out-of-stock.
Required element.
selling_price 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. Must be less than or equal to the list_price.
Required element.
list_price The price displayed in the shop as the standard price. Must be greater than or equal to the selling_price.
Required element.
cost The cost of the product. Can also be provided in payment notifications, in which case the notification cost has precedence. Used for calculating profit for profit-optimising algorithms. Never sent to the front-end.
url The URL to the product page with this size pre-selected. Must be relative to page root, i.e. start with /.

Images

The images element is a part of the product element and contains one or more image elements. Multiple image elements with the same type are allowed.

The image element defines a single image which may have URLs with different resolutions of the same image. An image element must have at least one URL and URLs are not allowed to be duplicates within an images element.

Product listings show a primary image and a hover image for each product. What type that is used as a primary or a hover image is set in the Experience app. If there are more than one image with the same type, eSales will use the first image available as determined by the order of the images with the same type in the import data.

<images>
    <image type="model">
        <url resolution="card">//site.com/images/123-B_model.jpg</url>
        <url resolution="thumbnail">//site.com/images/123-B_model_thumbnail.jpg</url>
    </image>
    <image type="model">
        <url resolution="card">//site.com/images/123-B_model_2.jpg</url>
    </image>
    <image type="cutout">
        <url resolution="card">//site.com/images/123-B_cutout.jpg</url>
        <url resolution="thumbnail">//site.com/images/123-B_cutout_thumbnail.jpg</url>
    </image>
</images>

Elements and attributes

Name Description
image A group element for the url elements of this type.
Required element.
type The type of image. Supported types are: model and cutout. The type model is an image of a model with the product. The type cutout is an isolated image of the product, typically with a white background. The cutout image will be used for automatic colour extraction. Multiple image elements with the same type are allowed.
Required attribute.
url URL to the image in the given resolution. Must be absolute and start with http://, https://, or //. Using // is good practice, as it will use the same scheme as the site.
Required element.
resolution Resolution of the image with this URL. Supported values are: card and thumbnail. If a thumbnail version is missing, don't duplicate the card URL, eSales will handle this automatically.
Required attribute.

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 contains at least one variant and one image.

<product key="123-B">
    <title>Linen T-shirt</title>
    <release_date>2017-10-27T11:16:07Z</release_date>
    <url>/products?product_key=123-B</url>
    <pattern>Striped</pattern>
    <description>Loose-fit T-shirt with a slightly lower neckline.</description>
    <additional_autocomplete_phrases>T-Shirts|Brown T-Shirts</additional_autocomplete_phrases>
    <images>
        ... <!-- As described in the images section -->
    </images>
    <rating>4.3</rating>
    <custom_attributes><!-- Example of custom user-defined 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 Description
key The key of this product, must be unique for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required attribute.
title The title of the product. Searchable and shown in product cards, and completions.
Required element.
url The URL to the product page with this colour/style pre-selected. Must be relative to page root, i.e. start with /.
Required element.
images
Details
Group element for images. Requires at least one image if present.
Required element.
variants
Details
Group element for variants. Requires at least one variant.
Required element.
release_date Release date, used for ranking and adding badges to new items. Used for sorting by newest first. The time is in the ISO 8601 format, including offset.
color_override This attribute allows for overriding analyzed colours for the product. This is useful for the unusual cases where the automatic image analysis does not give satisfying results, or if the product has a metallic colour or is multicoloured. The colours will be searchable, can be used in the colour facet, and the first value will show up as swatch on the product card. Valid values are: Gold, Silver, Multi, or colours in hex, e.g. #ffffff. Supports multiple pipe-separated (|) values.
color_default This attribute is a backup colour for the product. The colour specified in this attribute will be active if color_override is not set and the automatic image analysis does not give results, for instance if a cut-out image isn't available. Valid values are: Gold, Silver, Multi, or colours in hex, e.g. #ffffff. Supports multiple pipe-separated (|) values.
pattern An optional pattern such as Dotted or Striped, for faceting. Supports multiple pipe-separated (|) values.
description A product description used for search.
additional_autocomplete_phrases Phrases that can be of good use in autocomplete, but don’t fit in as any of the other attributes. As there is not yet a standard category attribute, it is highly advisable to add category/product type names here. Supports multiple pipe-separated (|) values.
rating A product rating from 0.0 to 5.0.
custom_attributes Group element for custom user-defined attributes. These can be used in facets and search. Custom facets are added through the app. Supports multiple pipe-separated (|) values.

Product group

A product group is a base item that is used to show different colours or styles of a product under the same product card.

The product group holds attributes that are common for all its products and variants, and also defines the included products.

A product group must contain at least one product.

<product_group key="123">
    <brand>Apparel</brand>
    <department>Men</department>
    <size_type>Men's Clothing</size_type>
    <products>
        ... <!-- As described in the product section -->
    </products>
</product_group>

Elements and attributes

Name Description
key The key of this product group, must be unique for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required attribute.
brand The brand appears in the product card. It is searchable and visible as an autocomplete phrase. It can also be used as a facet.
Required element.
department Element used to filter on department, appears as facet.
Required element.
size_type Used to group each size under a header in the size facet.
Required element.
products
Details
Group element for products. Requires at least one product.
Required element.

Products and variants cannot be added separately and must be added as part of the whole product group.

Apptus eSales does not support editorial content, but it is possible to add links with titles that appears in the search assistant and links to pages on the site.

<content_link key="871">
    <title>Shipping</title>
    <url>/uk/customer-service/shipping</url>
</content_link>

Elements and attributes

Name Description
key The key of this content link, must be unique for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required attribute.
title Title to be displayed as text completion.
Required element.
url 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.
Required element.

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.

A full import is used to set the complete state of the product and content link data of a market. Partial updates are used to a add, replace, or remove product or content link items.

The attribute modification import has a different root element than full and partial imports. It is used for frequent updates of product attributes such as selling_price and stock_number and does not use any import operations.

Fashion data import

The fashion data import is defined by the value of it's attribute type, which is either full or partial. It is the root element of an import XML file.

Import operations

An import XML have three import operations that are performed on the product_groups and content_links elements. These operations are used in different combinations in the two fashion data import types. The fashion attribute modification import type does not use any import operations.

The order of operations in an import are remove_all, remove, and add_or_replace.

<fashion_data_import type="full"> 
    <!-- Used to set the complete state of the data. --> 
</fashion_data_import>
<fashion_data_import type="partial"> 
    <!-- Used to add, replace or remove items. --> 
</fashion_data_import>

Modify

The modify element is used by the full and partial import methods. It defines what market and locale product groups and content links should be operated on in an import.

Multiple markets can be modified at the same time in an import, but a market can only be modified once during the same import.

<modify market="UK" locale="en-GB">
    <!-- Product groups and content links for the market UK -->
</modify>
<modify market="SE" locale="sv-SE">
    <!-- Product groups and content links for the market SE -->
</modify>

Elements and attributes

Name Description
type Defines the type of import when using fashion_data_import. Valid values are full and partial.
Required attribute.
add_or_replace Operation that adds new, or update existing, product_groups or content_links for the market that is modified by the import.
remove Operation that allows removal of an individual product_group or content_link. Requires a key value for each element that is to be removed.
remove_all Operation that removes all product_groups or content_links for the market that is modified by the import.
modify Element that defines the market and locale to perform import operations on.
Required element.
market
Details
A market key. Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-. The market key is used by all import methods.
Required attribute.
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. If a market have more than one language, that market must be split into two separate markets in eSales for Fashion. The locale is used by the full and partial import methods.
Required attribute.

Fashion attribute modification

The fashion attribute modification import does not use any import operations. All actions are determined by the root element fashion_attribute_modification in the import XML file.

All objects that are to be modified, such as product_groups, product, and variant, are identified by their key attribute values.

<fashion_attribute_modification> 
    <!-- Used to modify items. --> 
</fashion_attribute_modification>

Modify

The modify_attributes element is used by the attribute modification import. It defines what existing market that content will be operated on. Attribute modification

Multiple markets can be modified at the same time in an import, but a market can only be modified once during the same import.

<modify_attributes market="UK">
    <!-- Product groups for the market UK -->
</modify_attributes>

Elements and attributes

Name Description
modify_attributes Element that defines the market to perform updates on.
Required element.
market
Details
A market key. Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-. The market key is used by all import methods.
Required attribute.

Import examples

Full import

The full import sets the complete state of the data, thus anything that is not declared in here will be deleted from eSales.

This enables a retailer to do a full synchronisation between their systems and eSales.

The following example will add items to a site with market set to UK and locale set to en-GB. If the market already exists, any previous product groups and content links are deleted and replaced with the new data.

Full import example
<?xml version="1.0" encoding="UTF-8" ?>
<fashion_data_import type="full">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <add_or_replace>
                <product_group key="123">
                    <brand>Apparel</brand>
                    <department>Men</department>
                    <size_type>Men's Clothing</size_type>
                    <products>
                        <product key="123-B">
                            <title>Linen T-shirt</title>
                            <release_date>2017-10-27T11:16:07Z</release_date>
                            <url>/products?product_key=123-B</url>
                            <pattern>Striped</pattern>
                            <description>Loose-fit T-shirt with a slightly lower neckline.</description>
                            <additional_autocomplete_phrases>T-Shirts|Brown T-Shirts</additional_autocomplete_phrases>
                            <images>
                                <image type="model">
                                    <url resolution="card">//site.com/images/123-B_model.jpg</url>
                                    <url resolution="thumbnail">//site.com/images/123-B_model_thumbnail.jpg</url>
                                </image>
                                <image type="cutout">
                                    <url resolution="card">//site.com/images/123-B_cutout.jpg</url>
                                    <url resolution="thumbnail">//site.com/images/123-B_cutout_thumbnail.jpg</url>
                                </image>
                            </images>
                            <rating>4.3</rating>
                            <!-- Example of custom used-defined attributes -->
                            <custom_attributes>
                                <season>Summer</season>
                                <style>Casual</style>
                                <category>T-Shirts</category>
                            </custom_attributes>
                            <variants>
                                <variant key="123-B-S">
                                    <sizes>
                                        <size format="SML">S</size>
                                        <size custom_format="US">6</size>
                                    </sizes>
                                    <stock_number>27</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/variant?variant_key=123-B-S</url>
                                </variant>
                                <variant key="123-B-M">
                                    <sizes>
                                        <size format="SML">M</size>
                                        <size custom_format="US">8</size>
                                    </sizes>
                                    <stock_number>0</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/variant?variant_key=123-B-M</url>
                                </variant>
                            </variants>
                        </product>
                    </products>
                </product_group>
            </add_or_replace>
        </product_groups>
        <content_links> 
            <add_or_replace>
                <content_link key="871">
                    <title>Shipping</title>
                    <url>/uk/customer-service/shipping</url>
                </content_link>
                <content_link key="872">
                    <title>Contact</title>
                    <url>/uk/contact</url>
                </content_link>
            </add_or_replace>
        </content_links>
    </modify>
</fashion_data_import>

Partial import

Partial imports have the type attribute set to partial. This means that no data is removed at the beginning of the import.

The following example of a partial import that will add or replace one or more product groups, products, variants and content links in an existing market with the key UK. The items are identified using their key-values.

Partial import example with add or replace
<?xml version="1.0" encoding="UTF-8" ?>
<fashion_data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <add_or_replace>
                <product_group key="123"> 
                    <!-- attributes omitted for brevity -->
                    <products>
                        <product key="123-B"> 
                            <!-- attributes omitted for brevity -->
                            <variants>
                                <variant key="123-B-S"> 
                                    <!-- attributes omitted for brevity -->
                                </variant>
                            </variants>
                        </product>
                    </products>
                </product_group>
                <product_group key="124"> 
                    <!-- ... --> 
                </product_group>
            </add_or_replace>
        </product_groups>
        <content_links>
            <add_or_replace>
                <content_link key="871"> 
                    <!-- attributes omitted for brevity -->
                </content_link>
            </add_or_replace>
        </content_links>
    </modify>
</fashion_data_import>

The following example of a partial import will remove all product groups and content links from an existing market with the key UK.

Partial import example with remove all
<?xml version="1.0" encoding="UTF-8" ?>
<fashion_data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove_all/>
        </product_groups>
        <content_links>
            <remove_all/>
        </content_links>
    </modify>
</fashion_data_import>

The following example of a partial import will remove a specific product_group and content_link 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" ?>
<fashion_data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove>
                <!-- Removes product group with key = 123 from market UK-->
                <product_group key="123"/>
            </remove>
        </product_groups>
        <content_links>
            <remove>
                <!-- Removes content link with key 984 from market UK -->
                <content_link key="984"/>
            </remove>
        </content_links>
    </modify>
</fashion_data_import>

Attribute modification

Attribute modifications use a different root element, so they cannot be mixed with other types of imports. 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, and a variant 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" ?>
<fashion_attribute_modification>
    <modify_attributes market="UK">
        <product_groups>
            <!-- Update product group with key 123, 
            changing only its brand and leaving everything else untouched -->
            <product_group key="123">
                <brand>Armani</brand>
            </product_group>
        </product_groups>
        <products>
            <!-- Update product with key 123-B, 
            changing only its title and its custom attribute season -->
            <product key="123-B">
                <title>Brown Linen T-shirt</title>
                <custom_attributes>
                    <season>Winter</season>
                </custom_attributes>
            </product>
        </products>
        <variants>
            <!-- Update variant with key 00123-B-S, 
            changing only its stock_number and selling_price -->
            <variant key="123-B-S">
                <stock_number>20</stock_number>
                <selling_price>8.99</selling_price>
                <list_price>8.99</list_price>
            </variant>
        </variants>
    </modify_attributes>
</fashion_attribute_modification>
×