Skip to content

Magento V2 Product XML

The XML format documented here is used for the import of product records into Magento, via the Import Products to Magento V2 task.

Our object model mirrors the JSON body of the POST /V1/products endpoint, so the Adobe Commerce REST API reference is a useful companion to this page. Any product attribute Magento supports can be sent, either as one of the elements documented below or as a custom attribute.

We recommend that the external_id field be populated with the unique ID of the product from the external system. Zynk uses this field to track products already imported when the Prevent Reprocessing setting is enabled.

Required Fields

Magento rejects a new product if any of the following are missing. They are the most common cause of a 400 Bad Request from the products endpoint. Zynk does not fill in a value for any of these fields, so they must be set in your mapping.

XML Field Notes
sku Unique identifier for the product. Also used by Zynk to match existing products when no id is supplied
name Product name
attribute_set_id See Attribute Set below
price* Product price
type_id The type of product, e.g. simple
status See Status below
visibility See Visibility below
weight* Product weight
custom_attributes/custom_attribute (tax_class_id) See Tax Class below
  • price* - Required for simple, virtual and downloadable products. Not required for configurable and grouped products, or bundle products with a dynamic price
  • weight* - Required by Magento for shippable product types, e.g. simple. Omit for virtual and downloadable products

Status - Required

Sent in the status element. Controls whether the product can be sold.

Option Meaning
1 Enabled - This product is able to be sold
2 Disabled - This product is not able to be sold
<status>1</status>

Visibility - Required

Sent in the visibility element. Controls where the product appears on the storefront.

Option Meaning
1 Not Visible Individually - This product does not appear in the catalogue or in search results. Used for the child products of a configurable or grouped product
2 Catalog - This product appears when browsing the catalogue, but not in search results
3 Search - This product appears in search results, but not when browsing the catalogue
4 Catalog, Search - This product appears in both the catalogue and search results
<visibility>4</visibility>

Attribute Set - Required

Sent in the attribute_set_id element. The attribute set decides which attributes are available on the product.

Option Meaning
4 Default - The Default attribute set on a standard Magento installation
Any other ID An attribute set added to your own Magento installation. Use Export Product Attributes to find the IDs of your attribute sets
<attribute_set_id>4</attribute_set_id>

Tax Class - Required

Sent as a custom attribute with an attribute_code of tax_class_id, not as an element of the product. The options below are those of a standard Magento installation. Additional tax classes may have been added to your store.

Option Meaning
0 None - This product is not taxable
2 Taxable Goods - This product is taxed at the rate set up for Taxable Goods in Magento
<custom_attributes>
  <custom_attribute>
    <attribute_code>tax_class_id</attribute_code>
    <value>2</value>
  </custom_attribute>
</custom_attributes>

XML

Any fields not documented below are not supported by our Magento V2 connector, with the exception of product attributes sent via custom_attributes. Examples of where in the XML the fields should appear are shown in the samples below.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfProduct xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Product>
    <external_id>STOCK001</external_id>
    <sku>24-MB01</sku>
    <name>Joust Duffle Bag</name>
    <attribute_set_id>4</attribute_set_id>
    <price>34.00</price>
    <status>1</status>
    <visibility>4</visibility>
    <type_id>simple</type_id>
    <weight>1.5</weight>
    <extension_attributes>
      <values>
        <CatalogDataProductExtension>
          <stock_item>
            <qty>100</qty>
            <is_in_stock>true</is_in_stock>
          </stock_item>
        </CatalogDataProductExtension>
      </values>
    </extension_attributes>
    <product_links>
      <product_link>
        <sku>24-MB01</sku>
        <link_type>upsell</link_type>
        <linked_product_sku>24-MB03</linked_product_sku>
        <linked_product_type>simple</linked_product_type>
      </product_link>
    </product_links>
    <media_gallery_entries>
      <media_gallery_entry>
        <media_type>image</media_type>
        <label>Joust Duffle Bag</label>
        <position>1</position>
        <disabled>false</disabled>
        <types>
          <string>image</string>
          <string>small_image</string>
          <string>thumbnail</string>
        </types>
        <file>/m/b/mb01-blue-0.jpg</file>
      </media_gallery_entry>
    </media_gallery_entries>
    <tier_prices>
      <tier_price>
        <customer_group_id>0</customer_group_id>
        <qty>10</qty>
        <value>30.00</value>
      </tier_price>
    </tier_prices>
    <custom_attributes>
      <custom_attribute>
        <attribute_code>tax_class_id</attribute_code>
        <value>2</value>
      </custom_attribute>
      <custom_attribute>
        <attribute_code>description</attribute_code>
        <value>&lt;p&gt;The sporty Joust Duffle Bag can't be beat.&lt;/p&gt;</value>
      </custom_attribute>
      <custom_attribute lookup_option_label="true" create_new_option_label="true">
        <attribute_code>manufacturer</attribute_code>
        <value>Zynk Software</value>
      </custom_attribute>
    </custom_attributes>
  </Product>
