The following changes will be made to the error responses of the Merchant Product Submission API
In addition to errors, the Merchant Product Submission API responses will now also contain warnings. Whereas errors
continue to cause submissions to be rejected (e.g. "ean" is mandatory for each simple), warnings are for information
purposes. An example of a warning case could be an issue with any optional attribute (e.g. "certificate" is supplied but
is given the wrong structure).
→ Impact: Prior to this change, warning cases would have been omitted without explanation. With this release, a warning
will inform of such a case, which gives you the chance of fixing the optional attribute and ensuring it gets included
for your article post fix.
Examples of API Responses with new warnings (right side):
Example 1: Response contains validation errors and warnings:
| Current Behaviour |
Post Update Behavior |
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
[
{
"actual": "Undefined",
"expected": "array",
"path": "product_model/product_model_attributes/target_genders"
}
]
],
"code": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
{
"title": "Bad Request",
"detail": "Bad Request: validation errors found",
"body_errors": [
{
"attribute": "target_genders",
"message": "target_genders is missing from model attributes",
"path": "/product_model/product_model_attributes",
"reason": "MISSING_ATTRIBUTE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#missing_attribute"
"tier": "model"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
Example 2: Response contains no validation errors but a warning:
| Current Behaviour |
Post Update Behavior |
|
|
{
"title": "Success",
"detail": "Success with warnings",
"body_warnings": [
{
"attribute": "occasion",
"tier": "config",
"path": "/product_model/product_configs[0]/product_config_attributes/occasion",
"message": "'Coloured' is not a valid value for occasion in outline low_shoe",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"status": 200,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
The response field "code" will be replaced with the "status" as was declared originally in the API spec.
Change Example:
| Current Behaviour |
Post Update Behavior |
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
{
"attribute": "occasion",
"tier": "config",
"path": "product_model/product_configs[0]/product_config_attributes/occasion",
"message": "'Coloured' is not a valid value for occasion in outline low_shoe",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"code": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
{
"attribute": "occasion",
"tier": "config",
"path": "/product_model/product_configs[0]/product_config_attributes/occasion",
"message": "'Coloured' is not a valid value for occasion in outline low_shoe",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
Error Messages will be restructured for better readability and contain the following new elements:
- Attribute: calls out the attribute_label which caused the error
- Message: a detailed description of what caused the error
- Path: helps locate the error within the submission, following the logical structure of a submission e.g. in the second
example below, the path "/product_model/product_configs[0]/product_simples[3]/product_simple_attributes/ean" indicates
that the issues lies with the attribute “EAN” which is located at simple level.
- Tier: the level at which the error is located - can be model/ config or simple.
- Reference: Links to further documentation that helps resolve the error.
→ Impact: This more human-readable error structure will help locate, understand and hence resolve errors faster.
Change Examples
Example 1: Error due to target_gender incorrect
Given the following submission body, where the specified value for target_genders is incorrect:
{
"outline": "bag",
"product_model": {
"merchant_product_model_id": "some model id",
"product_model_attributes": {
"target_genders": [
"target_gender_male;target_gender_female"
]
}
}
}
| Current Behaviour |
Post Update Behavior |
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
{
"error": "Invalid gender: target_gender_male;target_gender_female",
"path": "0"
},
{
"error": "Invalid gender: target_gender_male;target_gender_female",
"path": "1"
},
{
"error": "Invalid gender: target_gender_male;target_gender_female",
"path": "2"
},
{
"error": "Invalid gender: target_gender_male;target_gender_female",
"path": "3"
},
{
"error": "Invalid gender: target_gender_male;target_gender_female",
"path": "4"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
{
"title": "Bad Request",
"detail": "Bad Request: validation errors found",
"body_errors": [
{
"attribute": "target_genders",
"tier": "model",
"path": "/product_model/product_model_attributes/target_genders",
"message": "'target_gender_male;target_gender_female' is not a valid value for target_genders in outline bag",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
Example 2: Error due to duplicate EANs
| Current Behaviour |
Post Update Behavior |
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
{
"offending_ids": [
"8445497420559"
],
"error_description": "Submission contains duplicate eans within the same model"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
{
"title": "Bad Request",
"detail": "Bad Request: validation errors found",
"body_errors": [
{
"attribute": "ean",
"tier": "simple",
"path": "[/product_model/product_configs[0]/product_simples[3]/product_simple_attributes/ean, /product_model/product_configs[0]/product_simples[4]/product_simple_attributes/ean]",
"message": "same ean 8445497420559 found in multiple simples",
"reason": "DUPLICATE_IDENTIFIERS",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#duplicate_identifiers"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
The value in the error path field will from now on be specified in JsonPointer format, which means it will start
with '/' (whereas before it did not appear at the start).
| Current Behaviour |
Post Update Behavior |
{
"title": "Bad Request",
"detail": "Wrong body format",
"body_errors": [
{
"attribute": "occasion",
"tier": "config",
"path": "/product_model/product_configs[0]/product_config_attributes/occasion",
"message": "'Coloured' is not a valid value for occasion in outline low_shoe",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"code": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
{
"title": "Bad Request",
"detail": "Bad Request",
"body_errors": [
{
"attribute": "occasion",
"tier": "config",
"path": "/product_model/product_configs[0]/product_config_attributes/occasion",
"message": "'Coloured' is not a valid value for occasion in outline low_shoe",
"reason": "UNSUPPORTED_VALUE",
"reference": "https://developers.merchants.zalando.com/docs/product-submission-validation.html#unsupported_value"
}
],
"status": 400,
"contact": "support-onboarding@zalando.de",
"flow_id": "some-flow-id"
}
|
Currently, an error message is returned if any of the following is missing from a request body, but not if an empty
string is supplied.
- outline
- merchant_product_model_id
- merchant_product_config_id
- merchant_product_simple_id
After this change, empty strings will be rejected, because the identifiers require a string of at least one character.
→ Impact: Currently, if an empty string is supplied, the API would let this submission “pass” but the article would then
be rejected a few minutes later with a PSERR Error. With the January 2025 release, the API will no longer let such a submission pass, which will help identify such issues sooner.
Currently, a partner can attempt a submission, for any outline, and this will be accepted initially by the Merchant
Product Submission API, however the product will be rejected and a PSERR error will be associated with the product and
reported in zDirect Article Listing.
After this change…
→ Impact: A submission for an outline that is not applicable for the partner, will cause an error from the Merchant
Product Submission API.
Currently, the Merchant Product Submission API accepts a submission, if it contains an invalid GTIN-13 barcode value
for "ean", however the product will be rejected and a PSERR error will be associated with the product and reported in
zDirect Article Listing.
After this change…
→ Impact: a submission with invalid values for "EAN" field, will cause an error from the Merchant Product Submission
API.
Contact Support