Catalog entity format overview

The catalog consists of structured product data, content, and translations. This section provides a detailed overview of these entities as well as how to work with market- and locale-specific information.

Most models in this section are expanded as JSON for improved readability. When provided as part of imports, each operation, including all inner models, must be provided as a single JSON line.

Related articles

Guidance on working with catalog import files — catalog import overview.
Complete schemas and request requirements — import specification.
Contextualized, complete examples for common import scenarios — import examples.
Import strategies and scheduling — scheduled imports.

Product model

Items available for purchase are structured as product groups, which contain products, each with one or more variants.

Product group

The product group is the top level of the product model and represents a single article. It acts as a container for one product model with visible differences. The product group itself does not contain any attributes (apart from optional duplicate suppression).

ProductGroup

{
  "key": "1001",
  "productGroup": {
    "suppressDuplicates": "false",
    "products": {
      // As described in the product section
    }
  }
}

Each product group is identified by a unique key, which is referenced in any instruction that modifies the product group. Related schemas: ProductGroup.

Product

A product represents a specific variation within a product group and includes attributes that distinguish it from other products in the same group. These are typically visible characteristics such as color, pattern, material, or visible size-related aspects like mattress thickness, which help customers easily differentiate products in listings or search results. A good rule of thumb is that products within a group typically have their own images. Each product must contain at least one variant and should have at least one image.

Product

{
  "1001-100": {
    "markets": ["uk"],
    "colorInitial": ["#FF0000"],
    "defaults": {
      // Product data
    },
    "overrides": {
      "*|sv-SE": {
        // Product data
      }
    },
    "images": {
      // As described in the images section
    },
    "variants": {
      // As described in the variant section
    }
  }
}

Each product is identified by a unique key, which is referenced in the product group’s products map and in any instruction that modifies the product. Some attributes are provided directly on the product object, while most are defined in inner productData objects that can be supplied as defaults and overrides.

ProductData

{
  "url": "/products/1001-100",
  "title": "Louisa black coat",
  "ontology": "Clothing > Outerwear > Coats",
  "category": ["c1", "c2"],
  "brand": "Luis Vitton",
  "sizeType": "Clothing",
  "description": "A fine coat for any occasion",
  "releaseDate": "2023-06-20T00:00:00+02:00",
  "rating": 5,
  "customLabels": {
    // As described in the custom attributes section
  },
  "customLengths": {
    // As described in the custom attributes section
  }
}

In this example, two translation identifiers are provided in the category attribute. See translation for more information. Related schemas: Product, ProductData.

Images

An image object defines a single image and may include multiple URLs representing different resolutions of the same image. These variations help optimize bandwidth usage and are especially useful for thumbnails. Each image must include at least one URL.

Image

{
  "i1": {
    "typeInitial": "model",
    "defaults": {
      // Image data
    },
    "overrides": {
      "*|sv-SE": {
        // Image data
      }
    }
  }
}

ImageData

{
  "urls": [
    {
      "url": "//cdn.example.com/products/p1?preset=200x200",
      "widthInitial": 200
    },
    {
      "url": "//cdn.example.com/products/p1?preset=600x600",
      "widthInitial": 600
    }
  ],
  "caption": "The model is 176 cm tall and is wearing size S",
  "alt": "The model is 176 cm tall and is wearing size S",
  "tags": ["hero"],
  "customData": {
    "user": "u1",
    "type": "Instagram"
  }
}

Each image is identified by a combination of its parent product key and its own unique image key in the product’s images map and in any instruction that modifies the image. Some attributes are provided directly on the image object, while most are defined in inner imageData objects that can be supplied as defaults and overrides. Related schemas: Image, UrlMeta.

Variant

A variant represents a stock-keeping unit (SKU) and includes attributes specific to that SKU. It typically reflects a difference in physical size, but can also represent variations like memory capacity or other product-specific features.

Variant

{
  "1001-100-1": {
    "defaults": {
      // Variant data
    }
  },
  "overrides": {
    "se|*": {
      // Variant data
    }
  }
}

Each variant is identified by a unique key, which is referenced in the product’s variants map and in any instruction that modifies the variant. The variant attributes are defined in inner variantData objects that can be supplied as defaults and overrides.

VariantData

{
  "url": "/products/1001-100-1?size=S",
  "stock": 12,
  "sellingPrice": 129.0,
  "listPrice": 199.0,
  "cost": 55.0,
  "size": ["S"],
  "storeStock": {
    "stockholm": 23
  },
  "customLabels": {
    // As described in the custom attributes section
  }
}

Sizes

A single physical size can be expressed in several formats. For example, a shirt can be considered both a size S and sizes 34 and 36 simultaneously. If multiple formats are known, all should be provided using sizeFormats instead of size. Multiple variants with the same format and value are allowed, as long as there is one format with a unique single value.

sizeFormats

"sizeFormats": {
  "sml": ["S"],
  "eu": ["34", "36"]
}

Custom prices

Custom prices allow a single variant to have multiple prices. They are associated with price IDs, which must also be included when querying.

customPrices

