Onboarding Existing Products

If you have used the Products API to verify that a product you wish to sell already exists in the Zalando Catalog, you may associate your own product identifiers with the corresponding EAN for each product variant or option.

Associating your Product Identifiers with an EAN

For more information about product identifiers, see the Product Identifiers and Product Mapping section of our Products Onboarding Overview.


The zDirect API requires OAuth 2.0 authentication for all API calls. Use the Authentication API to generate access tokens as described in the Authentication section.

Create a JSON Payload

Create a file called skus.json that defines your product_simple_id, product_config_id, and product_model_id for a single EAN,

  "merchant_product_simple_id": "{YOUR_PROD_SIMPLE_ID}",
  "merchant_product_config_id": "{YOUR_PROD_CONFIG_ID}",
  "merchant_product_model_id": "{YOUR_PROD_MODEL_ID}"

This is a typical example:

  "merchant_product_simple_id": "white-shoes-1105AA",
  "merchant_product_config_id": "7b077fc4-fde3-47d4-8b25-97af8793e13d",
  "merchant_product_model_id": "MODEL_ID_123"

We recommend to associate all three identifiers to create an explicit relationship between ids at all tiers. But you need to supply at least merchant_product_simple_id. Here is an example of a minimum required payload:

  "merchant_product_simple_id": "white-shoes-1105AA"


Use the zDirect Products API to submit your JSON to Zalando:

PUT /merchants/{merchant_id}/products/identifiers/{ean}

A typical httpie command for a product with the EAN 9780679762881123 looks like this:

http PUT \
/9780679762881123" \
"Authorization:Bearer $YOUR_ACCESS_TOKEN" \
< skus.json


If the request is successful, you will receive the following http reply:

204 No Content

After receiving a positive reply, you may update stocks and prices for this EAN. For more information, see Manage Prices and Manage Stock.


Once you have mapped your product IDs to an existing product, they will not be shown in your Product Status Report until you update either their stock or their price.

If your JSON is not valid or the EAN does not exist, you will receive a HTTP 400 reply with details about the failure. For example, if you omit the mandatory merchant_product_simple_id field, you will receive the following error:

HTTP/1.1 400 Bad Request

Error in $: When parsing the record ProductAssociation of type
Lemur.ArticleTypes.Inbound.ProductAssociation the key
merchant_product_simple_id was not present.

Sandbox Testing

The Products API supports sandbox mode. Data submitted by write operations in the sandbox environment are not persisted or propagated, but the automated validation applied on submission is the same as in the production environment.

For more information, see the Sandbox section of the Products API Overview in our API Reference.

Additional Resources

  • Products API Reference: Information on scopes, rate limiting, and sandbox behavior, and an OpenAPI reference for the Products API.
Contact Support