Skip to content

Catalog

https://{cluster-id}.api.esales.apptus.cloud/api/admin/v4/export/catalog

GET

An export of the product data in Elevate 4 can be done using the standard HTTP GET method, with personal cluster credentials provided during onboarding.

Request

Header parameters

Name Description Example
Api-Key
Required
Api-key that was supplied during on-boarding pkA123456789AB1BE..
Accept-Encoding Allows responses to be compressed using Gzip. gzip

Query parameters

Name Description Example
limit Optional limit of how many items of each type to return
productGroupKeys Optional set of keys to limit which product groups should be included. At most 100 keys can be picked. If not included, all product groups will be exported.
types Optional limit of which data types to return. Valid values are 'PRODUCT_GROUPS', 'CONTENT', 'TRANSLATIONS' Supported values: PRODUCT_GROUPS, CONTENT, TRANSLATIONS.
curl -i \
-X GET \
-H 'Api-Key: pkA123456789AB1BE..' \
-H 'Accept-Encoding: gzip' \
"https://{cluster-id}.api.esales.apptus.cloud/api/admin/v4/export/catalog?limit=limit&productGroupKeys=productGroupKeys&types=types"

Response

Response codes

Status Description
200 Query accepted. The data will be returned as an application/jsonlines.
403 Incorrect cluster credentials.
404 Cluster not found.
405 The export is not allowed due to incomplete upgrade. Perform a full v4 catalog import to upgrade.
500 Server error such as cluster unavailable, busy or internal error. If 5xx errors persist, contact support and attach any information found in the response body.
503 The server in the cluster that received the request is currently unavailable or busy. It is recommended to retry the request. The time between request attempts should be increasing.

Response body

Example
application/jsonlines
{
  "replace" : {
    "content" : {
      "defaults" : {
        "customLabels" : { },
        "dataLocale" : "en-GB",
        "description" : null,
        "releaseDate" : null,
        "title" : null,
        "url" : null
      },
      "image" : {
        "defaults" : {
          "alt" : null,
          "caption" : null,
          "customData" : { },
          "tags" : [ null ],
          "urls" : [ {
            "url" : null,
            "widthInitial" : 0
          } ]
        },
        "limitedLocales" : [ null ],
        "limitedMarkets" : [ null ],
        "order" : 1,
        "overrides" : { },
        "typeInitial" : null,
        "typeOverride" : null
      },
      "limitedLocales" : [ null ],
      "markets" : [ "sv-SE" ],
      "overrides" : { },
      "type" : null
    },
    "key" : "pg1",
    "productGroup" : {
      "products" : { },
      "suppressDuplicates" : true
    },
    "translation" : {
      "attribute" : "customLabels.season",
      "id" : "S2",
      "locale" : "en-GB",
      "value" : "Summer"
    }
  }
}
Schema

OpenApiCatalogImportPutBodyExampleSchema

Name Type Description Example
replace Replace Add or replace an entity in the catalog. "{ "replace": { "key": "pg1", "productGroup": {...} } }n{ "replace": { "key": "c1", "content": {...} } }n{ "replace": { "key": "t1", "translation": {...} } }n"

Schemas

Inner schemas

Content

The definition of a single piece of content, such as an FAQ, shipping, or contact information. Usually placed after product groups in the import files.

Name Type Description Example
defaults ContentData Default content data. See defaults and overrides.
A default title and url is mandatory for new content.
image Image One image representing the content.
limitedLocales string[] A subset of the market's supported locales. Useful if the content lacks translations for all locales.
markets string[] Which markets this content should be available in. Required to contain at least one market. ["sv-SE"]
overrides <string, ContentData> Data overrides for specific markets/locales. See defaults and overrides
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.

ContentData

Name Type Description Example
customLabels <string, string[]> Group element for custom user-defined attributes. These support 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.
dataLocale string The locale of the data provided, used as a hint to improve Elevate's product analysis. This may be different from the actual locale, e.g. if English is used in the Italian market. "en-GB"
description string The description of the content. Used for search but valued less than other attributes when evaluating a match.
releaseDate string Used for sorting by newest first.

Type restrictions:
Time is in the ISO 8601 format. The only accepted decimal separator is a dot, ., and it is only allowed after seconds. The minimum required precision is a day but it is recommended to set it as precise as possible.
title string The title of the content item. A default title is required on all content.
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.example.com/uk/customer-service/shipping

A default url is required on all content.

Image