</ArrayOfProduct>

In each of the following sections most of the XML has been omitted to make the samples easier to read. The whole structure of the ArrayOfProduct schema is used above as a reference of where fields should be in the object model.

Product

The following information can be found within the 'Product' section.

Magento Field XML Field Type Input Notes
ID id int Optional The Magento entity ID. When supplied, the product with this ID is updated
- external_id string Optional Stored in Zynk's internal DB and used to track products already imported. Required when the Prevent Reprocessing setting is enabled
SKU sku string Required Used for matching existing products when no id is supplied
Product Name name string Required
Attribute Set attribute_set_id int Required See Attribute Set
Price price* decimal Conditional
Enable Product status int Required See Status
Visibility visibility int Required See Visibility
Product Type type_id string Required Valid values are listed below
Weight weight* decimal Conditional
- store_code string Optional The store view code to send this product to, overriding the Store View Code setting on the task for this record only
- created_at DateTime Optional
- updated_at DateTime Optional
- match / matches element Optional Match an existing product on a field other than sku, see Matching Records in Magento v2
  • price* - Required for simple, virtual and downloadable products. Not required for configurable and grouped products, or bundle products with a dynamic price
  • weight* - Required for shippable product types, e.g. simple. Omit for virtual and downloadable products

  • type_id - Valid values:

Value Meaning
simple A single physical product with its own SKU
virtual A product with no physical presence, e.g. a service or warranty. Has no weight
downloadable A product delivered as one or more files, see Downloadable Product Links
configurable A parent product whose variants are chosen by attribute, see Configurable Product Options
grouped A collection of simple products presented together
bundle A customisable kit of products, see Bundle Product Options
<Product>
  <external_id>STOCK001</external_id>
  <sku>24-MB01</sku>
  <name>Joust Duffle Bag</name>
  <attribute_set_id>4</attribute_set_id>
  <price>34.00</price>
  <status>1</status>
  <visibility>4</visibility>
  <type_id>simple</type_id>
  <weight>1.5</weight>
  <store_code>default</store_code>
</Product>

Custom Attributes

Any product attribute which is not one of the elements listed above is sent as a custom attribute. This includes the standard Magento attributes description, short_description, tax_class_id, url_key, meta_title, meta_keyword, meta_description, cost and category_ids, as well as any attribute added to your own Magento installation. Use Export Product Attributes to list the attribute codes available on your store. The options for tax_class_id are listed under Tax Class.

Magento Field XML Field Type Input Notes
Attribute Code attribute_code string Required The code of the Magento attribute, e.g. tax_class_id
Value value string Required The value to set. For a select or multiselect attribute this is the option ID, unless lookup_option_label is used. Multiple option IDs for a multiselect attribute are sent as a comma separated list

The following XML attributes can be set on the custom_attribute element to look up the options of a select or multiselect attribute by their label rather than by their ID:

