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

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 pipe-separated (`\|`) values. Type restrictions: Valid color codes are provided as hex, e.g. `#ffffff`. Additional valid values are `Gold`, `Silver`, or `Multi`.
colorOverride	string[]	An override of the product color, used to override the color analysis and the color_default attribute.
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. Images are 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.

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.