Name Type Description Example
defaults ImageData Default image data used if no overrides exists for the current market/locale. See defaults and overrides
limitedLocales string[] If included, the image will only be returned on selected locales. Useful if the image contains text.
limitedMarkets string[] If included, the image will only be returned on selected markets. Useful if laws in some markets disallow the use of the image.
order integer An override of the image order when listing images within the parent entity or for Elevate apps merchandising purposes. The position is evaluated by the order value in ascending order and defaults to order of appearance in the parent entity. 1
overrides <string, ImageData> Data overrides for specific markets and/or locales. See defaults and overrides
typeInitial string Element 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.
typeOverride string Override of the analyzed 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.

ImageData

Name Type Description Example
alt string The alt text of the image. The alt text should describe the image. Always returned along with the image.
caption string the caption for the image, only returned on the product page (or content information for content).
customData <string, string> Group element for custom user-defined attributes which are 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 (_).
tags string[] Allows custom tagging of images for image prioritization in the product cards set in the Elevate apps. Not allowed on a content image.
urls UrlMeta[] A group element for the url elements of one image. Multiple url elements containing different resolutions of the same product image may be provided for optimal performance. Required

Length

Name Type Description Example
amount number The measured value 58
unit string The unit the attribute is measured in "cm"

Price

Name Type Description Example
listPrice number The standard price.
Required

Type restrictions:
Must be a decimal number, greater than or equal to the selling_price.
sellingPrice number The price that the customer pays. When the variant is on sale, the selling_price is lower than the list_price.
Required

Type restrictions:
Must be a decimal number, less than or equal to the list_price.

Product

Defines a visually distinct product within a product group. Must have at least one variant and is strongly recommended to have at least one image.

Name Type Description Example
colorInitial string[] The default color of the product, used until automatic color analysis can be performed. Recommended for products with metallic properties. For more information about color analysis, see Image and data analysis. Supports multiple values.

Type restrictions:
Valid color codes are provided as hex, e.g. #ffffff. Additional valid values are Gold, Silver, or Multi.
"FF0000"
colorOverride string[] An override of the product color, used to override the color analysis and the colorInitial attribute. "FF0000"
defaults ProductData All default product data. For more information, see defaults and overrides. Required on new products.
images <string, Image> A mapping from image key to image. Image keys may be repeated within different products and can be used to access specific images in edit operations. Recommended
markets string[] Which markets this product should be visible on. Required to contain at least one market. ["sv-SE"]
overrides <string, ProductData> Data overrides for specific markets and/or locales. See defaults and overrides.
variants <string, Variant> A mapping from variant key to variant. Required to contain at least one variant.

ProductData

A collection of overridable attributes for a specific product, see defaults and overrides. A product must have a default title and url.

Name Type Description Example
age string[] The age of the product's target audience in text. Used by Elevate to improve relevance. Numeric values should be followed by a unit of time, like years. If no unit is specified Elevate will assume that the value is in years.Examples: children, teenager, or 1-3 years.
brand string The brand of the product group e.g. Calvin Klein or Bosch. It is searchable, used as an autocomplete phrase, and supports faceting. Recommended "Bosch"
category string[] The category of the product. Recommended to be used to define pages in the apps, and is used by Elevate to better understand the product if no ontology property was supplied.

Use the greater than symbol (>) to specify hierarchy if this information is available, e.g. Clothing > Trousers > Chinos. Spaces are optional but should be consistent.
Supports translations.
For more information about categories, see Categories.
customJson <string, object> Group element for custom user-defined json attributes. Can be used to define custom purely presentational information, that's unsuitable for search, filters etc.
Be mindful that having multiple large json objects will affect response times.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
customLabels <string, string[]> Group element for custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app.
Recommended

Supports translations.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
customLengths <string, Length> Group element for custom user-defined length attributes. Can be used to define secondary measurement attributes, such as the package size.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
customNumbers <string, number> Group element for custom user-defined number attributes. These support faceting and filtering. Custom attributes are selected for use as facets in the Settings tab in the Experience app.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
dataLocale string The locale of the data provided, used as a hint to improve Elevate's product analysis. This may be different from the actual locale, e.g. if English is used in the Italian market. "en-GB"
department string[] Element used to filter on department. This supports faceting and search.
depth Length The depth of the product, e.g. depth of a moving box. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!
description string The description of the product, used for automatic data extraction. The description is not directly searchable by default. To enable search hits in the description element, contact Voyado Support. Recommended
gender string[] The gender of the product's target audience. Used by Elevate to improve relevance. Examples: ladies, women, men, unisex
height Length The height of the product, e.g. height of a miniature statue. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!
length Length The length of the product, e.g. length of a wire-lock. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!
name string The product's name, if any. These are generally proper names given to products by the vendor. They are often identical to the series name. If the product doesn't have a name, this attribute should be omitted. The name should not be confused with title or brand.
Examples: iPhone, Corolla, KALLAX.
"iPhone"
ontology string The ontological category of the product. Used exclusively to help Elevate understand the product type.
Recommended