XML Attribute Type Input Notes
lookup_option_label bool Optional Set to true to treat the value as an option label. Zynk looks up the matching option on the attribute in Magento and sends its option ID
case_sensitive_option_lookup bool Optional Set to true to perform a case sensitive match when looking up the option label
create_new_option_label bool Optional Set to true to create the option on the attribute in Magento when no existing option matches the label
option_label_separator string Optional The character used to separate multiple option labels within a single value, for use with multiselect attributes
<custom_attributes>
  <custom_attribute>
    <attribute_code>tax_class_id</attribute_code>
    <value>2</value>
  </custom_attribute>
  <custom_attribute>
    <attribute_code>short_description</attribute_code>
    <value>Dual top handles, adjustable shoulder strap, full-length zipper.</value>
  </custom_attribute>
  <custom_attribute>
    <attribute_code>category_ids</attribute_code>
    <value>3,11</value>
  </custom_attribute>
  <custom_attribute lookup_option_label="true" create_new_option_label="true" case_sensitive_option_lookup="false">
    <attribute_code>manufacturer</attribute_code>
    <value>Zynk Software</value>
  </custom_attribute>
  <custom_attribute lookup_option_label="true" option_label_separator=";">
    <attribute_code>colours</attribute_code>
    <value>Blue;Green</value>
  </custom_attribute>
</custom_attributes>

Categories can also be assigned by name rather than by ID, using the Import Categories settings on the Import Products to Magento V2 task.

Extension Attributes

Stock levels, and the options of configurable, bundle and downloadable products, are sent within extension_attributes. Note the values and CatalogDataProductExtension elements, which are required for the contents to be read.

<Product>
  <extension_attributes>
    <values>
      <CatalogDataProductExtension>
        <!-- stock_item, configurable_product_options, configurable_product_links,
             bundle_product_options, downloadable_product_links and
             downloadable_product_samples go here -->
      </CatalogDataProductExtension>
    </values>
  </extension_attributes>
</Product>

Stock Item

Alternatively, use the Update Inventory or Import Source Items tasks to update stock levels without sending the rest of the product data.

Magento Field XML Field Type Input Notes
Quantity qty decimal Optional
Stock Status is_in_stock bool Optional
- item_id int Optional
- product_id int Optional
- website_id int Optional
- stock_id int Optional
Qty Uses Decimals is_qty_decimal bool Optional
Display Out of Stock Message show_default_notification_message bool Optional
Out-of-Stock Threshold min_qty decimal Optional Set use_config_min_qty to false to use this value
- use_config_min_qty bool Optional
Minimum Qty Allowed in Cart min_sale_qty decimal Optional Set use_config_min_sale_qty to 0 to use this value
- use_config_min_sale_qty int Optional 0 for false, 1 for true
Maximum Qty Allowed in Cart max_sale_qty decimal Optional Set use_config_max_sale_qty to false to use this value
- use_config_max_sale_qty bool Optional
Backorders backorders int Optional Valid values are listed below. Set use_config_backorders to false to use this value
- use_config_backorders bool Optional
Notify for Quantity Below notify_stock_qty decimal Optional Set use_config_notify_stock_qty to false to use this value
- use_config_notify_stock_qty bool Optional
Qty Increments qty_increments decimal Optional Set use_config_qty_increments to false to use this value
- use_config_qty_increments bool Optional
Enable Qty Increments enable_qty_increments bool Optional Set use_config_enable_qty_inc to false to use this value
- use_config_enable_qty_inc bool Optional
Manage Stock manage_stock bool Optional Set use_config_manage_stock to false to use this value
- use_config_manage_stock bool Optional
- low_stock_date string Optional
Can be Divided into Multiple Boxes for Shipping is_decimal_divided bool Optional
- stock_status_changed_auto int Optional
  • backorders - Valid values:
Value Meaning
0 No Backorders
1 Allow Qty Below 0
2 Allow Qty Below 0 and Notify Customer
<Product>
  <extension_attributes>
    <values>
      <CatalogDataProductExtension>
        <stock_item>
          <qty>100</qty>
          <is_in_stock>true</is_in_stock>
          <manage_stock>true</manage_stock>
          <use_config_manage_stock>false</use_config_manage_stock>
          <backorders>0</backorders>
          <use_config_backorders>false</use_config_backorders>
        </stock_item>
      </CatalogDataProductExtension>
    </values>
  </extension_attributes>
