Skip to content
×
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

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 Fashion. The data feed is an XML-file encoded using UTF-8.

Basic file syntax 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="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>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                </image>
                                <image>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=200x200</url>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=600x600</url>
                                </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_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>
Advanced file syntax 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="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" tags="Hero">
                                    <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>
                                </image>
                                <image type_override="cutout">
                                    <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>
                                </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>blue|white</color_default>
                            <color_override>blue|white</color_override>
                        </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>

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 Description
key The key of this product group, must be unique within all key attributes for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required
brand The brand appears in the product card. It is searchable and visible as an autocomplete phrase. This supports faceting and search.
Required
department Element used to filter on department. This supports faceting and search.
Required
products
Details
Group element for products. Requires at least one product.
Required element for Fashion data import.
Not allowed for Fashion attribute modification.
size_type 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 Description
key The key of this product, must be unique within all key attributes for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required
title The title of the product. Searchable and shown in product cards, and completions.
Required
url The URL to the product page with this colour/style preselected. Must be relative to page root, i.e. start with /. Relative path example: /products/1001-100
Required
variants
Details
Group element for variants. Requires at least one variant.
Required element for Fashion data import.
Not allowed for Fashion attribute modification.
release_date Used for ranking and adding badges to new items and for sorting by newest first. The time is in the ISO 8601 format, including offset.
Recommended
description 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
Details
Group element for images. Requires at least one image if present.
Recommended
custom_attributes
Details
Group element for custom user-defined attributes. These supports faceting and search. Custom attributes are selected for use as facets in the Experience app. Supports multiple pipe-separated (|) values. Maximum length of custom element names is 2 000 characters.
Recommended
pattern The pattern of the product such as Dotted or Striped. This supports faceting and search. Supports multiple pipe-separated (|) values.
rating A product rating from 0.0 to 5.0. Enables ratings in product cards.
For more information about ratings, see Additional Features
color_default The default colour of the product, used until automatic colour analysis can be performed. Valid values are: colours in hex (e.g. #ffffff), Gold, Silver, or Multi. Supports multiple pipe-separated (|) values. Recommended for products with metallic properties.
For more information about colour analysis, see Image and Data Analysis.
color_override An override of the product colour, used to override the colour analysis and the color_default attribute. Valid values are: colours in hex (e.g. #ffffff), Gold, Silver, or Multi. Supports multiple pipe-separated (|) values.
For more information about colour analysis, see Image and Data Analysis.

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

<images>
    <image>
        <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
        <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
    </image>
    <image>
        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout_thumbnail.jpg</url>
        <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg</url>
    </image>
</images>
Elements and attributes
Name Description
image A group element for the url elements of one image.
Required
url The URL to the image. Multiple url elements containing different resolutions of the same product image may be provided for optimal performance. 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
Required
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. For more information, see Image and Data Analysis.

<images>
    <image type_default="model" tags="Hero">
        <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>
    </image>
    <image type_override="cutout">
        <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>
    </image>
</images>
Elements and attributes
Name Description
tags Attribute of image that allows custom tagging of images. Required to enable image prioritisation using custom tags. Supports multiple pipe-separated (|) values.
width Attribute of url that specifies the pixel width of the target image. Must be a positive integer. Used until automatic image analysis can be performed.
For more information about image analysis, see Image and Data Analysis.
type_default Attribute of image describing the type of image, used until automatic image analysis can be performed. Can be either model, cutout, or `misc.
For more information about image analysis, see Image and Data Analysis.
type_override Attribute of image overriding the analysed image type. Can be either model, cutout, or misc.
For more information about image analysis, see Image and Data Analysis.
type Replaced by type_default.
Deprecated
resolution Replaced by width.
Deprecated

Custom attributes

Custom attributes can have an additional name attribute if the identifier is not human friendly.

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

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

Variant

A variant is a SKU (stock-keeping-unit) and contains attributes that are specific to the SKU.

<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>XS</size>
    </sizes>
</variant>

Elements and attributes

Name Description
key The key of the variant element, must be unique within all key attributes for the market. Maximum length is 200 characters and allowed characters are A-Z, a-z, 0-9, and /_-.
Required
stock_number Number of items in stock, used in ranking and marking the variant as out-of-stock.
Required
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
list_price The price displayed in the shop as the standard price. Must be greater than or equal to the selling_price.
Required
cost 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
url The URL to the product page with this size preselected. Enables more specific link targets in product listings. Must be relative to page root, i.e. start with /.
Relative path: /variant?variant_key=123-B-S.
Recommended
sizes
Details
A group element for the size element of this variant. Requires at least one size if present. Should only be omitted for products without useful sizes.
Recommended
size The actual size of a variant in a specific format. Required if sizes is present.
custom_prices
Details
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.

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. Multiple variants with the same format and value are not allowed.

<sizes>
    <size custom_format="SML">S</size>
    <size custom_format="EU">36</size>
</sizes>
Elements and attributes
Name Description
custom_format 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 Description
price Contains selling_price and list_price for a specific id.
Required
id 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 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
list_price The price displayed in the shop as the standard price. Must be greater than or equal to the selling_price.
Required

Content links enable visitors to find editorial content on the site, such as shipping and contact information. Content links are usually placed after the product groups in the import files.

<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
title Title to be displayed as text completion.
Required
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.
Relative path: /uk/customer-service/shipping
Absolute path: //cdn.esalesdrivensite.com/uk/customer-service/shipping
Required

Markets

Products, variants, content links, 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 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. Only attributes defined in the import will be modified.

For more information on when to use full, partial, or attribute modifications imports, see Continuous product feed.

Fashion data import

The fashion 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 fashion_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_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

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 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
market
Details
A market key. Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-.
Required
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

Fashion attribute modification

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

The modify_attributes element is used by the Fashion 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 links are modified separately when performing a Fashion attribute modification.

<fashion_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>
    </modify_attributes>
</fashion_attribute_modification>

Elements and attributes

Name Description
modify_attributes Element that defines the market to perform updates on.
Required
market
Details
A market key. Maximum length is 40 characters and allowed characters are A-Z, a-z, 0-9, and _-.
Required
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.

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" ?>
<fashion_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>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=200x200</url>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_model.jpg?preset=600x600</url>
                                </image>
                                <image>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=200x200</url>
                                    <url>//cdn.esalesdrivensite.com/images/1001-100_cutout.jpg?preset=600x600</url>
                                </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_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>
Full import example with advanced feature usage
<?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="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" tags="Hero">
                                    <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>
                                </image>
                                <image type_override="cutout">
                                    <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>
                                </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>blue|white</color_default>
                            <color_override>blue|white</color_override>
                        </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

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="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_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 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 = 1002 from market UK-->
                <product_group key="1002"/>
            </remove>
        </product_groups>
        <content_links>
            <remove>
                <!-- Removes content link with key 984 from market UK -->
                <content_link key="873"/>
            </remove>
        </content_links>
    </modify>
</fashion_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, 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 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>
    </modify_attributes>
</fashion_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" ?>
<fashion_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>
</fashion_attribute_modification>

Last update: April 30, 2020