Skip to content

Data Entity Types

A data entity type can be defined as an object with certain properties, a key and value map. There are three main data entity types in Apptus eSales: product, category, and ad.

The data entities are derived from a retailer's own systems, such as PIM, CMS, CRM, and ERP, and transformed by the retailer (or an implementing partner) into eSales compatible XML and imported into eSales with the RESTful API.

Each entity type have user-defined and configurable attributes. The attributes are based on a retailer's data model. The data model can be considered as the design specification for the XML, and lays the groundwork to a successful eSales integration.

A general recommendation is that all data that can be used in eSales such as attributes for sort, search, presentation, facets, and so on should be used in eSales. This includes copy such as product descriptions from a CMS and price data from a PIM.

Product

A product is the main data entity in Apptus eSales. Together with variants, it is how content is mainly represented in Apptus eSales and hold all necessary information of an actual product. Products can have variants and be a part of one or several categories.

Variants are items that represent a product but due to different characteristics, or business reasons, must be accounted for separately. Variants can be placed in two different ways in a data model. Either the variant is nested inside the product or it is a stand-alone entity that has a product key link that connects it to its parent product.

Reserved product attributes

The following product attributes are reserved in Apptus eSales:

product_key, relevance_class, relevance, sales, rank, locale, abandoned_timestamp, viewed_timestamp, bought_timestamp, proportion, rating, clicks, explanation, revenue, personal

Mandatory product and variant attributes

The following product attributes are mandatory:

product_key

The following variant attributes are mandatory:

variant_key

product_key (if the variant is a stand-alone entity and not nested in a product)

Recommended product attributes

The following product attributes are recommended to use:

locale

market

Attribute restrictions

User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.

A product or variant key may not contain any whitespace characters or commas, ,.

XML structure examples

The following examples showcase how different types of products and data models result in different XML structures.

Fashion/apparel/lifestyle product example
...
<product>
    <product_key>1234567-1</product_key>
    <title>Free Run 2</title>
    <url>/products/1234567</url>
    <has_image>true</has_image>
    <image_url>/images/products/1234567-1.jpg</image_url>
    <price>99.00</price>
    <market>UK</market>
    <locale>en-GB</locale>
    <release_date>2017-03-10</release_date>
    <section>men-shoes-running-shoes</section>
    <brand>Nike</brand>
    <colour>Black</colour>
    <variants>
        <variant>
            <variant_key>1234567-1-42</variant_key>
            <size>42</size>
            <in_stock>true</in_stock>
        </variant>
        <variant>
            <variant_key>1234567-1-43</variant_key>
            <size>43</size>
            <in_stock>true</in_stock>
        </variant>
    </variants>
</product>
<product>
    <product_key>1234567-2</product_key>
    <title>Free Run 2</title>
    <url>/products/1234567/2</url>
    <has_image>true</has_image>
    <image_url>/images/products/1234567-2.jpg</image_url>
    <price>99.00</price>
    <market>UK</market>
    <locale>en-GB</locale>
    <release_date>2017-03-10</release_date>
    <section>men-shoes-running-shoes</section>
    <brand>Nike</brand>
    <colour>White</colour>
    <variants>
        <variant>
            <variant_key>1234567-2-42</variant_key>
            <size>42</size>
            <in_stock>false</in_stock>
        </variant>
        <variant>
            <variant_key>1234567-2-43</variant_key>
            <size>43</size>
            <in_stock>true</in_stock>
        </variant>
    </variants>
</product>
...
Books/media/technology product example
...
<product>
    <product_key>42037246</product_key>
    <title>Ruins</title>
    <artist>First Aid Kit</artist>
    <category>music</category>
    <url>/music/42037246</url>
    <has_image>true</has_image>
    <image_url>/images/music/42037246.jpg</image_url>
    <market>UK</market>
    <locale>en-GB</locale>
    <release_date>2018-01-19</release_date>
    <category_slug>new-releases</category_slug>
    <media>CD</media>
    <price>15.00</price>
    <description>The Swedish folk duo’s fourth album is a showcase for their sweet harmonies, with some bold stylistic departures.</description>
    <in_stock>true</in_stock>
    <label>Columbia</label>
    <distributor>SME</distributor>
    <ean>0190758060125</ean>
    <tracks>&lt;track&gt;Rebel Heart&lt;/track&gt;&lt;track&gt;It's a Shame&lt;/track&gt;&lt;track&gt;Fireworks&lt;/track&gt;&lt;track&gt;Postcard&lt;/track&gt;&lt;track&gt;To Live a life&lt;/track&gt;&lt;track&gt;My Wild Sweet Love&lt;/track&gt;&lt;track&gt;Distant Star&lt;/track&gt;&lt;track&gt;Ruins&lt;/track&gt;&lt;track&gt;Hem of Her Dress&lt;/track&gt;&lt;track&gt;Nothing Has to Be True&lt;/track&gt;</tracks>