</Product>

Configurable Product Options

Used when type_id is configurable. The child products must already exist in Magento, must have a value set for the attribute being configured, and are normally imported with a visibility of 1.

Magento Field XML Field Type Input Notes
- configurable_product_options/configurable_product_option/id int Optional The ID of an existing option to update
Attribute configurable_product_options/configurable_product_option/attribute_id string Required The ID of the attribute the variants differ by, e.g. the ID of color. Use Export Product Attributes to find attribute IDs
Attribute Label configurable_product_options/configurable_product_option/label string Optional
Position configurable_product_options/configurable_product_option/position int Optional
- configurable_product_options/configurable_product_option/is_use_default bool Optional
- configurable_product_options/configurable_product_option/product_id int Optional
Values configurable_product_options/configurable_product_option/values/value/value_index int Required The option ID of each attribute value included in this configurable product
Associated Products configurable_product_links/int int Required The Magento entity IDs of the child products
<Product>
  <type_id>configurable</type_id>
  <extension_attributes>
    <values>
      <CatalogDataProductExtension>
        <configurable_product_options>
          <configurable_product_option>
            <attribute_id>93</attribute_id>
            <label>Colour</label>
            <position>0</position>
            <values>
              <value>
                <value_index>50</value_index>
              </value>
              <value>
                <value_index>51</value_index>
              </value>
            </values>
          </configurable_product_option>
        </configurable_product_options>
        <configurable_product_links>
          <int>101</int>
          <int>102</int>
        </configurable_product_links>
      </CatalogDataProductExtension>
    </values>
  </extension_attributes>
</Product>

Bundle Product Options

Used when type_id is bundle.

Magento Field XML Field Type Input Notes
- option_id int Optional The ID of an existing option to update
Option Title title string Required
Required required bool Optional
Input Type type string Required Valid values are select, radio, checkbox and multi
Position position int Optional
- sku string Optional The SKU of the bundle product
- product_links/product_link/id string Optional
Product product_links/product_link/sku string Required The SKU of a product included in the bundle
- product_links/product_link/option_id int Optional
Default Quantity product_links/product_link/qty decimal Optional
Position product_links/product_link/position int Optional
Is Default product_links/product_link/is_default bool Optional
Price product_links/product_link/price decimal Optional Only used when the bundle has a fixed price
Price Type product_links/product_link/price_type int Optional 0 for a fixed price, 1 for a percentage of the bundle price
User Defined Quantity product_links/product_link/can_change_quantity int Optional 0 for false, 1 for true
<Product>
  <type_id>bundle</type_id>
  <extension_attributes>
    <values>
      <CatalogDataProductExtension>
        <bundle_product_options>
          <bundle_product_option>
            <title>Choose a Bag</title>
            <type>radio</type>
            <required>true</required>
            <position>1</position>
            <sku>BUNDLE001</sku>
            <product_links>
              <product_link>
                <sku>24-MB01</sku>
                <qty>1</qty>
                <is_default>true</is_default>
                <can_change_quantity>0</can_change_quantity>
              </product_link>
            </product_links>
          </bundle_product_option>
        </bundle_product_options>
      </CatalogDataProductExtension>
    </values>
  </extension_attributes>
</Product>

Used when type_id is downloadable.

Magento Field XML Field Type Input Notes
- id int Optional The ID of an existing link to update
Title title string Required
Position sort_order int Optional
Shareable is_shareable int Optional 0 for No, 1 for Yes, 2 to use the store configuration
Price price decimal Optional
Maximum Downloads number_of_downloads int Optional 0 for unlimited
File Type link_type string Required Valid values are file and url
- link_file* string Conditional The path of a file already present in Magento
- link_file_content/file_data* string Conditional The file itself, base 64 encoded
- link_file_content/name* string Conditional The name to save the file as
Link URL link_url* string Conditional
Sample File Type sample_type string Optional Valid values are file and url
- sample_file string Optional The path of a sample file already present in Magento
- sample_file_content/file_data string Optional The sample file itself, base 64 encoded
- sample_file_content/name string Optional The name to save the sample file as
Sample URL sample_url string Optional
  • link_file*, link_file_content/file_data* - When link_type is file, send either link_file or link_file_content
  • link_file_content/name* - Required when sending link_file_content
  • link_url* - Required when link_type is url

