Product Status Report API
Overview
The Product Status Report API (or PSR API) provides read access to Product Status Report data. Query the PSR API to get up-to-date information about your products, such as validation status, current price, and available stock.
Possible data lags
The data served by the PSR API is near real-time and usually lags only by a few minutes. However, this lag may sometimes increase to a few hours for short periods.
PSR data is also available through the Article Listing in zDirect UI, but you must have a Merchant Partner account to access that portal.
PSR API specification
- PSR API reference: Information on scopes, rate limiting, and sandbox behavior.
- PSR API tutorial: Instructions on how to use the interactive documentation to construct a request.
Unlike other zDirect APIs, the PSR API is not a RESTful API. Instead, it uses the GraphQL framework. For more information, we recommend the Official GraphQL Documentation or Introduction to GraphQL from GitHub.
To make requests, POST a JSON specifying your request parameters to the API. The target URL for all PSR API requests is:
POST https://api.merchants.zalando.com/graphql
GraphQL Clients
We recommend using GraphQL freeware clients during development, such as:
- Insomnia: This is our recommendation. Examples in this documentation use Insomnia version 7.1.0 for Windows.
- Postman API Client: Postman v7.2 and later have GraphQL support.
These clients allow you to easily send queries directly to the API, which can be useful for testing or for manually retrieving data.
They can also help you understand how to write GraphQL queries for the zDirect API, so you can programmatically construct requests with UIs or in application code. This article will explain how to create and execute GraphQL queries within Insomnia.
Using Insomnia to View the PSR API Documentation
As an introduction, we will walk through sending a basic request to the PSR API. Once you have done so, you can use Insomnia to generate an interactive reference for the API.
Create a Request
- In the upper-left, click on the plus icon and selection New Request.
- Enter a name such as "PSR Sample Query" in the dialog box. Select "POST" for the request type, and "GraphQL Query" for the body type.
- Click "Create".
- In the top bar, enter the target URL: https://api.merchants.zalando.com/graphql
- Add authorization information.
- Use the zDirect Authentication API to generate an access token as described in Authentication.
- In the Auth pull-down tab on the Insomnia client, select "Bearer Token"
- Enter the access token in the TOKEN field.
- Click the Header tab and verify that Content-Type is set to "application/json".
You are now ready to send a request.
Select the GraphQL tab and copy-and-paste the following JSON into the window:
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, status_clusters: [REJECTED]
, limit: 10
}) {
items {
product_configs {
product_simples {
ean
status { status_detail_code }
}
}
}
}
}
}
Be sure to enter one or more actual Merchant IDs in the merchant_ids field. Click the Send button to the right of the URL. The PSR API will return a JSON reply.
Launch the Interactive Documentation
In the upper-right of the window where you entered your sample query, click the Schema button, and select Refresh Schema. The Show Documentation option should now be selectable. Click it.
This will launch interactive documentation that describes the various query options for the PSR API. For a simple tutorial that shows how to use the interactive documentation to construct a query, see Tutorial: Using the PSR API.
Using the PSR API
In the PSR API design, we have used the same attribute names that we use for product submission whenever possible, but they do not always correspond exactly. Refer to the interactive documentation for a detailed enumeration of all available attributes and values.
Key PSR Query Fields
Bellow are some of the most important PSR API query fields:
| Option | Description |
|---|---|
| query.psr.countries | Lists available countries for the merchant. |
| query.psr.brands | Lists available brands for the merchant. |
| query.psr.seasons | Lists available seasons for the merchant. |
| query.psr.product_status_codes | Lists product status codes. |
| query.psr.product_models | Searches for product models, including all their configs, simples, and offers. |
For a full list of query options, refer to the interactive documentation.
Product Data and Specific Offer Data
A product can have no offers or multiple offers, with each offer available on a different sales channel (such as zalando.de or zalando.co.uk). Each offer has its own status, which is separate from the overall product status and can be queried independently.
The product_models query returns product data, including model, config, and simple tier details such as name, IDs, size group,
outline, target gender, and more. For an example of a product model, see the Product Status Example.
Offer data is included in the simple tier and contains information such as price, stock, and more. For an example of a product offer status,
see the Offer Status Example.
A product's status can be found in the status parameter within product_simples. Once a product is submitted, it will have a status,
but it may not necessarily have an offer status. The product status represents the overall state of the product:
- If the product is in the onboarding process, it indicates whether the product is under review or has been rejected.
- If the product has been created, it reflects the combined status across all offers.
Within product_simples, the optional offers data provides a list of all sales channels where the product is available.
Each offer's status can be retrieved from the offer_status parameter. The offer status represents:
- Whether the product is live or missing essential data (such as price or stock) for that specific sales channel.
- Whether the product has an offer blocker for that sales channel.
Overall product status information
In general, the product status information consolidates both the product and offer statuses. The product status consists of the following fields:
| Status Field | Explanation |
|---|---|
| status_detail_code | A unique code representing each status. |
| status_cluster | The broad category the status belongs to within the product lifecycle. Possible values: "REJECTED", "INREVIEW", "BLOCKED", or "LIVE". |
| status_level | Indicates the product tier level associated with the status. Possible values: "simple", "config", or "model". |
| short_description | A brief, headline-like summary of the status. |
| description | The most important field — provides a detailed explanation of the status code and may include guidance on how to resolve issues. |
| status_urls | Optional business documentation links on resolving status-related issues. Dedicated URLs are provided for the Partner Program and Connected Retail. |
Warning
To help users understand status information, we recommend including at least the status_detail_code, description, and status_urls, depending on the business model.
GraphQL gives you a power to get all this data in one call. But sometimes it makes sense to perform separate calls not to overwhelm the system (e.g. UI). For example, you can load all the relevant product data and EANs first, and then get the offer-specific data with subsequent requests.
For a complete list of returned data, see the interactive documentation. For an overview of the product data structure, refer to Understanding Products.
Pagination
All pagination is performed at the product model level.
Recommended pagination limit
We recommend using pagination limit of 10 models for better results, regarding response latency.
Pagination Example
We specify that we want to receive only the first 5 models and specify that we expect the cursor field to be present in the response:
{
psr {
product_models(input: {
merchant_ids: ["YOUR_MERCHANT_ID"],
limit: 5
}) {
cursor
items {
zalando_product_model_id
merchant_product_model_id
product_configs {
product_simples {
ean
}
}
}
}
}
}
As a response, the cursor value for the next entries will be present. Here we can see a LABWE-238498 cursor value:
{
"data": {
"psr": {
"product_models": {
"cursor": "LABWE-238498",
"items": [
{
...
We can add this cursor to the original request to get the second page and the same process can be repeated to retrieve the following pages, if existent.
{
psr {
product_models(input: {
merchant_ids: ["YOUR_MERCHANT_ID"],
limit: 5,
cursor: "LABWE-238498"
}) {
cursor
items {
zalando_product_model_id
merchant_product_model_id
product_configs {
product_simples {
ean
}
}
}
}
}
}
Termination
You have consumed all pages once you receive an empty cursor.
Example Queries
PSR API provides you information about every product you have submitted. This information will help you understand where your product is in the entire Product Lifecycle. In these examples, you find a summary of what we provide.
Validation Example 1
The following query will return the EAN and validation status code of all rejected product simples for a specified product model. Queries like this are useful during product submission validation.
Note that you need to provide real values for PARTNER_MODEL_ID and YOUR_MERCHANT_ID.
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, status_clusters: [REJECTED]
, limit: 10
, search_value: "YOUR_PARTNER_MODEL_ID"
}) {
items {
product_configs {
product_simples {
ean
status {
status_detail_code
description {
en
}
}
}
}
}
}
}
}
You will receive a reply similar to the following example:
{
"data": {
"psr": {
"product_models": {
"items": [
{
"product_configs": [
{
"product_simples": [
{
"ean": "4351261305360",
"status": [
{
"status_detail_code": "PSERR_110",
"description": {
"en": "Article rejected, because the size grid is not included in the Partner Master Data. Please reach out to our Partner Care team."
}
}
]
},
{
"ean": "4351261305361",
"status": [
{
"status_detail_code": "PSERR_110",
"description": {
"en": "Article rejected, because the size grid is not included in the Partner Master Data. Please reach out to our Partner Care team."
}
}
]
}
]
}
]
}
]
}
}
}
}
Validation Example 2
This query will return the primary, secondary and tertiary colors in english as well as
size_group.size, size_group.length, and validation status code of all products with a
specified product status, product model, and merchant id.
Such query can help identify product submissions that were rejected.
Note that you need to provide real values for PARTNER_MODEL_ID, MERCHANT_ID, and STATUS_DETAIL_CODE.
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, status_detail_codes: ["STATUS_DETAIL_CODE"]
, search_value: "YOUR_PARTNER_MODEL_ID"
, limit: 10
}) {
items {
size_group { size length }
product_configs {
color_primary { code localized { en } }
color_secondary { code localized { en } }
color_tertiary { code localized { en } }
product_simples {
ean
size_codes { size length }
status { status_detail_code }
}
}
}
}
}
}
You will receive a reply similar to the following example:
{
"data": {
"psr": {
"product_models": {
"items": [
{
"size_group": [
{
"size": "2FKO000E3A",
"length": null
}
],
"product_configs": [
{
"color_primary": {
"code": "001",
"localized": {
"en": "yellow"
}
},
"color_secondary": {
"code": "002",
"localized": {
"en": "blue"
}
},
"color_tertiary": {
"code": "003",
"localized": {
"en": "green"
}
},
"product_simples": [
{
"ean": "4351261305362",
"size_codes": {
"size": "36",
"length": null
},
"status": [
{
"status_detail_code": "STATUS_DETAIL_CODE"
}
]
}
]
}
]
},
{
"size_group": [
{
"size": "2FKO000E3A",
"length": null
}
],
"product_configs": [
{
"color_primary": {
"code": "802",
"localized": {
"en": "black"
}
},
"color_secondary": null,
"color_tertiary": null,
"product_simples": [
{
"ean": "4351261305370",
"size_codes": {
"size": "36",
"length": null
},
"status": [
{
"status_detail_code": "STATUS_DETAIL_CODE"
}
]
},
{
"ean": "4351261305371",
"size_codes": {
"size": "38",
"length": null
},
"status": [
{
"status_detail_code": "STATUS_DETAIL_CODE"
}
]
}
]
}
]
}
]
}
}
}
}
Product Status Example
The following request will return the EANs of all product simples along with their validation status codes for all live products specific to a Merchant ID.
Such data is useful to learn more about which products are selling and being back-filled, and how they are offered to customers.
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, status_clusters: [LIVE]
, country_codes: ["de"]
, limit: 10
}) {
items {
product_configs {
product_simples {
ean
status {
status_detail_code
status_cluster
short_description { en }
}
}
}
}
}
}
}
You will receive a reply similar to the following example:
{
"data":{
"psr":{
"product_models":{
"items":[
{
"product_configs":[
{
"product_simples":[
{
"ean":"4351261305360",
"status":[
{
"status_detail_code":"ZAON_01",
"status_cluster": "LIVE",
"short_description": {
"en": "You are selling this EAN"
}
},
{
"status_detail_code":"ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
]
},
{
"ean":"4351261305361",
"status":[
{
"status_detail_code":"ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
]
},
{
"ean":"4351261305362",
"status":[
{
"status_detail_code":"ZAON_01",
"status_cluster": "LIVE",
"short_description": {
"en": "You are selling this EAN"
}
}
]
}
]
}
]
}
]
}
}
}
}
You can see multiple status codes for a simple with EAN - 4351261305360. The status means that the product is created, but not fully live yet. If you want to dive deeper, take a look at the offers section using the following Offer Status Example.
Offer Status Example
To get more detailed information about offer status, use product_models query, as in this example:
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, eans: ["4351261305360", "4351261305361"]
, status_clusters: [LIVE]
, country_codes: ["de"]
, limit: 10
}) {
items {
product_configs {
product_simples {
ean
zalando_product_simple_id
offers {
offer_status {
status_detail_code
status_cluster
short_description { en }
}
}
}
}
}
}
}
}
With this query, you will receive a response containing the status code and cluster for each offer that matches the query with a short description in English. For example:
{
"data": {
"psr": {
"product_models": {
"items": [
{
"product_configs": [
{
"product_simples": [
{
"ean": "4351261305360",
"zalando_product_simple_id": "VE042D04C-A60000M000",
"offers": [
{
"offer_status": [
{
"status_detail_code": "ZAON_01",
"status_cluster": "LIVE",
"short_description": {
"en": "You are selling this EAN"
}
}
]
},
{
"offer_status": [
{
"status_detail_code": "ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
]
}
]
},
{
"ean": "4351261305361",
"zalando_product_simple_id": "VE042D04C-A6100XS000",
"offers": [
{
"offer_status": [
{
"status_detail_code": "ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
]
}
]
}
]
}
]
}
]
}
}
}
}
Offer Stock and Price Example
To get more detailed information about offer's price and stock, use product_models query, as in this example:
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, eans: ["4351261305360", "4351261305361"]
, status_clusters: [LIVE]
, country_codes: ["de"]
, limit: 10
}) {
items {
product_configs {
product_simples {
ean
zalando_product_simple_id
offers {
country { code localized { en } }
stock { amount }
price {
regular_price { amount currency }
discounted_price { amount currency }
}
fulfillment_type
}
}
}
}
}
}
}
Price data shows the current values applied in a given sales channel. New price updates can take some time to be shown in the store, and they are updated here afterwards. More info about price updates can be found under Manage Prices.
Stock data shows the current stock levels that can be sold in a given sales channel. For ZFS stock (Zalando-fulfilled), however, this
stock number does not reflect the physical count of items in the warehouse and more info can be found on the
ZFS Stock API. The stock type can be identified by the fulfillment_type information:
- For ZFS stock, the
fulfillment_typefield will haveZFSfulfillment type value. - For partner fulfilled stock, the
fulfillment_typefield will havePARTNER_FULFILLMENTfulfillment type value.
An overall offers data, containing different sales channels with price, stock, status, and fulfillment_type,
can be seen in the following example response:
{
"data": {
"psr": {
"product_models": {
"items": [
{
"product_configs": [
{
"product_simples": [
{
"ean": "4351261305360",
"zalando_product_simple_id": "VE042D04C-A60000M000",
"offers": [
{
"offer_status": [
{
"status_detail_code": "ZAON_01",
"status_cluster": "LIVE",
"short_description": {
"en": "You are selling this EAN"
}
}
],
"country": {
"code": "DE",
"localized": {
"en": "Germany"
}
},
"stock": {
"amount": 42
},
"price": {
"regular_price": {
"amount": 69.95,
"currency": "EUR"
},
"discounted_price": {
"amount": 39.95,
"currency": "EUR"
}
},
"fulfillment_type": "ZFS"
},
{
"offer_status": [
{
"status_detail_code": "ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
],
"country": {
"code": "NL",
"localized": {
"en": "Netherlands"
}
},
"stock": {
"amount": 420
},
"price": null,
"fulfillment_type": "ZFS"
}
]
},
{
"ean": "4351261305361",
"zalando_product_simple_id": "VE042D04C-A6100XS000",
"offers": [
{
"offer_status": [
{
"status_detail_code": "ZANOP_01",
"status_cluster": "BLOCKED",
"short_description": {
"en": "Price is missing"
}
}
],
"country": {
"code": "DE",
"localized": {
"en": "Germany"
}
},
"stock": {
"amount": 21
},
"price": null,
"fulfillment_type": "PARTNER_FULFILLMENT"
}
]
}
]
}
]
}
]
}
}
}
}
For more information, see the preceding Product Data and Specific Offer Data.
Sustainability Certificate
Use the product_models.items query below to retrieve a product sustainability certificate information.
Additionally, you can retrieve products with or without approved sustainability certificate by using
the optional boolean has_approved_sustainability_related_claim query filter.
{
psr {
product_models(
input:
{ merchant_ids: ["YOUR_MERCHANT_ID"]
, has_approved_sustainability_related_claim: true
, limit: 10
}) {
items {
product_configs {
certificate {
certificate_info
certificate_test_institute
certificate_approval_number
certification_tier
product_component {
variant
certified_percentage
}
has_approved_sustainability_related_claim
}
product_simples {
ean
zalando_product_simple_id
}
}
}
}
}
}
An example response showing the certificate information:
{
"data": {
"psr": {
"product_models": {
"items": [
{
"product_configs": [
{
"certificate": {
"certificate_info": "home_labels_5111",
"certificate_test_institute": "Ecocert Greenlife SAS",
"certificate_approval_number": "EGL/000000/GOTS/000000/0",
"certification_tier": "brand",
"product_component": {
"variant": "non_material_variant:full_product",
"certified_percentage": 95.0
},
"has_approved_sustainability_related_claim": true
},
"product_simples": [
{
"ean": "5701586978572",
"zalando_product_simple_id": "CX742I007-Q12000L000"
}
]
}
]
}
]
}
}
}
}