"customPrices": {
  "VIP": {
    "sellingPrice": 99.0,
    "listPrice": 199.0
  }
}

Store stock

The default stock level defines the online stock availability, while storeStock allows a variant to have store specific stock information. Store specific stock levels are associated with store IDs, which must also be included when querying.

storeStock

"storeStock": {
  "stockholm": 23,
  "lund": 2
}

Related schemas: Variant, VariantData, Price. Related articles: Custom prices feature , Store specific stock.

Content

Content enables visitors to find editorial content items on a site, such as FAQs, shipping, and contact information.

Content

{
  "key": "842",
  "content": {
    "markets": ["se", "uk"],
    "type": "article",
    "defaults": {
      // Content data
    },
    "overrides": {
      "*|sv-SE": {
        // Content data
      },
      "se|*": {
        // Content data
      }
    },
    "image": {
      // As described in the images section
    }
  }
}

Each content item is identified by a unique key, which is referenced in any instruction that modifies the content. Some attributes are provided directly on the content object, while most are defined in inner contentData objects that can be supplied as defaults and overrides.

ContentData

{
  "url": "uk/articles/its-finally-sweater-season-2020-11-20/",
  "title": "It's finally sweater season",
  "releaseDate": "2023-08-20",
  "description": "Warm, comfortable, and stylish when it matters the most.",
  "customLabels": {
    "season": ["S1"]
  }
}

Related schemas: Content, ContentData, Image.

Translation

Translation is a separate entity that can be imported within a catalog feed. A translation is a mapping of an ID for a specific property to a localized value. Translations apply to all Product, Variant, and Content properties that match. Using IDs in filters and product selections with translations as a means to localize the presentational information ensures stable filters and product selections. This means that localized presentational values can be altered via translations, without changing filter definitions or product selections. Translations also enable stable cross-market and locale filters and product selections, meaning the same ID can be used in multiple markets while still having differently localized presentational values. If a property supporting translation lacks a translation for a locale, the ID itself will be used as the presentational value. Translation support is currently limited to the attributes category, age, gender, series, department, pattern, name, brand, and custom label attributes, for example customLabels.season.

Translation

{
  "translation": {
    "locale": "en-GB",
    "attribute": "customLabels.season",
    "id": "AUT",
    "value": "Autumn"
  }
}

When this translation is supplied, the value Autumn will be searchable and used for presentation by Elevate in the Apps as well as returned in queries using en-GB as locale for any matching catalog items. Related schemas: Translation.

Shared models

Custom attributes

Catalog items support several types of custom attributes. Each type offers specific features tailored to the kind of data it represents.

customLabels

Supports filters and facets, and works with translations. Useful for defining custom filtering or faceting options beyond standard attributes.

"customLabels": {
  "season": ["AUT"]
}

customLengths

Supports range queries and metric conversion. Can be used for secondary measurements, such as shipping size.

"customLengths": {
  "packageWidth": {
    "amount": 3.0,
    "unit": "dm"
  }
}

customNumbers

Supports numeric range queries. Useful for numeric attributes like the number of items in a package or other count-based values.

"customNumbers": {
  "pieces": 100.0
}

customJson

Supports raw JSON values. Useful for including flexible, presentational, or miscellaneous data that should be returned as-is in JSON responses.

"customJson": {
  "cardStyle": { "theme": "dark" }
}

customData

Handles non-facetable metadata. Used specifically for supplying additional data for image objects.

"customData": {
  "user": "u1",
  "type": "Instagram"
}

Refer to each item’s schema to see which custom attribute types it supports.

Predefined measurements

Predefined measurements like width, height, length, depth, weight, and volume share product and variant values in facets, product selections, and sorting. This means that there is a single facet for, for example, width that holds all width values regardless of whether they are provided at product or variant level. In catalog imports, each product must have its predefined measurements specified, either at the product level or the variant level. If measurements are provided at the variant level, then all variants of the product must include values for the relevant measurements. Each measurement consists of an amount and a unit, where valid units depend on the type of measurement. Related schemas: Length, Weight, Volume.

Markets and locales

Market identifiers and keys for product groups, products, and variants must be consistent across the catalog imports, the order notifications, and the order history. All keys are case sensitive.

Market availability for content and products is specified in the attribute markets. All variants that belong to a product will automatically become available on all the markets that the product is available on. A productGroup will be available for markets where at least one of its products is available, and will only include the products available for that market. All product data and content will be available on all locales that are supported by a market according to the configuration, unless explicitly limited. Note that only content and imagery support explicit locale limitations.

Example

Given the product group example below, requests to the following markets would yield the following results:

Market uk — Product group pg1, containing products p1 and p2
Market se — Product group pg1, containing product p2
Market us — No product groups

The variants p1-v1 and p1-v2 will always be returned when p1 is returned, and p2-v1 when p2 is returned.

Product group example

{
  "key": "pg1",
  "productGroup": {
    "products": {
      "p1": {
        "markets": ["uk"],
        "...": "omitted for brevity",
        "variants": {
          "p1-v1": {
            "...": "omitted for brevity"
          },
          "p1-v2": {
            "...": "omitted for brevity"
          }
        }
      },
      "p2": {
        "markets": ["uk", "se"],
        "...": "omitted for brevity",
        "variants": {
          "p2-v1": {
            "...": "omitted for brevity"
          }
        }
      }
    }
  }
}