Samples which are not tied to a link are sent in downloadable_product_samples, using the id, title, sort_order, sample_type, sample_file, sample_file_content and sample_url fields.

<Product>
  <type_id>downloadable</type_id>
  <extension_attributes>
    <values>
      <CatalogDataProductExtension>
        <downloadable_product_links>
          <downloadable_product_link>
            <title>User Manual</title>
            <link_type>url</link_type>
            <link_url>https://www.zynk.com/manual.pdf</link_url>
            <number_of_downloads>0</number_of_downloads>
            <is_shareable>2</is_shareable>
            <sort_order>1</sort_order>
          </downloadable_product_link>
        </downloadable_product_links>
        <downloadable_product_samples>
          <downloadable_product_sample>
            <title>Sample Chapter</title>
            <sample_type>url</sample_type>
            <sample_url>https://www.zynk.com/sample.pdf</sample_url>
          </downloadable_product_sample>
        </downloadable_product_samples>
      </CatalogDataProductExtension>
    </values>
  </extension_attributes>
</Product>

Related, up-sell, cross-sell and associated products.

Magento Field XML Field Type Input Notes
- sku string Required The SKU of the product being imported
Link Type link_type string Required Valid values are listed below
Linked Product linked_product_sku string Required The SKU of the product to link to. The product must already exist in Magento
- linked_product_type string Optional The type_id of the linked product, e.g. simple
- position int Optional
Default Quantity extension_attributes/qty decimal Optional Used for the child products of a grouped product
  • link_type - Valid values: related, upsell, crosssell, associated
<Product>
  <product_links>
    <product_link>
      <sku>24-MB01</sku>
      <link_type>related</link_type>
      <linked_product_sku>24-MB03</linked_product_sku>
      <linked_product_type>simple</linked_product_type>
      <position>1</position>
      <extension_attributes>
        <qty>1</qty>
      </extension_attributes>
    </product_link>
  </product_links>
</Product>

Images and videos for the product.

Magento Field XML Field Type Input Notes
- id int Optional The ID of an existing gallery entry to update
- media_type string Required Valid values are listed below
Alt Text label string Optional
Position position int Optional
Hide from Product Page disabled bool Optional
Role types/string string Optional The roles this image fills. Valid values are listed below
- file* string Conditional The path of an image already present in Magento's media directory, e.g. /m/b/mb01-blue-0.jpg
- content/base64_encoded_data* string Conditional The image itself, base 64 encoded
- content/type* string Conditional The MIME type of the image, e.g. image/png or image/jpeg
- content/name* string Conditional The name to save the image as
- unique_id string Optional Used by Zynk to identify the entry when reporting errors
- extension_attributes/video_content/media_type* string Conditional Set to external-video
Video URL extension_attributes/video_content/video_url* string Conditional
- extension_attributes/video_content/video_provider string Optional e.g. youtube or vimeo
Video Title extension_attributes/video_content/video_title string Optional
Video Description extension_attributes/video_content/video_description string Optional
- extension_attributes/video_content/video_metadata string Optional
  • file*, content/base64_encoded_data* - Send either file or content for an image entry
  • content/type*, content/name* - Required when sending content
  • extension_attributes/video_content/media_type*, extension_attributes/video_content/video_url* - Required when media_type is external-video

  • media_type - Valid values: image, external-video

  • types - Valid values: image, small_image, thumbnail, swatch_image
<Product>
  <media_gallery_entries>
    <media_gallery_entry>
      <media_type>image</media_type>
      <label>Joust Duffle Bag</label>
      <position>1</position>
      <disabled>false</disabled>
      <types>
        <string>image</string>
        <string>small_image</string>
        <string>thumbnail</string>
      </types>
      <content>
        <base64_encoded_data>iVBORw0KGgoAAAANSUhEUg==</base64_encoded_data>
        <type>image/png</type>
        <name>mb01-blue-0.png</name>
      </content>
    </media_gallery_entry>
  </media_gallery_entries>