Use the greater than symbol (>) to specify hierarchy if this information is available, e.g. Clothing > Trousers > Chinos. Spaces are optional but should be consistent.

This can be similar to the site's navigation structure, but it is important to only include actual product types in the field. Power tools > Drills > Drill bits is a valid example, while Men > Sale > Jackets or Outdoors > Garden > Hammocks should be avoided.
For more information, see Categories.
pattern string[] The pattern of the product, such as Dotted or Striped. This supports faceting and search.
productType string[] The type of product, used as a strong hint to the automatic product type analysis. Typically not necessary but may be helpful if the product type is not obvious from the data, for example if the product title includes other product types.Another scenario when productType is recommended is when the product is a bundle rather than a single product and has multiple different product types.Examples: t-shirt, potato peeler, tent pole. Values should be specific product types, i.e. neither wider categories such as tools or clothing, nor combined product types, such as t-shirts/tops or beds & mattresses. ["hoodie"]
rating number 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.
releaseDate string Used for ranking and adding badges to new items and for sorting by newest first.
Recommended

Type restrictions:
Time is in the ISO 8601 format. The only accepted decimal separator is a dot, ., and it is only allowed after seconds. The minimum required precision is a day but it is recommended to set it as precise as possible.
series string The name of the series that this product belongs to, if any. This is mainly used for recommendations and is a recommended attribute to use as it facilitates the use of filters, improves site performance, and SEO.
Examples: iPhone 15, Air Jordan.
Recommended
Supports translations. We recommend using translations for series in order to allow different series to have the same name, yet not show up as recommendations to each other.

For more information on recommendations regarding the series attribute, see More from series.
"iPhone 15"
sizeType string Enables manually defined grouping of sizes in the size facet. Can be any value.
styleWith string[] A list of product keys for products that should appear in the Style with recommendation on a product page. There can be a maximum of 20 product keys.
title string The title of the product. Searchable and used as an autocomplete phrase. The title is usually displayed on the product card together with a brand and name to quickly describe the product to the visitor. Required on defaults. "Teddy-lined suede jacket"
url string The URL to the product page of this product. If a shared page is used for the product group, ensure that the correct style/color is preselected.

Type restrictions:
Must be relative to page root, i.e. start with /.
"/products/1001-100"
volume Volume The volume of the product, e.g. how much a shampoo bottle contains. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!
weight Weight The weight of the product, e.g. how heavy an item is. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!
width Length The width of the product, e.g. width of a book shelf. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both!

ProductGroup

The definition of a single product group that may contain multiple products

Name Type Description Example
products <string, Product> A mapping of product keys to product definitions. A group must contain at least one product
suppressDuplicates boolean If true, this product group will only show up once in a product listing (as opposed to each product in the group having its own entry). Useful for visually similar product groups. Default is false.

Replace

An operation to add or replace an entity in the catalog. Each entry must provide a key and exactly one of productGroup, content or translation.

Name Type Description Example
content Content The definition of a single piece of content, such as an FAQ, shipping, or contact information. Usually placed after product groups in the import files.
key string The key of the object to replace in the catalog "pg1"
productGroup ProductGroup The definition of a single product group that may contain multiple products
translation Translation A translation of an attribute value for a specific locale. See translations.

Translation

A translation of an attribute value for a specific locale. See translations.

Name Type Description Example
attribute string The attribute for which the translation applies to. Either category, age, gender or a custom label. "customLabels.season"
id string The attribute id for which the translation value applies to. Should be a stable id. "S2"
locale string The locale the translation applies to. "en-GB"
value string The value of the translation for the provided id, attribute and locale. "Summer"

UrlMeta

Name Type Description Example
url string The URL to the image.
Required

Type restrictions:
URL:s must be absolute and start with http://, https://, or //. Using // is good practice, as it will use the same scheme as the site.
Absolute path: //cdn.example.com/images/1001-100_cutout.jpg
widthInitial integer 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.

Variant

Defines a stock-keeping-unit (SKU) and contains attributes that are specific to the SKU. A variant typically represents a single physical size.

