Products Onboarding Cheatsheet

This reference provides a high-level overview of the core concepts of product onboarding to serve as a reference during development.

Product Structure Highlights

The Zalando Catalog is the master database for all products for sale through Zalando.
A product is one salable item, including all of its options and variants, such as one model of shoe, including all size and color options.
During product submission, products are defined in JSON files by a three-tier hierarchy of attributes:
- product_model
- product_config
- product_simple

For more information, see Understanding Products.

Outline of Product Onboarding

Check if EAN is already present in Zalando Catalog

Use the Products API to check if the EAN already exists in the Zalando Catalog.
If so, proceed to "Onboarding Existing Products."
If not, proceed to "Onboarding New Products"

For more information, see Checking if a Product Exists in the Zalando Catalog.

Onboarding Existing Products

Map your unique product identifiers to the product EAN.
You may then set available stock and price.

For more information, see Onboarding Existing Products.

Onboarding New Products

Get a product outline for your product type, which provides an enumeration of the attributes required.
Use the Product Submission JSON Template as a starting point for constructing a product submission JSON for one product and all its variants.
Use the Product Attributes API to get information about each attribute and complete the submission JSON.
Use the Product Submissions API to submit the JSON.
Use your Product Status Report (PSR) to monitor the validation status of your product submissions.
Once a product is added to the Zalando Catalog, you may set available stock and price.
If necessary, make any required corrections and use the Product Submissions API to resubmit the JSON.

Warning

When you have submitted the product for (a) correcting mistakes or (b) by adding new Variants/Sizes to the Product, you must always resubmit the entire Product including all previous parts

For more information, see Onboarding New Products.

Product Images

All products in the Zalando Catalog have one and only one set of associated images.
To submit images, host them on any publicly-available URL such as Dropbox and submit the URLs in the media attribute of the product_config.

For more information, see Images in "Onboarding New Products."

Product Onboarding APIs

Type	Path	Main Uses	API
GET	/merchants/{merchant_id}/outlines	Return available outlines for the merchant.	Products
GET	/merchants/{merchant_id}/outlines/{outline_label}	Return specific outline by product type.	Products
GET	/merchants/{merchant_id}/attribute-types/{type_label}	Return the schema for the specified attributes type.	Product Attributes
GET	/merchants/{merchant_id}/attribute-types/{type_label}/attributes	Return all attributes of the specified attribute type.	Product Attributes
GET	/merchants/{merchant_id}/attribute-types/{type_label}/attributes/{attribute_label}	Return the specified attribute of the specified attribute type.	Product Attributes
POST	/merchants/{merchant_id}/product-submissions	Post a single product submission JSON.	Product Submissions API

Example Calls

Note: all requests require authentication.

Return all outlines

Returns a (large) JSON with all available product outlines.

GET /merchants/{merchant_id}/outlines

Return a specific outlines

To get the outline for sandals:

GET /merchants/{merchant_id}/outlines/sandals

Return the schema for the specified attributes type

Learn more about an attribute type such as target_genders.

GET /merchants/{merchant_id}/attribute-types/target_genders

Example response:

{
    "cardinality": "many",
    "definition": {
        "type": "StringDefinition"
    },
    "description": {
        "en": "Target genders"
    },
    "label": "target_genders",
    "name": {
        "en": "target genders"
    },
    "type_variants": [],
    "usage": "reference_by_label"
}

For more information on parsing this response, see Attribute Type Schema below.

Return all attributes of the specified attribute type

Learn more about the attributes of a specified attribute type such as target_genders.

If the attribute value must be one from a list of possible options (that is, the usage value is reference_by_label), then this call will return all valid values for the attribute type.

GET /merchants/{merchant_id}/attribute-types/target_genders/attributes

Example response:

{
    "items": [
        {
            "label": "target_gender_male",
            "name": {
                "en": "target gender male"
            },
            "value": {
                "string": "target_gender_male"
            }
        },
        {
            "label": "target_gender_female",
            "name": {
                "en": "target gender female"
            },
            "value": {
                "string": "target_gender_female"
            }
        }
    ]
}

Return specified attribute of specified attribute type

Similar to above, but returns only the specified attribute of the specified attribute type.

GET /merchants/{merchant_id}/attribute-types/target_genders/attributes/target_gender_male

Example response:

{
    "label": "target_gender_male",
    "name": {
        "en": "target gender male"
    },
    "value": {
        "string": "target_gender_male"
    }
}

Attribute Type Schema

