Product Onboarding API Overview

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

Note

This API is currently in developing mode, and will be made generally available in the future.

Sync and Async Mode

The POST /partners/{business_partner_id}/products endpoint supports two processing modes:

  • Synchronous (sync): the request is validated and processed immediately, and the response reflects the final processing result. See Synchronous API for details.
  • Asynchronous (async): the request only goes through basic payload validation before being accepted; the actual processing happens afterwards, and the result is delivered via the Product Reporting API, Submission Endpoint, keyed by submission_id. See Asynchronous API for details.

To select the mode, set the X-API-Mode header on your request:

X-API-Mode header Mode
sync Synchronous
(omitted) Asynchronous (default)

If the header is omitted, the API defaults to asynchronous mode.

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.

Note

For media submission guidelines and Sandbox behavior, see Product Onboarding API Best Practices.

Synchronous API

In synchronous mode, article updates submitted via POST /partners/{business_partner_id}/products are applied immediately, and the response reflects the final processing result with immediate feedback (200 OK on success, 400 Bad Request on failure, with an error description).

Note

Media is handled differently: the media schema is validated synchronously as part of the request, but the actual media enrichment (downloading and applying the submitted media) is always applied asynchronously, regardless of the selected mode. See Submitting media for details.

Asynchronous API

Note

This behavior is planned and not yet active in production. The endpoint below is the same one described above (POST /partners/{business_partner_id}/products); this section documents how it will behave once the asynchronous flow is rolled out. See Sync and Async Mode for how to select this mode.

The API retains the POST /partners/{business_partner_id}/products endpoint. Prior to accepting a partner submission, the API performs basic payload validation:

  • Structure validation: The request must conform to the standard model/config/simple hierarchy, requiring at least one node structure (which may be empty).
  • EAN validation: Every simple node must include a valid 13-digit EAN.
  • merchant_model_id is present.
  • At least one attribute from any tier level is present.

If validation fails, the API responds immediately with a 400 Bad Request status code and an error description, using the same error response body as the synchronous flow described above. These initial validation failures are not reported to the Product Reporting API, Submission Endpoint.

The API does not allow concurrent processing of submissions with the same merchant_model_id for the same business partner. If a submission for that combination is already being processed, the API responds with a 409 Conflict status code. Retry the submission once the in-progress one has finished processing.

When all validations pass, the API returns a submission_id and processes the submission asynchronously. The result of this asynchronous processing is made available to partners via the Product Reporting API, Submission Endpoint, keyed by submission_id.

The minimal request for submission processing looks like this:

{
  "product_model": {
    "merchant_model_id": "ABC-123-DEF",
    "product_model_attributes": {
    },
    "product_configs": [
      {
        "product_config_attributes": {
          "color_code.primary": "red"
        },
        "product_simples": [
          {
            "product_simple_attributes": {
              "gtin": 5233232112240
            }
          }
        ]
      }
    ]
  }
}

The successful response, with a 201 status code:

{
  "submission_id": "796291fa-ad77-43c5-8985-7a9e2d49cf3b"
}

Additional Resources

Contact Support