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
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`. Type restrictions: This attribute can contain a maximum of 20 values.
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. Type restrictions: This attribute can contain a maximum of 100 values.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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. Type restrictions: This attribute can contain a maximum of 20 values.
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` Type restrictions: This attribute can contain a maximum of 20 values.
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. Type restrictions: This attribute can contain a maximum of 20 values.
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`. Type restrictions: This attribute can contain a maximum of 20 values.	`["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. Type restrictions: This attribute can contain a maximum of 20 values.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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. Attribute names must be xml compliant.
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"`