Defaults and overrides

When making a request to Voyado Elevate, a market and locale are always supplied. The entities which can be returned are determined by the market and locale availability, but the data that the entities contain is determined by how the data is supplied within each entity. Structural information such as included imagery and variants, as well as a selected few properties, such as content type and product colors, are provided on the entities themselves. This means that the information cannot differ for different market and locale request contexts. But the majority of properties can vary with the request context. These attributes are located within entity-specific data objects called defaults, and can be overridden using overrides. Entities that support defaults and overrides include content, product, variant, and image. Properties provided within defaults are returned for all request contexts with the correspondingly provided default value, unless overridden. In such cases, the overridden value of the property is returned. Overrides are provided as a map of data keys to the properties to override, where the data key determines when to apply the override. Overrides are only relevant for retailers that have or plan on supporting multiple markets or locales.

Data keys

Data keys consist of a market identifier and a locale, separated by a pipe [market]|[locale]. The asterisk * is a special identifier that signifies it is applicable for all markets or locales, for example [market]|* or *|[locale].

Locale overrides

Locale overrides refer to overrides that apply for a specific locale, regardless of market. Data keys for such overrides are constructed using * instead of a specific market, followed by the locale. A good rule of thumb is that locale overrides should be used for all localized text information that isn’t intended for, or supported in, filters and product selections. Good examples include title and description. Data key example: *|en-GB.

Market overrides

Market overrides refer to overrides that apply for a specific market, regardless of locale. Data keys for such overrides are constructed by the market identifier, followed by using * instead of a specific locale. Market overrides should be used to override properties that will be used in filters and product selections, as well as any attribute that is connected to the market rather than the locale. Some properties can only be overridden using market overrides; this is true for attributes which require locale consistency, such as rating, releaseDate, and stock. Properties used in filters and product selections with localized values should be localized using translations. Data key example: uk|*.

Distinct overrides

Distinct overrides refer to overrides that apply for a specific locale in a specific market. Data keys for such overrides are constructed by the market identifier, followed by the specific locale. Distinct overrides should not be used at all in the majority of integrations. When used, it is for very specific circumstances or use cases. If distinct overrides are used a lot, the catalog feed is likely modeled incorrectly. One use case where distinct overrides are reasonable to use is for URLs given specific circumstances, for example URLs that include both market and locale, where no post-processing of them is done on the site. Data key example: uk|en-GB.

Value evaluation order

Values of properties are resolved according to the following priority:

Distinct overrides
Market overrides
Locale overrides
defaults

This means that if a property is included in a distinct, market, and locale override, the value in the distinct override will be the resulting value for requests with that market and locale combination. However, overridden values should under normal circumstances only be provided as a single type of override.

Guidelines

Aim for the highest level of abstraction when modeling defaults and overrides.
For all properties that are shared across markets and locales for an entity, use defaults.
When using overrides, place data where it naturally belongs when possible.
Distinct overrides should only be used in very rare cases.
Localize values using translations for all properties that are used as filters and product selections.
Follow best practices.

Specific use cases

Defaults as fallback

An optional usage of defaults is to use it as fallback data. This can be applicable when all properties are well-defined for the entities in a certain market and locale and are acceptable to use for other market and locale combinations as well, when no other data is present.

Unique locales per market

When having exactly one locale per market and no locales are ever reused, all overrides can be supplied for each market and locale combination using market overrides. If locales start being reused across markets, it is strongly recommended to generalize the locale information to locale overrides at that point. Note that distinct overrides are not recommended for this use case.

Overview

Configuration

Catalog imports

Other imports

Site integration

Other integrations

Product model

Product group

Product

Images

Variant

Sizes

Custom prices

Store stock

Content

Translation

Shared models

Custom attributes

customLabels

customLengths

customNumbers

customJson

customData

Predefined measurements

Markets and locales

Example

Defaults and overrides

Data keys

Locale overrides

Market overrides

Distinct overrides

Value evaluation order

Guidelines

Specific use cases

Defaults as fallback

Unique locales per market

​Product model

​Product group

​Product

​Images

​Variant

​Sizes

​Custom prices

​Store stock

​Content

​Translation

​Shared models

​Custom attributes

​customLabels

​customLengths

​customNumbers

​customJson

​customData

​Predefined measurements

​Markets and locales

​Example

​Defaults and overrides

​Data keys

​Locale overrides

​Market overrides

​Distinct overrides

​Value evaluation order

​Guidelines

​Specific use cases

Defaults as fallback

Unique locales per market

Product model

Product group

Product

Images

Variant

Sizes

Custom prices

Store stock

Content

Translation

Shared models

Custom attributes

customLabels

customLengths

customNumbers

customJson

customData

Predefined measurements

Markets and locales

Example

Defaults and overrides

Data keys

Locale overrides

Market overrides

Distinct overrides

Value evaluation order

Guidelines

Specific use cases