Product Onboarding API Overview

The Product Onboarding API is used for product onboarding process in the Zalando Catalog.

Note

This API is in pilot mode for wholesale partners, and will be made generally available in the future. Please contact your integration manager if you are interested in participating in the pilot program.

Product Onboarding API Scopes

To use the Product Onboarding API, your client must have the product-onboarding-service/write scope.

Rate Limiting

Each app may only make the following number of requests per second:

Environment req/sec
production 20
sandbox 20

For more information, see Rate Limiting.

Sandbox Behavior

The Sandbox is a dedicated environment where you can validate your integration with the Product Onboarding API before sending real product data to production. In the Sandbox: Your requests go through the same API schema validation and OAuth2 token authorization as production. Your requests are not validated against real product data rules (no duplicate detection, no material/logistics/compliance checks, no GTIN lookups). Instead, the Sandbox returns predictable, controllable responses so you can build and test your error-handling logic. No data is persisted and nothing is sent downstream - you can submit the same request as many times as you like.

How to Trigger a Success or a Failure

The Sandbox inspects the values you send in your request. This gives you full control over what response you get back, without needing any special headers or configuration:

  • Submit normal-looking values -> you get back a SUCCESS response.
  • Include the word INVALID (case-insensitive) anywhere in the value of any attribute, at any level of the payload (model, config, or simple) -> that attribute is reported back as a validation error, and the overall response becomes a FAILURE.

You can combine this with any number of attributes, at any tier, to simulate single or multiple validation errors in one request.

Example 1 - Success

Request:

curl -X POST https://api-sandbox.merchants.zalando.com/partners/{business_partner_id}/products \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "X-Flow-ID: my-test-flow-001" \
  -d '{
    "product_model": {
      "product_model_attributes": {
        "supplier_article_name": "Sample Product"
      },
      "product_configs": [
        {
          "product_config_attributes": {
            "supplier_article_code": "SAMPLE-001",
            "supplier_color_description": "Black"
          },
          "product_simples": [
            {
              "product_simple_attributes": {
                "gtin": "5233232112240"
              }
            }
          ]
        }
      ]
    }
  }'

Response - 200 OK:

{
  "title": "SUCCESS",
  "status": 200,
  "detail": "The product data has been successfully processed.",
  "flow_id": "my-test-flow-001",
  "body_warnings": null
}

Example 2 - Single Attribute Failure

Change one attribute's value to contain INVALID:

Request:

curl -X POST https://api-sandbox.merchants.zalando.com/partners/{business_partner_id}/products \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "X-Flow-ID: my-test-flow-002" \
  -d '{
    "product_model": {
      "product_model_attributes": {
        "supplier_article_name": "Sample Product"
      },
      "product_configs": [
        {
          "product_config_attributes": {
            "supplier_article_code": "SAMPLE-001",
            "supplier_color_description": "Black",
            "certificate": {
              "certificate_info": "Test INVALID Info"
            }
          },
          "product_simples": [
            {
              "product_simple_attributes": {
                "gtin": "5233232112240"
              }
            }
          ]
        }
      ]
    }
  }'

Response - 400 Bad Request:

{
  "title": "FAILURE",
  "status": 400,
  "detail": "The product data haven't been updated.",
  "flow_id": "my-test-flow-002",
  "body_warnings": [
    {
      "path": "product_model/product_configs/0/product_config_attributes/certificate",
      "tier": "config",
      "attribute": "certificate",
      "message": "Invalid value detected: '{certificate_info=Test INVALID Info}'"
    }
  ]
}

Example 3 - Multiple Failures Across Different Levels

You can put INVALID in attributes at the model, config, and simple level in a single request to get multiple warnings back at once:

Request:

curl -X POST https://api-sandbox.merchants.zalando.com/partners/{business_partner_id}/products \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "X-Flow-ID: my-test-flow-003" \
  -d '{
    "product_model": {
      "product_model_attributes": {
        "supplier_article_name": "Product INVALID Name"
      },
      "product_configs": [
        {
          "product_config_attributes": {
            "supplier_article_code": "SAMPLE-001",
            "supplier_color_description": "Black",
            "country_of_origin": "Country INVALID",
            "material.upper_material_back": [
              {
                "material_percentage": 50,
                "material_code": "INVALID Material"
              }
            ]
          },
          "product_simples": [
            {
              "product_simple_attributes": {
                "gtin": "5233232112240",
                "eu_address": "Address INVALID EU"
              }
            }
          ]
        }
      ]
    }
  }'

Response - 400 Bad Request:

{
  "title": "FAILURE",
  "status": 400,
  "detail": "The product data haven't been updated.",
  "flow_id": "my-test-flow-003",
  "body_warnings": [
    {
      "path": "product_model/product_model_attributes/supplier_article_name",
      "tier": "model",
      "attribute": "supplier_article_name",
      "message": "Invalid value detected: 'Product INVALID Name'"
    },
    {
      "path": "product_model/product_configs/0/product_config_attributes/country_of_origin",
      "tier": "config",
      "attribute": "country_of_origin",
      "message": "Invalid value detected: 'Country INVALID'"
    },
    {
      "path": "product_model/product_configs/0/product_config_attributes/material.upper_material_back",
      "tier": "config",
      "attribute": "material.upper_material_back",
      "message": "Invalid value detected: '[{material_percentage=50.0, material_code=INVALID Material}]'"
    },
    {
      "path": "product_model/product_configs/0/product_simples/0/product_simple_attributes/eu_address",
      "tier": "simple",
      "attribute": "eu_address",
      "message": "Invalid value detected: 'Address INVALID EU'"
    }
  ]
}

Additional Resources

Contact Support