> ## Documentation Index
> Fetch the complete documentation index at: https://product-discovery.developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XML format specification

> The XML data format specification for Admin v3 data imports to Voyado Elevate.

The format specification of the data feed describes how the product data needs to be formatted and structured to be imported into Voyado Elevate. This data feed is an XML file encoded using `UTF-8`. For full examples of the file syntax, see [Import examples](#import-examples).

<Tip>
  The XML format is the data import format used in version 3 of the Admin API. For newer versions, use the [Catalog import format](/docs/integration/catalog-imports/catalog-imports) and look [here](/docs/api/admin/v4/import/catalog) for the specification.
</Tip>

<Tip>
  * **Required** fields must be provided for the import to be accepted.
  * **Conditionally required** fields are only required as stated by the conditions.
  * **Recommended** fields are important to very central features and are highly recommended to supply when possible.
  * Fields that are not highlighted are optional but may be required to enable specific features or performance gains. It is recommended to provide this information when easily accessible, or when needed for specific features. This information can often favorably be added iteratively once a data feed with required and recommended elements is in place.
</Tip>

<Note>
  [Market identifiers](/docs/integration/essentials/markets-and-locales#markets) and keys for product groups, products, and variants must be consistent across the data feed, the order notifications, and the order history. All keys within a market must be unique and are case sensitive.
</Note>

## Product data

Product data consist of [product groups](#product-group) that include [products](#product) that in turn include [variants](#variant). Maximum length of an element value is 2,000,000 characters.

### Product group

The first level of the data model is the product group (the overall article). The product group holds attributes that are common for all its products and variants. A product group must contain at least one product.

```xml icon="code" theme={null}
<product_group key="1001">
    <brand>Gazelle</brand>
    <department>Men</department>
    <products suppress_duplicates="true">
        ... <!-- As described in the product section -->
    </products>
</product_group>
```

#### Elements and attributes

| Name                  | Type                | Description                                                                                                                                                                                                                                                                                  |
| --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                 | string              | The key of this product group, must be unique within all `key` attributes for the market. **Required.** Type restrictions: maximum length is 50 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.                                                                     |
| `brand`               | string              | The brand of the product group, for example Calvin Klein or Bosch. It is searchable, used as an autocomplete phrase, and supports faceting. **Recommended.**                                                                                                                                 |
| `department`          | string              | Element used to filter on department. This supports faceting and search. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters).                                                                                                    |
| `size_type`           | string              | Enables manually defined grouping of sizes in the size facet. Can be any value.                                                                                                                                                                                                              |
| `products`            | [product](#product) | Group element for products. Requires at least one product. **Required element for data import.** Not allowed for attribute modification.                                                                                                                                                     |
| `suppress_duplicates` | boolean             | An optional attribute set on the `products` element. If set to `true`, for example `<products suppress_duplicates="true">`, this product group will only show up once in a product listing. Useful for visually similar product groups. Will default to `false` if omitted in the data feed. |

### Product

A product is a color or style variation of a product group and contains attributes that are specific to this variation. Each product in turn must contain at least one [variant](#variant) and is strongly recommended to have at least one [image](#images).

```xml icon="code" expandable theme={null}
<product key="1001-100">
    <title>Linen T-shirt</title>
    <url>/products/1001-100</url>
    <release_date>2019-10-27T00:00:00Z</release_date>
    <description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
    <categories>men > clothing > t-shirts &amp; polos > t-shirts</categories>
    <images>
        ... <!-- As described in the images section -->
    </images>
    <custom_attributes>
        <season>Summer</season>
        <style>Casual</style>
        <material>Cotton</material>
    </custom_attributes>
    <custom>
        <lengths>
            <package_width>
                <amount>37.5</amount>
                <unit>cm</unit>
            </package_width>
        </lengths>
    </custom>
    <variants>
        ... <!-- As described in the variant section -->
    </variants>
</product>
```

#### Elements and attributes

| Name                   | Type                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                  | string                                                                                     | The key of this product, must be unique within all `key` attributes for the market. **Required.** Type restrictions: maximum length is 50 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `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. Examples: "Plate 28 cm, red", "Teddy-lined suede jacket". **Required.**                                                                                                                                                                                                                                                                                                                                                                                |
| `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. **Required.** Type restrictions: must be relative to page root, that is start with `/`. Relative path example: `/products/1001-100`.                                                                                                                                                                                                                                                                                                                                                                             |
| `categories`           | string                                                                                     | The categories of the product. Used to define pages in the apps and to help Elevate understand the product. **Recommended.** Use the greater than symbol (`>`) to specify hierarchy if this information is available, for example `Clothing > Trousers > Chinos`. Spaces are optional but should be consistent. Supports multiple pipe-separated (`\|`) values. Supports [attribute names](#attribute-names). For more information about categories, see [Categories](/docs/guides/feature-concepts/categories).                                                                                                                                                  |
| `variants`             | [variant](#variant)                                                                        | Group element for variants. Requires at least one variant. **Required element for data import.** Not allowed for attribute modification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `release_date`         | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) <Icon icon="external-link" size={12} /> | Used for ranking and adding badges to new items and for sorting by `newest first`. **Recommended.** Type restrictions: time is in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) <Icon icon="external-link" size={12} /> 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.                                                                                                                                                                                                                                 |
| `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](mailto:support@voyado.com). **Recommended.**                                                                                                                                                                                                                                                                                                                                                                                                            |
| `images`               | [images](#images)                                                                          | Group element for images. Requires at least one image if present. **Recommended.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `custom_attributes`    | custom attributes                                                                          | Group element for custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the [Settings tab](https://help.elevate.voyado.com/hc/en-gb/articles/27611266063132-Settings) <Icon icon="external-link" size={12} /> in the Experience app. **Recommended.** Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Supports [attribute names](#attribute-names). Type restrictions: maximum length of custom element names is 2,000 characters.                                                                                              |
| `custom`               | [typed custom attributes](#typed-custom-attributes)                                        | Group element for typed custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the [Settings tab](https://help.elevate.voyado.com/hc/en-gb/articles/27611266063132-Settings) <Icon icon="external-link" size={12} /> in the Experience app.                                                                                                                                                                                                                                                                                                                                                       |
| `pattern`              | string                                                                                     | The pattern of the product, such as `Dotted` or `Striped`. This supports faceting and search. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters).                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `rating`               | double                                                                                     | A product rating. Enables ratings in product cards. For more information about ratings, see [Additional features](https://help.elevate.voyado.com/hc/en-gb/articles/27609462141596-Additional-features#ratings) <Icon icon="external-link" size={12} />. Type restrictions: ratings must be a decimal number from `0.0` to `5.0`.                                                                                                                                                                                                                                                                                                                                 |
| `color_default`        | color code                                                                                 | 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](https://help.elevate.voyado.com/hc/en-gb/articles/27609512134300-Image-and-data-analysis#color-analysis) <Icon icon="external-link" size={12} />. Supports multiple pipe-separated (`\|`) values. Type restrictions: valid color codes are provided as hex, for example `#ffffff`. Additional valid values are `Gold`, `Silver`, or `Multi`.                                                                                                  |
| `color_override`       | color code                                                                                 | An override of the product color, used to override the color analysis and the `color_default` attribute. For more information about color analysis, see [Image and data analysis](https://help.elevate.voyado.com/hc/en-gb/articles/27609512134300-Image-and-data-analysis#color-analysis) <Icon icon="external-link" size={12} />. Supports multiple pipe-separated (`\|`) values. Type restrictions: valid color codes are provided as hex, for example `#ffffff`. Additional valid values are `Gold`, `Silver`, or `Multi`.                                                                                                                                    |
| `product_type_default` | string                                                                                     | Used as a strong hint to the automatic product type analysis in identifying the product type. Especially useful when a product falls into multiple categories or lacks explicit mention of its type. Examples: `truckercap`, `book` or `potato peeler`. Key pointers: avoid broad and general terms like `tools`, `headwear`, `library` or `clothing`, opt for single specific product type terms, avoid broader categories or multiple products, such as `t-shirts/tops` or `beds & mattresses`.                                                                                                                                                                 |
| `style_with`           | string                                                                                     | A list of product keys for products that should appear in the Style with recommendation on a product page. Supports multiple pipe-separated (`\|`) product keys. There can be a maximum of 20 product keys.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `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 [attribute names](#attribute-names). We recommend using attribute names 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](/docs/guides/recommendations/recommendation-best-practices#more-from-series). |
| `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`.                                                                                                                                                                                                                                                                                                                                                |
| `width`                | [length](#lengths)                                                                         | The width of the product, for example width of a book shelf. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `height`               | [length](#lengths)                                                                         | The height of the product, for example height of a miniature statue. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `length`               | [length](#lengths)                                                                         | The length of the product, for example length of a wire-lock. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `depth`                | [length](#lengths)                                                                         | The depth of the product, for example depth of a moving box. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `volume`               | [volume](#volume)                                                                          | The volume of the product, for example how much a shampoo bottle contains. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `weight`               | [weight](#weight)                                                                          | The weight of the product, for example how heavy an item is. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

#### Images

The `images` element is a part of the [product element](#product) and contains one or more `image` elements. The `image` element defines a single image which may have URLs with different resolutions of the same image. Multiple resolutions are used for saving bandwidth and are especially useful for thumbnails. An `image` element must have an `urls` element which must have at least one URL, and URLs must be unique within a product. If relative image resolutions are known, the image URLs should be ordered by ascending width, that is smallest first, otherwise it can lead to inconsistencies before it is analyzed automatically. There can be a maximum of 25 images on a product.

```xml icon="code" expandable theme={null}
<images>
    <image>
        <urls>
            <url>//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
            <url>//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
        </urls>
    </image>
    <image>
        <urls>
            <url>//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
            <url>//cdn.example.com/images/1001-100_cutout.jpg</url>
        </urls>
    </image>
</images>
```

##### Elements and attributes

| Name    | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                     |
| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | element | A group element for one image. Contains advanced image attributes and `urls`. **Required.**                                                                                                                                                                                                                                                                                                     |
| `urls`  | element | A group element for the `url` elements of one image. **Required.**                                                                                                                                                                                                                                                                                                                              |
| `url`   | string  | The URL to the image. Multiple `url` elements containing different resolutions of the same product image may be provided for optimal performance. **Required.** Type restrictions: URLs 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`. |

##### Advanced image imports

Additional attributes regarding image tags, widths, and types can be set in the import. These attributes are mainly for use before the automatic image analysis is complete. There is also support for custom image attributes and the `alt` and `caption` elements.

```xml icon="code" expandable theme={null}
<images>
    <image>
        <type_default>model</type_default>
        <tags>Hero|Good</tags>
        <alt>A woman wearing a white t-shirt</alt>
        <caption>The model is 176 cm tall and is wearing size S</caption>
        <urls>
            <url width="200">//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
            <url width="600">//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
        </urls>
    </image>
    <image>
        <type_override>cutout</type_override>
        <alt>A white t-shirt</alt>
        <urls>
            <url width="40">//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
            <url width="600">//cdn.example.com/images/1001-100_cutout.jpg</url>
        </urls>
    </image>
    <image>
        <type_override>misc</type_override>
        <custom_attributes>
            <user>John Doe</user>
            <type>Instagram</type>
        </custom_attributes>
        <urls>
            <url width="600">//cdn.example.com/images/1001-100_influencer.jpg</url>
        </urls>
    </image>
</images>
```

###### Elements and attributes

| Name                | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tags`              | string            | Element of `image` that allows custom tagging of images for image prioritization in the product cards set in the Elevate apps. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Not allowed on a [content](#content) image.                                                                                                                                                       |
| `width`             | integer           | Attribute of `url` that specifies 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](https://help.elevate.voyado.com/hc/en-gb/articles/27609512134300-Image-and-data-analysis#image-resolution-analysis) <Icon icon="external-link" size={12} />. Type restrictions: must be a positive integer.                                 |
| `type_default`      | string            | Element of `image` describing the type of image, used until automatic image analysis can be performed. For more information about image analysis, see [Image and data analysis](https://help.elevate.voyado.com/hc/en-gb/articles/27609512134300-Image-and-data-analysis#image-type-analysis) <Icon icon="external-link" size={12} />. Not allowed on a [content](#content) image. Type restrictions: can be either `model`, `cutout`, or `misc`. |
| `type_override`     | string            | Element of `image` overriding the analyzed image type. For more information about image analysis, see [Image and data analysis](https://help.elevate.voyado.com/hc/en-gb/articles/27609512134300-Image-and-data-analysis#image-type-analysis) <Icon icon="external-link" size={12} />. Not allowed on a [content](#content) image. Type restrictions: can be either `model`, `cutout`, or `misc`.                                                 |
| `alt`               | string            | Element of `image` specifying the alt text of an `image`. The alt text should describe the image. Always returned along with the image.                                                                                                                                                                                                                                                                                                           |
| `caption`           | string            | Element of `image` specifying the caption for the `image`, only returned on the [product page](/docs/api/storefront/v3/queries/product-page) (or [content information](/docs/api/storefront/v3/queries/content-information) for content).                                                                                                                                                                                                         |
| `custom_attributes` | custom attributes | Group element for custom user-defined attributes which is 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 (\_). Supports [attribute names](#attribute-names).                                                                                                                                                            |
| `type`              | N/A               | Replaced by `type_default`. **Deprecated.**                                                                                                                                                                                                                                                                                                                                                                                                       |
| `resolution`        | N/A               | Replaced by `width`. **Deprecated.**                                                                                                                                                                                                                                                                                                                                                                                                              |

#### Attribute names

The `categories` attribute, `series` attribute, and custom attributes on products and variants can have a `name` attribute. The `name` is used to link a human-friendly name to an identifier to simplify merchandising without breaking the site when values change.

```xml icon="code" theme={null}
<custom_attributes>
    <season name="Summer">m_678</season>
    <style name="Casual|Baggy">m_c_349|m_c_333</style>
</custom_attributes>
<categories name="men > t-shirts">c102</categories>
<series name="Professional">Professional-Skeppshult</series>
```

##### Elements and attributes

| Name   | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Attribute that contains the human-friendly value that is displayed instead of the identifier. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Type restrictions: the number of identifiers must match the provided number of names when multiple pipe-separated values are used. The identifier must be unique and not associated with more than one `name` within an import. |

<Accordion title="Additional information">
  It is strongly advised to use stable IDs when creating pages and/or boost/bury, but it is hard for merchandisers to work with IDs. To solve this problem, a `name` can be used to tie a name and an ID together. An attribute with a `name` will work just as an attribute with the name as its value in all aspects, except for filtering and making product selections. When making product selections in the apps, the name will be shown but the ID will be saved. This means that if the name changes, no pages or boost/bury will stop working.

  Names are supplied as an XML attribute to the attribute element. Below is an example:

  ```xml icon="code" theme={null}
  <custom_attributes>
      <season name="Summer">m_678</season>
      <style name="Casual|Baggy">m_c_349|m_c_333</style>
      <material name="Cotton">349</material>
  </custom_attributes>
  <categories name="men>t-shirts">c102<categories>
  ```

  In this example, for the first element, `season` is the attribute, `Summer` is the name, and `m_678` is the ID. The name `Summer` will be searchable and used by Elevate to understand the product. `Summer` will also be shown in the apps, but if chosen, the ID `m_678` will be saved instead of the name `Summer`.

  Import rules for `name`:

  * The number of pipe-separated values supplied must match the number of names. The first name represents the first value and so on. In the example above, `Baggy` is the name of the style with the ID `m_c_333`. If a custom attribute has multiple values and only some of them have names, then the ID should be entered as the name for the IDs which are missing a name. It is recommended to use names for either all values or none within one attribute.
  * IDs must only have one name. If an ID is associated with multiple names in the same import, the import will fail.
  * If two IDs within the same custom attribute share the same name, faceting will consider them to be the same but product selections will consider them separate. In the apps, names with multiple IDs will be represented as `name (ID)`.
  * Setting or changing a name on one product will apply the name to all instances of that ID on all products in the import and previously existing products. If an ID has a name, it is recommended to always include the name alongside the ID.
  * If a value that has had a name since a previous import is only mentioned without a name in a new import, the name will be removed from all previously existing products.
</Accordion>

#### Typed custom attributes

The `custom` element allows custom attributes of specific types to be imported. Supplying types on custom attributes enables type-specific features, such as range facets for `lengths` and `numbers`.

The supported types are `lengths` and `numbers`.

##### Length custom attributes

Custom attributes of type `lengths` can be used to define secondary measurement attributes, such as the package size. Within the `lengths` element, the name of the custom length attribute is specified, followed by the [length information](#lengths).

```xml icon="code" expandable theme={null}
<custom>
    <lengths>
        <package_width>
            <amount>37.5</amount>
            <unit>cm</unit>
        </package_width>
        <package_height>
            <amount>10</amount>
            <unit>cm</unit>
        </package_height>
        <package_depth>
            <amount>25</amount>
            <unit>cm</unit>
        </package_depth>
    </lengths>
</custom>
```

##### Number custom attributes

Custom attributes of type `numbers` can be used to define number attributes, such as the number of items in a package. Negative numbers are supported.

```xml icon="code" theme={null}
<custom>
    <numbers>
        <items_in_package>12</items_in_package>
    </numbers>
</custom>
```

#### 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 the import, each product must have predefined measurements specified, either at product level or variant level. When provided at variant level, all the variants of a product must specify the predefined measurement.

#### Lengths

Length properties consist of an amount and a unit describing a specific length. Lengths can be [predefined measurements](#predefined-measurements) or supplied as [typed custom attributes](#typed-custom-attributes).

##### Length format

```xml icon="code" theme={null}
<amount>10</amount>
<unit>cm</unit>
```

###### Elements and attributes

| Name     | Type   | Description                                                                     |
| -------- | ------ | ------------------------------------------------------------------------------- |
| `amount` | double | The amount of the length. Must be a positive value.                             |
| `unit`   | string | The unit of the length. Must be one of `mm`, `cm`, `dm`, `m`, `in`, `ft`, `yd`. |

#### Volume

Volume is a property type consisting of an amount and a unit describing a specific volume. `Volume` is a [predefined measurement](#predefined-measurements).

##### Volume format

```xml icon="code" theme={null}
<amount>10</amount>
<unit>cl</unit>
```

###### Elements and attributes

| Name     | Type   | Description                                                                |
| -------- | ------ | -------------------------------------------------------------------------- |
| `amount` | double | The amount of the volume. Must be a positive value.                        |
| `unit`   | string | The unit of the volume. Must be one of `ml`, `cl`, `dl`, `l`, `oz`, `gal`. |

#### Weight

Weight is a property type consisting of an amount and a unit describing a specific weight. `Weight` is a [predefined measurement](#predefined-measurements).

##### Weight format

```xml icon="code" theme={null}
<amount>10</amount>
<unit>kg</unit>
```

###### Elements and attributes

| Name     | Type   | Description                                                               |
| -------- | ------ | ------------------------------------------------------------------------- |
| `amount` | double | The amount of the weight. Must be a positive value.                       |
| `unit`   | string | The unit of the weight. Must be one of `mg`, `g`, `hg`, `kg`, `lb`, `oz`. |

### Variant

A `variant` is a stock-keeping unit (SKU) and contains attributes that are specific to the SKU. A variant typically represents a single physical size, and a physical size can be expressed in several formats, see [Sizes](#sizes), section Advanced size import.

```xml icon="code" expandable theme={null}
<variant key="1001-100-1">
    <stock_number>12</stock_number>
    <selling_price>9.99</selling_price>
    <list_price>12.99</list_price>
    <cost>8.00</cost>
    <url>/products/1001-100?size=XS</url>
    <length>
        <amount>68</amount>
        <unit>cm</unit>
    </length>
    <sizes>
        <size>XS</size>
    </sizes>
    <custom_attributes>
        <ean_code>1234567890123</ean_code>
    </custom_attributes>
</variant>
```

#### Elements and attributes

| Name                | Type                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`               | string                                              | The key of the variant element, must be unique within all `key` attributes for the market. **Required.** When [using Voyado Elevate with Voyado Engage](/docs/integration/voyado-engage-integration), the `key` **must** be the same as the article SKU in Voyado Engage, `sku`. Type restrictions: maximum length is 50 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `stock_number`      | 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.** Type restrictions: must be an integer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `selling_price`     | double                                              | 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list_price`        | double                                              | The standard price. **Required.** Type restrictions: must be a decimal number, greater than or equal to the `selling_price`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `sizes`             | [sizes](#sizes)                                     | A group element for the `size` element of this variant. Requires at least one `size` if present. Do not use `label` or `sizes` if there is only one variant per product. **Conditionally required**, under the following circumstances: the product has more than one variant, and `label` is not used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `cost`              | double                                              | 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.** Type restrictions: must be a decimal number. Must be a non-zero value less than the `sellingPrice`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `url`               | string                                              | The URL to the product page with this size preselected. Enables more specific link targets in product listings. **Recommended.** Type restrictions: must be relative to page root, that is start with `/`. Relative path: `/variant?variant_key=123-B-S`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `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. For example, 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**, under the following circumstances: the product has more than one variant, and `sizes` are not used.                                                                                                                                                                                                                                                          |
| `custom_prices`     | [custom prices](#custom-prices)                     | 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](https://help.elevate.voyado.com/hc/en-gb/articles/27609462141596-Additional-features#custom-prices) <Icon icon="external-link" size={12} />.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `stores`            | [stores](#stores)                                   | A group element for stores. Enables store specific stock numbers to be stored on each variant. For more information about stores, see [Store specific stock numbers](/docs/guides/feature-concepts/store-specific-stock-numbers).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `custom_attributes` | custom attributes                                   | Group element for custom user-defined attributes on variant level. These support faceting and search and can be selected for use as facets in the [Settings tab](https://help.elevate.voyado.com/hc/en-gb/articles/27611266063132-Settings) <Icon icon="external-link" size={12} /> 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 multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Supports [attribute names](#attribute-names). 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. |
| `custom`            | [typed custom attributes](#typed-custom-attributes) | Group element for typed custom user-defined attributes. These support faceting and search. Custom attributes are selected for use as facets in the [Settings tab](https://help.elevate.voyado.com/hc/en-gb/articles/27611266063132-Settings) <Icon icon="external-link" size={12} /> 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.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `order`             | integer                                             | An override of the variants' 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `width`             | [length](#lengths)                                  | The width of the variant, for example width of a book shelf. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `height`            | [length](#lengths)                                  | The height of the variant, for example height of a miniature statue. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `length`            | [length](#lengths)                                  | The length of the variant, for example length of a wire-lock. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `depth`             | [length](#lengths)                                  | The depth of the variant, for example depth of a moving box. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `volume`            | [volume](#volume)                                   | The volume of the variant, for example how much a shampoo bottle contains. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `weight`            | [weight](#weight)                                   | The weight of the product, for example how heavy an item is. Supports faceting, search, and sorting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

#### Sizes

`Sizes` is a part of the [variant element](#variant) and contains one or more `size` elements.

##### Elements and attributes

| Name   | Type   | Description                                                                                                                                                                                                                  |
| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `size` | string | The size of a variant. Required if `sizes` is present. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Type restrictions: duplicate values are not allowed. |

##### Advanced size import

Each variant has a single physical size, but the 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.

The format of the size is specified as an attribute and the actual size is provided as the value of the `size` element.

```xml icon="code" theme={null}
<sizes>
    <size custom_format="SML">S</size>
    <size custom_format="EU">34|36</size>
</sizes>
```

Multiple variants with the same format and value are allowed, as long as there is one format with a unique single value. For example, the snippet below shares the value 36 in the format EU with the example above, but may be imported as sizes for another variant, as the sizes have unique values in the format SML.

```xml icon="code" theme={null}
<sizes>
    <size custom_format="SML">M</size>
    <size custom_format="EU">36|38</size>
</sizes>
```

###### Elements and attributes

| Name            | Type   | Description                                                                                                                                                              |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `custom_format` | string | Attribute to the `size` element that describes the format that the size is provided in. It should follow key conventions and is required if multiple sizes are provided. |

#### Custom prices

The `custom_prices` element is a part of the [variant element](#variant) and contains one or more `price` elements. The maximum number of `price` elements for a variant is 1,000.

##### Advanced price import

For more information about custom prices, see [Additional features](https://help.elevate.voyado.com/hc/en-gb/articles/27609462141596-Additional-features#custom-prices) <Icon icon="external-link" size={12} />.

```xml icon="code" expandable theme={null}
<custom_prices>
    <price id="EUR">
        <selling_price>9.99</selling_price>
        <list_price>12.99</list_price>
    </price>
    <price id="SEK">
        <selling_price>99.90</selling_price>
        <list_price>129.90</list_price>
    </price>
    <price id="VIP_SEK">
        <selling_price>69.90</selling_price>
        <list_price>129.90</list_price>
    </price>
</custom_prices>
```

###### Elements and attributes

| Name            | Type    | Description                                                                                                                                                                                                                                                                                                                                            |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `price`         | element | Contains `selling_price` and `list_price` for a specific `id`. **Required.**                                                                                                                                                                                                                                                                           |
| `id`            | string  | Attribute to the `price` element. The `id` indicates which price should be displayed. If a custom price with a specific ID has been provided to a variant, all variants within that product must be provided with price information for that price ID. Products with price inconsistencies among variants will cause the import to fail. **Required.** |
| `selling_price` | double  | The price that the customer pays. When the variant is on sale, the `selling_price` is lower than the `list_price`. Displayed on the product card and used for badges. **Required.** Type restrictions: must be a decimal number, and be less than or equal to the `list_price`.                                                                        |
| `list_price`    | double  | The price displayed in the shop as the standard price. **Required.** Type restrictions: must be a decimal number, and be greater than or equal to the `selling_price`.                                                                                                                                                                                 |

#### Stores

The `stores` element is a part of the [variant element](#variant) and contains one or more `store` elements and their stock numbers.

##### Advanced stores import

For more information about stores, see [Store specific stock numbers](/docs/guides/feature-concepts/store-specific-stock-numbers).

```xml icon="code" theme={null}
<stores>
    <store key="240">
        <stock_number>5</stock_number>
    </store>
    <store key="100">
        <stock_number>0</stock_number>
    </store>
</stores>
```

###### Elements and attributes

| Name           | Type    | Description                                                                                                                                                                                            |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `store`        | element | Contains `stock_number` for a specific store.                                                                                                                                                          |
| `key`          | string  | Attribute on the `store` element. The `key` identifies the store. **Required.** Type restrictions: maximum length is 50 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.       |
| `stock_number` | integer | Number of items of this variant in stock in the store, used in ranking and marking the variant as out-of-stock. Negative values are treated as 0. **Required.** Type restrictions: must be an integer. |

## Content

The `content` element enables visitors to find editorial content items on a site, such as FAQs, shipping, and contact information. Content items are usually placed after the product groups in the import files.

```xml icon="code" expandable theme={null}
<content key="842">
    <type>article</type>
    <title>It's finally sweater season</title>
    <link>/uk/articles/its-finally-sweater-season-2020-11-20/</link>
    <release_date>2020-11-20T00:00:00Z</release_date>
    <description>As the holiday season approaches, temperatures start to fall 
    and skies begin to darken. It is time to embrace the clothes that will 
    get you through the chilliest days and nights of the year - the sweater. 
    Warm, comfortable, and stylish when it matters the most.</description>
    <image>
        <urls>
            <url>//cdn.example.com/images/content/sweater_season_2020.jpg?preset=800x400</url>
        </urls>
    </image>
    <custom_attributes>
        <tags>Winter|Fashion</tags>
    </custom_attributes>
</content>
```

### Elements and attributes

| Name                | Type                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `key`               | string                                                                                     | The key of this content, must be unique for the market. **Required.** Type restrictions: maximum length is 50 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.                                                                                                                                                                                                                                                                             |
| `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.                                                                                                                                                                                                                                                                                                             |
| `title`             | string                                                                                     | Title of the content item. **Required.**                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `link`              | string                                                                                     | URL to the page on this topic. Can be relative or absolute. Relative URLs must be relative to page root, that is 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`. **Required.**                                           |
| `release_date`      | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) <Icon icon="external-link" size={12} /> | Used for sorting by `newest first`. Type restrictions: time is in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) <Icon icon="external-link" size={12} /> 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.                                                                                                  |
| `description`       | string                                                                                     | The description of the content. Used for search but valued less than other attributes when evaluating a match.                                                                                                                                                                                                                                                                                                                                                     |
| `image`             | [image](#images)                                                                           | One image representing the content.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `custom_attributes` | custom attributes                                                                          | Group element for custom user-defined attributes. These support search and are returned with the content item in the results. The user-friendly `name` attribute is not supported for custom attributes for content. Supports multiple pipe-separated (`\|`) values, see [Escaping special characters](#escaping-special-characters). Supports [attribute names](#attribute-names). Type restrictions: maximum length of custom element names is 2,000 characters. |

<Accordion title="Old content link format">
  The old content link import format is still supported for backwards compatibility. The new and old format cannot be mixed in an import. The old format is shown below.

  ```xml icon="code" theme={null}
  <modify market="UK" locale="en-GB">
      <content_links>
          <add_or_replace>
              <content_link key="871">
                  <title>Shipping</title>
                  <url>/uk/customer-service/shipping</url>
              </content_link>
              ...
          </add_or_replace>
      </content_links>
  ```

  **Elements and attributes**

  | Name    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                              |
  | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `key`   | string | The key of this content link, must be unique for the market. **Required.** Type restrictions: maximum length is 200 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `#+./_-`.                                                                                                                                                                                                                             |
  | `title` | string | Title to be displayed as text completion. **Required.**                                                                                                                                                                                                                                                                                                                                                                  |
  | `url`   | string | URL to the page on this topic. Can be relative or absolute. Relative URLs must be relative to page root, that is 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`. **Required.** |
</Accordion>

## Imports

An import can be either a full, a partial, or an attribute modification import. The import type is based on the root element of the import file. The import file type is XML and must be encoded using `UTF-8`.

A full import is used to set the complete state of the product and content data for all markets. Partial updates are used to add, replace, or remove product or content items.

The attribute modification import has a different root element than full and partial imports. It is used for frequent updates of item attributes such as `selling_price` and `stock_number`. Only attributes defined in the import will be modified. The attribute modification import can also add new attributes to existing items.

For more information on when to use full, partial, or attribute modification imports, see [Scheduled imports](/docs/integration/catalog-imports/scheduling#scheduled-imports).

### Data import

The data import is either `full` or `partial` and is the root element of an import XML file. Three elements, `remove_all`, `remove`, and `add_or_replace`, in the XML file define what Elevate will do with the data in the file.

The `full` import sets the complete state of the data, thus anything that is not declared in the import will be deleted from Elevate, regardless of market. This enables a retailer to do a full synchronization between their systems and Elevate. Data is added into Elevate by using the `add_or_replace` element.

A partial import has the type attribute set to `partial`. This means that no data is automatically removed at the beginning of the import unless `remove` or `remove_all` are present in the file before using `add_or_replace`. Note that partial updates of product groups replace the entire group. This means that the product group is expected to be complete, as it replaces all information about the product group and any connected products and variants. To only modify information, use [Attribute modification](#attribute-modification).

#### Elements and attributes

| Name             | Description                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | Defines the type of import when using `data_import`. Valid values are `full` and `partial`. **Required.**                                         |
| `modify`         | Element that defines the `market` and `locale` to perform import operations on. **Required.**                                                     |
| `add_or_replace` | Operation that adds new, or updates existing, `product_groups` or `content_items` for the market that is modified by the import.                  |
| `remove`         | Operation that allows removal of an individual `product_group` or `content_items`. Requires a `key` value for each element that is to be removed. |
| `remove_all`     | Operation that removes all `product_groups` or `content_items` for the market that is modified by the import.                                     |

#### Modify

The `modify` element is used by the full and partial import methods. It defines the [market](/docs/integration/essentials/markets-and-locales#markets) and locale that is being imported. Multiple markets can be modified in the same [import](#imports). A market and locale combination can only be modified once during an import.

```xml icon="code" theme={null}
<modify market="UK" locale="en-GB">
    <!-- Product groups and content for the market UK -->
</modify>
<modify market="BE" locale="nl-NL">
    <!-- Product groups and content for the market BE in Dutch -->
</modify>
<modify market="BE" locale="fr-FR">
    <!-- Product groups and content for the market BE in French -->
</modify>
```

#### Elements and attributes

| Name     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market` | A market key. See [details](/docs/integration/essentials/markets-and-locales#markets). **Required.** Type restrictions: maximum length is 40 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `_-`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `locale` | Locale for searching, used when matching items in the market. Also defines which synonyms will be used. Given in the format `<language>-<COUNTRY>`, for example `en-GB`. An important thing to note is that setting the locale will change the locale for all items in the market, including previously imported items. Currently supported locales: `bg-BG`, `cs-CZ`, `da-DK`, `de-AT`, `de-CH`, `de-DE`, `el-GR`, `en-001`, `en-150`, `en-AU`, `en-CA`, `en-GB`, `en-IE`, `en-IN`, `en-PH`, `en-HK`, `en-TW`, `en-MO`, `en-US`, `es-ES`, `es-MX`, `et-EE`, `fi-FI`, `fr-BE`, `fr-CA`, `fr-CH`, `fr-FR`, `he-IL`, `hr-HR`, `hu-HU`, `it-CH`, `it-IT`, `ja-JP`, `ko-KR`, `lt-LT`, `lv-LV`, `nb-NO`, `nn-NO`, `no-NO`, `nl-BE`, `nl-NL`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sr-RS`, `sv-FI`, `sv-SE`, `tr-TR`, `uk-UA`, `vi-VN`, `zh-CN`, `zh-HK`, `zh-TW` and `zh-MO`. **Required.** |

### Attribute modification

The attribute modification import has the root element `attribute_modification` in the import XML file. It is used to modify attributes within individual items, as well as to add new attributes to existing items.

All items that are to be modified, such as `product_groups`, `product`, `variant`, and `content`, are identified by their `key` attribute values. If an item cannot be identified, for example due to an incorrect or nonexistent `key`, that item will be ignored, a warning will be logged, and the rest of the items are imported normally. Nesting of products within product groups and variants within products in the XML is not allowed.

The `modify_attributes` element is used by the attribute modification. It defines what existing market and locale that content will be operated on. Multiple markets and locales can be modified in the same import. A market and locale combination can only be modified once during an import.

For markets with exactly one locale, the locale may be omitted. For markets with multiple locales, the locale must be specified except for cross-locale attribute modifications, see below.

Product groups, products, variants, and content are modified separately when performing an attribute modification.

```xml icon="code" expandable theme={null}
<attribute_modification>
    <modify_attributes market="CA" locale="en-CA">
        <product_groups>
            <!-- Modifications on the Product groups level for the market CA and locale en-CA -->
        </product_groups>
        <products>
            <!-- Modifications on the Products level for the market CA and locale en-CA -->
        </products>
        <variants>
            <!-- Modifications on the Variants level for the market CA and locale en-CA -->
        </variants>
        <content_items>
            <!-- Modifications of Content for the market CA and locale en-CA -->
        </content_items>
    </modify_attributes>
    <modify_attributes market="CA" locale="fr-CA">
        <product_groups>
            <!-- Modifications on the Product groups level for the market CA and locale fr-CA -->
        </product_groups>
        <products>
            <!-- Modifications on the Products level for the market CA and locale fr-CA -->
        </products>
        <variants>
            <!-- Modifications on the Variants level for the market CA and locale fr-CA -->
        </variants>
        <content_items>
            <!-- Modifications of Content for the market CA and locale fr-CA -->
        </content_items>
    </modify_attributes>
</attribute_modification>
```

#### Elements and attributes

| Name                | Description                                                                                                                                                                                                                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `modify_attributes` | Element that defines the market to perform updates on. **Required.**                                                                                                                                                                                                                                         |
| `market`            | A market key. See [details](/docs/integration/essentials/markets-and-locales#markets). **Required.** Type restrictions: maximum length is 40 characters and allowed characters are `A-Z`, `a-z`, `0-9`, and `_-`.                                                                                            |
| `locale`            | Locale for searching, used when matching items in the market. Also defines which synonyms will be used. Given in the format `<language>-<COUNTRY>`, for example `en-GB`. Locale is optional for single-locale markets and for [cross-locale attribute modifications](#cross-locale-attribute-modifications). |
| `product_groups`    | Element that contains the [product groups](#product-group) that are to be modified.                                                                                                                                                                                                                          |
| `products`          | Element that contains the [products](#product) that are to be modified.                                                                                                                                                                                                                                      |
| `variants`          | Element that contains the [variants](#variant) that are to be modified.                                                                                                                                                                                                                                      |
| `content_items`     | Element that contains the [content](#content) that are to be modified.                                                                                                                                                                                                                                       |

#### Cross-locale attribute modifications

On markets with multiple languages, stock, cost, and price may be modified across all locales in a market. A cross-locale attribute modification is specified by omitting the locale in the `modify_attributes` element.

<Warning>
  Cross-locale attribute modifications cannot be combined with normal attribute modifications on the same market in the same import. For more information, see [Multilingual markets](/docs/integration/data-feed/multilingual-markets).
</Warning>

## Import examples

### Full import

The following example will add items to a site with `market` set to `UK` and `locale` set to `en-GB`. Any previous data not included in the import will be deleted from Elevate, regardless of market.

```xml title="Full import example with basic information" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="full">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <add_or_replace>
                <product_group key="1001">
                    <brand>Gazelle</brand>
                    <department>Men</department>
                    <products>
                        <product key="1001-100">
                            <title>Linen T-shirt</title>
                            <url>/products/1001-100</url>
                            <release_date>2019-10-27T00:00:00Z</release_date>
                            <description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
                            <images>
                                <image>
                                    <urls>
                                        <url>//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url>//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <urls>
                                        <url>//cdn.example.com/images/1001-100_cutout.jpg?preset=200x200</url>
                                        <url>//cdn.example.com/images/1001-100_cutout.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                            </images>
                            <custom_attributes>
                                <season>Summer</season>
                                <style>Casual</style>
                                <material>Cotton</material>
                            </custom_attributes>
                            <variants>
                                <variant key="1001-100-1">
                                    <stock_number>12</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=S</url>
                                    <sizes>
                                        <size>S</size>
                                    </sizes>
                                </variant>
                                <variant key="1001-100-2">
                                    <stock_number>0</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=M</url>
                                    <sizes>
                                        <size>M</size>
                                    </sizes>
                                </variant>
                                <variant key="1001-100-3">
                                    <stock_number>5</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=L</url>
                                    <sizes>
                                        <size>L</size>
                                    </sizes>
                                </variant>
                            </variants>
                        </product>
                    </products>
                </product_group>
            </add_or_replace>
        </product_groups>
        <content_items>
            <add_or_replace>
                <content key="871">
                    <type>link</type>
                    <title>Shipping</title>
                    <link>/uk/customer-service/shipping</link>
                </content>
                <content key="872">
                    <type>link</type>
                    <title>Contact</title>
                    <link>/uk/contact</link>
                </content>
            </add_or_replace>
        </content_items>
    </modify>
</data_import>
```

```xml title="Full import example with advanced feature usage" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="full">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <add_or_replace>
                <product_group key="1001">
                    <brand>Gazelle</brand>
                    <department>Men</department>
                    <products>
                        <product key="1001-100">
                            <title>Linen T-shirt</title>
                            <url>/products/1001-100</url>
                            <release_date>2019-10-27T00:00:00Z</release_date>
                            <description>Loose-fit striped T-shirt with a slightly lower neckline.</description>
                            <images>
                                <image>
                                    <type_default>model</type_default>
                                    <tags>Hero</tags>
                                    <urls>
                                        <url width="200">//cdn.example.com/images/1001-100_model.jpg?preset=200x200</url>
                                        <url width="600">//cdn.example.com/images/1001-100_model.jpg?preset=600x600</url>
                                    </urls>
                                </image>
                                <image>
                                    <type_override>cutout</type_override>
                                    <urls>
                                        <url width="40">//cdn.example.com/images/1001-100_cutout_thumbnail.jpg</url>
                                        <url width="600">//cdn.example.com/images/1001-100_cutout.jpg</url>
                                    </urls>
                                </image>
                            </images>
                            <custom_attributes>
                                <season name="Summer">m_678</season>
                                <style name="Casual">m_c_349</style>
                                <material name="T-shirts">349</material>
                            </custom_attributes>
                            <pattern>striped</pattern>
                            <rating>4.3</rating>
                            <color_default>#0000ff|#ffffff</color_default>
                            <product_type_default>t-shirt</product_type_default>
                            <variants>
                                <variant key="1001-100-1">
                                    <stock_number>12</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=S</url>
                                    <sizes>
                                        <size custom_format="SML">S</size>
                                        <size custom_format="EU">36</size>
                                    </sizes>
                                    <custom_prices>
                                        <price id="EUR">
                                            <selling_price>9.99</selling_price>
                                            <list_price>12.99</list_price>
                                        </price>
                                        <price id="SEK">
                                            <selling_price>99.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                        <price id="VIP_SEK">
                                            <selling_price>69.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                    </custom_prices>
                                </variant>
                                <variant key="1001-100-2">
                                    <stock_number>0</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=M</url>
                                    <sizes>
                                        <size custom_format="SML">M</size>
                                        <size custom_format="EU">38</size>
                                    </sizes>
                                    <custom_prices>
                                        <price id="EUR">
                                            <selling_price>9.99</selling_price>
                                            <list_price>12.99</list_price>
                                        </price>
                                        <price id="SEK">
                                            <selling_price>99.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                        <price id="VIP_SEK">
                                            <selling_price>69.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                    </custom_prices>
                                </variant>
                                <variant key="1001-100-3">
                                    <stock_number>5</stock_number>
                                    <selling_price>9.99</selling_price>
                                    <list_price>12.99</list_price>
                                    <cost>8.00</cost>
                                    <url>/products/1001-100?size=L</url>
                                    <sizes>
                                        <size custom_format="SML">L</size>
                                        <size custom_format="EU">40</size>
                                    </sizes>
                                    <custom_prices>
                                        <price id="EUR">
                                            <selling_price>9.99</selling_price>
                                            <list_price>12.99</list_price>
                                        </price>
                                        <price id="SEK">
                                            <selling_price>99.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                        <price id="VIP_SEK">
                                            <selling_price>69.90</selling_price>
                                            <list_price>129.90</list_price>
                                        </price>
                                    </custom_prices>
                                </variant>
                            </variants>
                        </product>
                    </products>
                </product_group>
            </add_or_replace>
        </product_groups>
        <content_items>
            <add_or_replace>
                <content key="871">
                    <type>link</type>
                    <title>Shipping</title>
                    <link>/uk/customer-service/shipping</link>
                </content>
                <content key="872">
                    <type>link</type>
                    <title>Contact</title>
                    <link>/uk/contact</link>
                </content>
                <content key="901">
                    <type>faq</type>
                    <title>How do I return clothes?</title>
                    <link>/uk/faq/returns</link>
                    <release_date>2020-12-01T00:00:00Z</release_date>
                    <image>
                        <urls>
                            <url width="400">//cdn.example.com/images/returns-pic-11204</url>
                        </urls>
                    </image>
                    <custom_attributes>
                        <keywords>replace|swap|take back</keywords>
                    </custom_attributes>
                </content>
            </add_or_replace>
        </content_items>
    </modify>
</data_import>
```

### Partial import

The following example of a partial import will add or replace one or more product groups, products, variants, and content in an existing `market` with the key `UK`. The items are identified using their `key` values.

<Warning>
  Partial updates of product groups replace the entire group. This means that the product group is expected to be complete, as it replaces all information about the product group and any connected products and variants. To only modify information, use [Attribute modification](#attribute-modification).
</Warning>

```xml title="Partial import example with add or replace" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <add_or_replace>
                <product_group key="1001">
                    <!-- attributes omitted for brevity -->
                    <products>
                        <product key="1001-100">
                            <!-- attributes omitted for brevity -->
                            <variants>
                                <variant key="1001-100-1">
                                    <!-- attributes omitted for brevity -->
                                </variant>
                            </variants>
                        </product>
                    </products>
                </product_group>
                <product_group key="1024">
                    <!-- ... -->
                </product_group>
            </add_or_replace>
        </product_groups>
        <content_items>
            <add_or_replace>
                <content key="871">
                    <!-- attributes omitted for brevity -->
                </content>
            </add_or_replace>
        </content_items>
    </modify>
</data_import>
```

The following example of a partial import will remove all `product_groups` and `content_items` from an existing `market` with the key `UK`.

```xml title="Partial import example with remove all" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove_all/>
        </product_groups>
        <content_items>
            <remove_all/>
        </content_items>
    </modify>
</data_import>
```

The following example of a partial import will remove a specific `product_group` and `content` from an existing `market` with the key `UK`. The items are identified using their `key` values.

```xml title="Partial import example with remove" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<data_import type="partial">
    <modify market="UK" locale="en-GB">
        <product_groups>
            <remove>
                <!-- Removes product group with key = 1002 from market UK-->
                <product_group key="1002"/>
            </remove>
        </product_groups>
        <content_items>
            <remove>
                <!-- Removes content with key 984 from market UK -->
                <content key="873"/>
            </remove>
        </content_items>
    </modify>
</data_import>
```

### Attribute modification examples

The common use case for attribute modifications is when updating prices and stock numbers.

The following example of an attribute modification import will update specific values for a `product_group`, a `product`, a `variant`, and a `content` item on an existing `market` with the key `UK`. The items are identified using their `key` values.

```xml title="Attribute modification import example" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
    <modify_attributes market="CA" locale="en-CA">
        <product_groups>
            <!-- Update product group with key 1032,
            changing only its brand and leaving everything else untouched -->
            <product_group key="1032">
                <brand>Armani</brand>
            </product_group>
        </product_groups>
        <products>
            <!-- Update product with key 1051-110,
            changing only its title, custom attribute season, and adding a product type to it -->
            <product key="1051-110">
                <title>Jane Insulated Boot</title>
                <custom_attributes>
                    <season>Winter</season>
                </custom_attributes>
                <product_type_default>chelsea boot</product_type_default>
            </product>
        </products>
        <variants>
            <!-- Update variant with key 1157-120-1,
            changing only its stock_number and selling_price -->
            <variant key="1157-120-1">
                <stock_number>20</stock_number>
                <selling_price>8.99</selling_price>
            </variant>
        </variants>
        <content_items>
            <!-- Update content with key c1,
            changing only its title and its custom attribute author -->
            <content key="c1">
                <title>returns</title>
                <custom_attributes>
                    <author>Pelle</author>
                </custom_attributes>
            </content>
        </content_items>
    </modify_attributes>
    <modify_attributes market="CA" locale="fr-CA">
        <product_groups>
            <!-- Update product group with key 1032,
            changing only its brand and leaving everything else untouched -->
            <product_group key="1032">
                <brand>Armani</brand>
            </product_group>
        </product_groups>
        <products>
            <!-- Update product with key 1051-110,
            changing only its title, custom attribute season, and adding a product type to it -->
            <product key="1051-110">
                <title>Bottes isolées Jane</title>
                <custom_attributes>
                    <season>Hiver</season>
                </custom_attributes>
                <product_type_default>chelsea boot</product_type_default>
            </product>
        </products>
        <variants>
            <!-- Update variant with key 1157-120-1,
            changing only its stock_number and selling_price -->
            <variant key="1157-120-1">
                <stock_number>20</stock_number>
                <selling_price>8.99</selling_price>
            </variant>
        </variants>
        <content_items>
            <!-- Update content with key c1,
            changing only its title and its custom attribute author -->
            <content key="c1">
                <title>retours</title>
                <custom_attributes>
                    <author>Pelle</author>
                </custom_attributes>
            </content>
        </content_items>
    </modify_attributes>
</attribute_modification>
```

```xml title="Cross-locale attribute modification import example with store specific stock numbers and custom prices" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
    <!-- Locale is not specified so this applies to all locales for CA -->
    <modify_attributes market="CA">
        <variants>
            <!-- Update variant with key 1157-120-1,
            changing the stock_number for store "240" and no other store -->
            <variant key="1157-120-1">
                <stores>
                    <store key="240">
                        <stock_number>3</stock_number>
                    </store>
                </stores>
            </variant>
            <!-- Update variant with key 1190-110-2,
            changing the selling_price for price id "SEK" -->
            <variant key="1190-110-2">
                <custom_prices>
                    <price id="SEK">
                        <selling_price>33.00</selling_price>
                    </price>
                </custom_prices>
            </variant>
        </variants>
    </modify_attributes>
</attribute_modification>
```

## Escaping special characters

Some elements in the data model can take multiple pipe-separated (`|`) values. Therefore, if the pipe character is part of the data, such as in a category name, it must be escaped using a backslash, `\`, before the actual character, `\|`. Using a backslash in the data must also be escaped using another backslash, `\\`.

Escaping must be done for values in all elements, including single-value elements.

```xml title="Character escaping example" icon="code" expandable theme={null}
<?xml version="1.0" encoding="UTF-8" ?>
<attribute_modification>
    <modify_attributes market="UK">
        <products>
            <product key="1051-110">
                <custom_attributes>
                    <!-- This results in two values as the pipe is not escaped-->
                    <tags>Shoes|Boots</tags>
                    <!-- This results in escaped characters-->
                    <escaped_pipe>This is a vertical bar, a.k.a. pipe: \|</escaped_pipe>
                    <escaped_slash>This is a backslash: \\</escaped_slash>
                </custom_attributes>
            </product>
        </products>
    </modify_attributes>
</attribute_modification>
```