</Product>

Tier Prices

Quantity and customer group based pricing. Alternatively, use the Import Tier Prices task to update tier prices without sending the rest of the product data.

Magento Field XML Field Type Input Notes
Customer Group customer_group_id int Required 0 is the NOT LOGGED IN group on a standard install, 32000 applies the price to all groups. Use Export Customer Groups to find your own group IDs
Quantity qty decimal Required The minimum quantity the price applies from
Price value* decimal Conditional The price to charge
Discount (%) extension_attributes/percentage_value* decimal Conditional The percentage discount to apply
Website extension_attributes/website_id int Optional 0 applies the price to all websites
  • value*, extension_attributes/percentage_value* - Send either a fixed value or a percentage_value
<Product>
  <tier_prices>
    <tier_price>
      <customer_group_id>0</customer_group_id>
      <qty>10</qty>
      <value>30.00</value>
      <extension_attributes>
        <website_id>0</website_id>
      </extension_attributes>
    </tier_price>
  </tier_prices>
</Product>

Customisable Options

Customisable options allow a customer to supply extra information, or choose from a list, when adding the product to their basket.

Magento Field XML Field Type Input Notes
- product_sku string Required The SKU of the product being imported
- option_id int Optional The ID of an existing option to update
Option Title title string Required
Option Type type string Required Valid values are listed below
Position sort_order int Optional
Required is_require bool Optional
Price price decimal Optional
Price Type price_type string Optional Valid values are fixed and percent
SKU sku string Optional
Compatible File Extensions file_extension string Optional Only used when type is file
Maximum Characters max_characters int Optional Only used when type is field or area
Maximum Image Width image_size_x int Optional Only used when type is file
Maximum Image Height image_size_y int Optional Only used when type is file
Option Title values/value/title* string Conditional
Position values/value/sort_order int Optional
Price values/value/price decimal Optional
Price Type values/value/price_type string Optional Valid values are fixed and percent
SKU values/value/sku string Optional
- values/value/option_type_id int Optional The ID of an existing option value to update
  • values/value/title* - Required for the select based option types: drop_down, radio, checkbox and multiple

  • type - Valid values: field, area, file, drop_down, radio, checkbox, multiple, date, date_time, time

<Product>
  <options>
    <option>
      <product_sku>24-MB01</product_sku>
      <title>Embroidered Name</title>
      <type>field</type>
      <is_require>false</is_require>
      <sort_order>1</sort_order>
      <price>5.00</price>
      <price_type>fixed</price_type>
      <max_characters>20</max_characters>
    </option>
    <option>
      <product_sku>24-MB01</product_sku>
      <title>Strap Colour</title>
      <type>drop_down</type>
      <is_require>true</is_require>
      <values>
        <value>
          <title>Blue</title>
          <price>0.00</price>
          <price_type>fixed</price_type>
          <sort_order>1</sort_order>
        </value>
        <value>
          <title>Green</title>
          <price>2.50</price>
          <price_type>fixed</price_type>
          <sort_order>2</sort_order>
        </value>
      </values>
    </option>
  </options>
</Product>

Errors

Records which fail to import are written to the Fail File in the same format as the input file, with the reason for the failure added in an errors element. There is no need to send this element yourself.

The name of each error tells you at which stage the record failed:

Name Meaning
Pre-Validation Zynk checked the record before sending it and found a problem, e.g. a required field is missing or a related record could not be found. The record was not sent to Magento
Prevent Reprocessing A record with the same external_id has already been imported, and the Prevent Reprocessing setting is enabled on the task
Error Magento rejected the record, or Zynk could not match the record to the data already in Magento. The description contains the message returned by Magento
Upload Error An unexpected error occurred while sending the record to Magento
<Product>
  <sku>24-MB01</sku>
  <name>Joust Duffle Bag</name>
  <errors>
    <error>
      <name>Pre-Validation</name>
      <description>price must be provided for new product</description>
    </error>
  </errors>
</Product>