Name Type Description Example
defaults VariantData Default variant data. See defaults and overrides
overrides <string, VariantData> Data overrides for specific markets/locales. See defaults and overrides

VariantData

Name Type Description Example
cost number The cost of the product. Can also be provided in payment notifications, in which case the notification cost has precedence. Used for reports and is required for utilizing profit-optimizing algorithms. Never sent client side.
Recommended
customJson <string, object> Group element for custom user-defined json attributes. Can be used to define custom purely presentational information, that's unsuitable for search, filters etc.
Be mindful that having multiple large json objects will affect response times.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
customLabels <string, string[]> Group element for custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the Settings tab in the Experience app.
It is recommended to use custom attributes on product level whenever applicable, and only use variant level custom attributes when required.

Supports translations.

Type restrictions:
Maximum number of custom attributes per variant is 20.
Maximum number of unique custom attributes on variants across a market-locale combination is 1 000.
Maximum length of custom element names is 2 000 characters.
customLengths <string, Length> Group element for custom user-defined length attributes. Can be used to define secondary measurement attributes, such as the package size.
customNumbers <string, number> Group element for custom user-defined number attributes.These support faceting and filtering. Custom attributes are selected for use as facets in the Settings tab in the Experience app.
It is recommended to use custom attributes on product level whenever applicable, and only use variant level custom attributes when required.

Type restrictions:
Maximum length of custom element names is 2 000 characters.
customPrices <string, Price> 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.
dataLocale string The locale of the data provided, used as a hint to improve Elevate's product analysis. This may be different from the actual locale, e.g. if English is used in the Italian market. "en-GB"
depth Length The depth of the variant, e.g. depth of a moving box. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.
height Length The height of the variant, e.g. height of a miniature statue. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.
label string The title of the variant. Used to represent the variant from the product page. Defaults to a size if not supplied. Useful if sizes are not being used or there are multiple size formats available and there is a specific size format or a size format combination that should be shown. E.g. on a shoe with size 40 in EU and size 7 in US, the label could be "40 (US 7)" or "40".
Do not use label or sizes if there is only one variant per product.

Conditionally required
Required under the following circumstances:
* The product has more than one variant.
* size is not used.
* sizeFormats is not used.
40
length Length The length of the variant, e.g. length of a wire-lock. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.
listPrice number The standard price.
Required

Type restrictions:
Must be a decimal number, greater than or equal to the selling_price.
order integer An override of the variant's position within the parent Product response object. The position is evaluated by the order value in ascending order. Required on all variants within a product if used.
sellingPrice number The price that the customer pays. When the variant is on sale, the selling_price is lower than the list_price.
Required

Type restrictions:
Must be a decimal number, less than or equal to the list_price.
size string[] The size(s) of this variant, using the default size format. Requires at least one size if present.
Do not use label or sizes if there is only one variant per product. See also: Sizes - fraction handling

Conditionally required
Required under the following circumstances:
* The product has more than one variant.
* label is not used.
* sizeFormats is not used.
sizeFormats <string, string[]> The size(s) of this variant, using custom size format. Requires at least one size if present. At least one format must have a unique value for each variant.
Do not use label or sizes if there is only one variant per product. See also: Sizes - fraction handling

Conditionally required
Required under the following circumstances:
* The product has more than one variant.
* label is not used.
* size is not used.
stock integer Number of items in the online (default) stock, used in ranking and marking the variant as out-of-stock. Negative values are treated as 0. Required
storeStock <string, integer> A group element for store stock levels, containing a mapping of store id:s to store specific stock numbers.
Stock numbers are used in ranking and marking the variant as out-of-stock. Negative values are treated as 0.
For more information, see Store specific stock numbers.
url string The URL to the product page with this size preselected. Enables more specific link targets in product listings.
Recommended
volume Volume The volume of the variant, e.g. how much a shampoo bottle contains. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.
weight Weight The weight of the variant, e.g. how heavy an item is. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.
width Length The width of the variant, e.g. width of a book shelf. Supports faceting, search, and sorting. Can be included on either product or variant level, but not both! If included on variant level, all variants of the product must have it.

Volume

Name Type Description Example
amount number The measured value 58
unit string The unit the attribute is measured in "cm"

Weight

Name Type Description Example
amount number The measured value 58
unit string The unit the attribute is measured in "cm"
×
Copyright

This online publication is intellectual property of Voyado Lund AB. 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 Voyado Lund AB 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. Voyado Lund AB 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