Field	Description
cardinality	Indicates if one or many responses are allowed.
definition	The expected data type of the value.
description	Any additional information about the attribute type.
label	Other calls may reference the attribute type by referencing the value of this field.
name	A human-readable description of the field for use in referencing the attribute type in front ends or UIs.
type_variants	Some attribute types have variants that are independently defined, such as color_code.primary and color_code.secondary. An outline may only allow some of the possible variants.
usage	Either `literal` or `reference_by_label`. For literal, enter a value. For reference_by_label, the specification takes a `label` value to specify the value.

Size Attributes

The following chart indicates which values in the size attribute enumeration contains the values you must submit in your JSON.

Value	Where it is defined in the size attributes enumeration
`size_group.size`	For any size group where `dimension.type` = `size`, the value of `label`
`size_group.length`	For any size group where `dimension.type` = `length`, the value of `label`
`size_code.size`	For any size group where `dimension.type` = `size`, the value of `supplier_size`
`size_code.length`	For any size group where `dimension.type` = `length`, the value of `supplier_size`

For more information, see Sizes in "Onboarding New Products".

Glossary of Key Terms

Attribute type: One type of information about a product, such as name or size_code.
Attribute value: A value specified for an attribute type.
Attribute type attribute: An attribute of an attribute type.
Attribute schema: The data model for any attribute or type attribute.
Outline: A product outline is a JSON that enumerates all of the mandatory and optional attributes that are used to define a product of a particular type.
Product: In the Merchant Center, a product is an article for sale, such as a model of shoes or a watch, along with all of its options and variants.
Product identifiers: Unique IDs that each partner creates and maintains which map to an EAN. Each EAN must have three corresponding product identifier, which correspond to the three attribute tiers.
Product Status Report (PSR): A report available through the zDirect UI that gives real-time information on the status of product submissions.
Product submission JSON: A JSON file used to define all mandatory and any desired optional product attributes for a product during product submission. PSRs are available through the zDirect UI.
Silhouette: See "Outline".
Tier (of attributes): The attributes in product outlines and product submission JSONs are organized into three tiers, the product_model, product_config, and product_simple tiers. By organizing product attributes into a hierarchy, we can define attributes that are shared by many individual EANs only once.

Sample Outline

The following is an example of a valid outline for the sandals model.