</product>
...
Furniture/home improvement product example
...
<product>
    <product_key>D55012505</product_key>
    <title>Work desk Basic</title>
    <category>desks</category>
    <url>/products/D55012505/</url>
    <market>UK</market>
    <locale>en-GB</locale>
    <width>120</width>
    <depth>80</depth>
    <min_height>65</min_height>
    <max_height>125</max_height>
    <max_load>100</max_load>
    <description>Versatile desk available in several materials and colours.</description>
    <variants>
        <variant>
            <variant_key>D55012505-white-birch</variant_key>
            <article_no>D55012505-1-1</article_no>
            <url_addon>#/white-birch/</url_addon>
            <colour>White</colour>
            <material>Birch veneer</material>
            <motorized>false</motorized>
            <price>120.00</price>
            <in_stock>true</in_stock>
            <has_image>true</has_image>
            <image_url>/images/products/D55012505-white-birch.jpg</image_url>
        </variant>
        <variant>
            <variant_key>D55012505-clear-acrylic-oak-veneer</variant_key>
            <article_no>D55012505-0-4</article_no>
            <url_addon>#/clear-acrylic-oak-veneer/</url_addon>
            <colour>Clear acrylic</colour>
            <material>Oak veneer</material>
            <motorized>true</motorized>
            <price>210.00</price>
            <in_stock>true</in_stock>
            <has_image>true</has_image>
            <image_url>/images/products/D55012505-clear-acrylic-oak-veneer.jpg</image_url>
        </variant>
    </variants>
</product>
...

Category

Categories are modelled as a tree structure that is defined during imports. There is always a root and all categories have an identifying parent category.

Categories and products are tightly coupled as a category contains products and a product is a part of one or more categories. This relationship is also defined during the imports.

The maximum number of category trees is 100 and a category tree has a max depth of 10 levels. A tree can hold maximum 10 000 categories and each category can hold up to 100 attributes.

Categories also support custom attributes to enable retrieval of images, links, or localised names directly from a result without multiple queries.

Reserved category attributes

The following category attributes are reserved in Apptus eSales:

key, relevance, product_count, selected, sales, personal, revenue, explanation

Mandatory category attributes

The following category attributes are mandatory:

key

parent

Recommended category attributes

The following category attributes are recommended to use:

display_name

locale

market

Attribute restrictions

User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.

A category key may not contain any whitespace characters or commas, ,.

XML structure examples

The following example showcase the XML structure of a basic category tree. The category tree attribute product_attribute="section" is used to connect to the category attribute of a product. The corresponding category key value men-shoes-running-shoes can be found in the Fashion/apparel/lifestyle product example.

Category example
...
<category_tree product_attribute="section">
    <category key="men-shoes-running-shoes" parent="men-shoes">
        <display_name>Running shoes</display_name>
        <market>UK</market>
        <locale>en-GB</locale>
        <attributes>
            <url>/categories/men-shoes-running-shoes</url>
            <department>Men</department>
        </attributes>         
    </category>
    <category key="men-shoes-tennis-shoes" parent="men-shoes">
        <display_name>Tennis shoes</display_name>
        <market>UK</market>
        <locale>en-GB</locale>
        <attributes>
            <url>/categories/men-shoes-tennis-shoes</url>
            <department>Men</department>
        </attributes>
    </category>
</category_tree>
...

Ads are a way of managing banners and campaigns on a site that already has a completed Apptus eSales integration. There are two types of ads: static ads and live ads. A static ad show a fixed image and a live ad includes a number of products in the ad. The type of ad is determined by the value of the live_products attribute of the ad.

Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalised if possible.

Reserved ad attributes

The following ad attributes are reserved in Apptus eSales:

ad_key, rank, locale, products, related, included, explanation

Mandatory ad attributes

The following ad attributes are mandatory:

ad_key

Recommended ad attributes

The following ad attributes are recommended to use:

locale

market

Attribute restrictions

User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.

An ad key may not contain any whitespace characters or commas, ,.

XML structure examples

Ad example
...
<ad>
    <ad_key>ad2018011420180214</ad_key>
    <start_time>2018-01-14T08:00:00+01:00</start_time>
    <end_time>2018-02-15T24:00:00+01:00</end_time>
    <included>category:'cd' AND genre:'soul' AND genre:'rnb'</included>
    <related>category:'cd' AND genre:'jazz'</related>
    <title>Valentines day music offers</title>
    <market>UK</market>
    <locale>en-GB</locale>
    <tags>cd,music</tags>
    <live_products>3</live_products>
    <campaign_key>valentines2018</campaign_key>
    <campaign_url>/campaigns/valentines-2018/music/</campaign_url>
    <format>fullwidth</format>
    <image_url>/images/ads/ad2018011420180214.jpg</image_url>
    <ad_category>frontpage</ad_category>
</ad>
...

Synonym

A new data format for managing synonyms is introduced with the Web API v2. Synonyms are used to extend searches of a phrase to include similar search phrases.

A synonym includes a locale, one search phrase, and one synonym phrase that will be used together with the search phrase. If the synonym is valid for all locales (worldwide), the value global should be used.

Reserved synonym attributes

The following synonym attributes are reserved in Apptus eSales:

locale, search_phrase, synonym_phrase

Data type availability

The synonym data entity type format is available with the Web API v2 only.

XML structure examples

Synonym example
...
<synonym>
    <locale>en-GB</locale>
    <search_phrase>Shoes</search_phrase>
    <synonym_phrase>Boots</synonym_phrase>
</synonym>
<synonym>
    <locale>en-GB</locale>
    <search_phrase>Shoes</search_phrase>
    <synonym_phrase>Sneakers</synonym_phrase>
</synonym>
...
×