{
  "label": "sandals",
  "tiers": {
    "model": {
      "optional_types": [],
      "mandatory_types": [
        "target_age_groups",
        "target_genders",
        "name",
        "brand_code",
        "size_group"
      ],
      "restricted_attributes": []
    },
    "config": {
      "optional_types": [
        "condition",
        "color_code.secondary",
        "color_code.tertiary",
        "width",
        "shape",
        "decksohle",
        "material.filling",
        "futter",
        "heel_form",
        "insole_technology",
        "material_construction",
        "non_textile_but_animal_parts",
        "occasion",
        "padding_type",
        "pattern",
        "shoe_detail",
        "shoe_toecap",
        "shoe_width",
        "size_fits",
        "sole_material",
        "sport_qualities",
        "sport_shoe_details",
        "sport_shoe_insole",
        "sport_shoe_outer_sole",
        "sport_shoe_outer_sole_technology",
        "sport_type",
        "upper_material",
        "washing_instructions"
      ],
      "mandatory_types": [
        "color_code.primary",
        "media",
        "season_code",
        "supplier_color",
        "description"
      ],
      "restricted_attributes": [
        {
          "type": {
            "label": "washing_instructions",
            "version": "1.0.0"
          },
          "values": [
            "washing_instructions_4106",
            "washing_instructions_4107",
            "washing_instructions_6999",
            "washing_instructions_7858"
          ]
        },
        ...
      ]
    },
    "simple": {
      "optional_types": [
        "metric.heel_height",
        "metric.platform_height",
        "metric.schafthoehe",
        "metric.schaftweite"
      ],
      "mandatory_types": [
        "ean",
        "size_codes"
      ],
      "restricted_attributes": []
    }
}

As you can see washing_instructions only allows a subset of values, therefore, all other washing_instructions values fetched via Product Attributes API and not included in restricted_attributes will result in a subsequent rejection.

Product Submission JSON Template

This is the basic structure of a product submission JSON. The actual mandatory attributes will vary, depending on which product outline you are using.

{
  "outline":"$MODEL_LABEL",
  "product_model":{
    "merchant_product_model_id":"$YOUR_MERCHANT_PRODUCT_MODEL_ID",
    "product_model_attributes":{
      "name":"$MODEL_NAME",
      "brand_code":"$MODEL_BAND_CODE",
      ...
    },
    "product_configs":[
      {
        "merchant_product_config_id":"$YOUR_MERCHANT_PRODUCT_CONFIG_ID",
        "product_config_attributes":{
          "color_code.primary":"$CONFIG_COLOR_CODE.PRIMARY",
          "media":[
            {
              "media_path":"URL",
              "media_sort_key":"$SORT_KEY"
            },
            {
              "media_path":"URL",
              "media_sort_key":"$SORT_KEY"
            },
            {
              "media_path":"URL",
              "media_sort_key":"$SORT_KEY"
            }
          ],
          "season_code":"fs20",
          "supplier_color":"white",
          ...
        },
        "product_simples":[
          {
            "merchant_product_simple_id":"$YOUR_MERCHANT_PRODUCT_SIMPLE_ID",
            "product_simple_attributes":{
              "ean":"$EAN",
              ...
            }
          }
        ]
      }
    ]
  }
}

Sample Product Submission JSON

The following is an example of a valid product submission JSON payload using the sandals outline. For more information, see the Product Submissions API OpenAPI Reference.

{
  "outline": "sandals",
  "product_model": {
    "merchant_product_model_id": "MODEL_ID_123",
    "product_model_attributes": {
      "name": "AIR FORCE SANDALS 1 '07 LV8 UTILITY",
      "brand_code": "ns1",
      "size_group": {
        "size": "4MU1000E2A"
      },
      "target_genders": [
        "target_gender_male",
        "target_gender_female"
      ],
      "target_age_groups": [
        "target_age_group_adult"
      ]
    },
    "product_configs": [
      {
        "merchant_product_config_id": "7b077fc4-fde3-47d4-8b25-97af8792",
        "product_config_attributes": {
          "color_code.primary": "001",
          "description": {
            "en": "Nice sandals",
            "de": "Gute Sandale",
            "ru": "Отличные сандали"
          },
          "material.upper_material_clothing": [
            {
              "material_code": "li",
              "material_percentage": 97.5
            },
            {
              "material_code": "el",
              "material_percentage": 2.5
            }
          ],
          "media": [
            {
              "media_path": "https://hosting_of_your_choice/media/7b077fc4-fde3-47d4-8b25-97af8792/pic-1.jpg",
              "media_sort_key": 1
            },
            {
              "media_path": "https://hosting_of_your_choice/media/7b077fc4-fde3-47d4-8b25-97af8792/pic-2.jpg",
              "media_sort_key": 2
            }
          ],
          "washing_instructions": "washing_instructions_4106",
          "season_code": "fs20",
          "supplier_color": "white"
        },
        "product_simples": [
          {
            "merchant_product_simple_id": "white-shoes-1105AA",
            "product_simple_attributes": {
              "ean": "9780679762881",
              "size_codes": {
                "size": "42"
              }
            }
          },
          {
            "merchant_product_simple_id": "white-shoes-2216BB",
            "product_simple_attributes": {
              "ean": "9780679763992",
              "size_codes": {
                "size": "44.5"
              }
            }
          }
        ]
      },
      {
        "merchant_product_config_id": "7b077fc4-fde3-47d4-8b25-97af8793",
        "product_config_attributes": {
          "color_code.primary": "608",
          "description": {
            "en": "Nice sandals",
            "de": "Gute Sandale",
            "ru": "Отличные сандали"
          },
          "material": [
            {
              "material_code": "li",
              "material_percentage": 87.5
            },
            {
              "material_code": "el",
              "material_percentage": 12.5
            }
          ],
          "media": [
            {
              "media_path": "https://hosting_of_your_choice/media/7b077fc4-fde3-47d4-8b25-97af8793/pic-1.jpg",
              "media_sort_key": 1
            },
            {
              "media_path": "https://hosting_of_your_choice/media/7b077fc4-fde3-47d4-8b25-97af8793/pic-2.jpg",
              "media_sort_key": 2
            }
          ],
          "season_code": "fs20",
          "supplier_color": "mint"
        },
        "product_simples": [
          {
            "merchant_product_simple_id": "mint-shoes-3326CC",
            "product_simple_attributes": {
              "ean": "9813752182012",
              "size_codes": {
                "size": "44.5"
              }
            }
          }
        ]
      }
    ]
  }
}

Additional Resources

API References: Information on scopes, rate limiting, and sandbox behavior, and an OpenAPI reference for each API.

Contact Support