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, including validation status, current price, available stock, and much more.

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 sometime increase to a few hours for short periods.

Some products will not be shown

If you just mapped your product IDs to an existing product and didn't set neither stock nor price, these products will not be shown in your Product Status Report until you update either their stock or their price.

To make requests, POST a JSON specifying your request parameters to the API.

PSR data is also available through the zDirect UI, but you must have a Merchant Partner account to access that portal.

GraphQL Endpoint

The target URL for all PSR API requests is:

POST https://api.merchants.zalando.com/graphql

GraphQL

Unlike other zDirect APIs, the PSR API is not a RESTful API. Instead, it uses the GraphQL framework.

GraphQL offers a flexible framework for making detailed queries without writing cumbersome requests with many parameters. It also provides interactive documentation that makes it easy to explore.

For more information, we recommend the Official GraphQL Documentation or Introduction to GraphQL from GitHub.

GraphQL Clients

We recommend using one of the excellent GraphQL freeware clients that are available for use during development, such as:

  • Insomnia: This is our recommendation of choice. Examples in this documentation use Insomnia.
  • Postman API Client: Postman v. 7.2 and later add support GraphQL. Also excellent.

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.

Using Insomnia to View the PSR API Documentation

Getting Started

Once you have installed the Insomnia client, you may wish to review the following sections of their documentation:

As an introduction to Insomnia, we will walk through sending a basic GraphQL request to the PSR API. Once you have done so, you can use Insomnia to generate an interactive reference for the API.

The following instructions are based on Insomnia version 7.1.0 for Windows.

Create a GraphQL Request

  1. In the upper-left, click on the plus icon and selection New Request.
  2. 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.
  3. Click "Create."
  4. In the top bar, enter the following URL: https://api.merchants.zalando.com/graphql
  5. Add authorization information.
    1. Use the zDirect Authentication API to generate an access token as described in Authentication.
    2. In the Auth pull-down tab on the Insomnia client, select "Bearer Token"
    3. Enter the access token in the TOKEN field.
  6. 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]
      , season_codes: []
      , brand_codes: []
      , country_codes: []
      , 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 as shown below:

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.

Using the Interactive Documentation

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.

Major PSR Query Fields

The following table shows some of the most important PSR API query fields:

Option Description
query.psr.countries Get list of countries available to merchant
query.psr.brands Get list of brands available to merchant
query.psr.seasons Get list of seasons available to merchant
query.psr.product_status_codes Get list of product status code
query.psr.product_models Search for product models. Complete product structure: model with all the configs, simples, and offers

For more information about available query options, see the interactive documentation.

Overall Product Data and Specific Offer Data

The product_models query returns Product data that includes model, config, and simple information, such as name, IDs, size group, outline, target gender, and more. For an example of a Product Model request and response, see the following Product Status Example.

Simple tier contains status. It's an overall status of the product:

  • If the product is not fully created, shows the rejection or review status of the product.
  • If the product was created, shows the combined status across all the offers.

Simple tier also contains optional offers. Offer is a sales-channel-specific information, such as price, stock, and status. The offer status is the most relevant status for the Sales Channel:

  • If the product is not fully created, shows the rejection or review status of the whole product.
  • If the product was created, shows the specific status for the offer (Sales Channel).

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 an example of divided requests and responses, see the following Product Status Example and Offer Status Example.

For a complete list of returned data, see the interactive documentation.

For an overview on the product data structure, see Understanding Products.

Pagination

All pagination is performed at the product model level.

Pagination Example

We specify that 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: ["2c3b1592-c504-45d4-9df0-10c9ecd5fe5b"],
      status_clusters: [],
      status_detail_codes: [],
      season_codes: [],
      brand_codes: [],
      country_codes: [],
      limit: 5,
      eans: []
    }) {
    cursor
    items {
      zalando_product_model_id
      merchant_product_model_id
      product_configs {
        product_simples {
          ean
        }
      }
    }
    }
  }
}

Here we can see that the response contains the cursor LABWE-238498:

{
  "data": {
    "psr": {
      "product_models": {
        "cursor": "LABWE-238498",
        "items": [
          {
...

We can add this cursor to the original request to get the second page.

{
   psr {
    product_models(input: {
      merchant_ids: ["2c3b1592-c504-45d4-9df0-10c9ecd5fe5b"],
      status_clusters: [],
      status_detail_codes: [],
      season_codes: [],
      brand_codes: [],
      country_codes: [],
      limit: 5,
      cursor: "LABWE-238498",
      eans: []
    }) {
    cursor
    items {
      zalando_product_model_id
      merchant_product_model_id
      product_configs {
        product_simples {
          ean
        }
      }
    }
    }
  }
}

Termination

You have consumed all pages once you receive fewer models than you specified in limit.

Example Queries

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]
      , season_codes: []
      , brand_codes: []
      , country_codes: []
      , limit: 10
      , search_value: "YOUR_PARTNER_MODEL_ID"
      }) {
      items {
        product_configs {
          product_simples {
            ean
            status { status_detail_code }
          }
        }
      }
    }
  }
}

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"
                      }
                    ]
                  },
                  {
                    "ean": "4351261305361",
                    "status": [
                      {
                        "status_detail_code": "PSERR_110"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

Validation Example 2

This query will return the primary color (in English), size_group.size, size_group.length, and validation status code of all products with a specified product status and for a specified product model, for a specific Merchant ID.

This kind of 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_clusters: []
      , status_detail_codes: ["STATUS_DETAIL_CODE"]
      , season_codes: []
      , brand_codes: []
      , country_codes: []
      , search_value: "YOUR_PARTNER_MODEL_ID"
      , limit: 10
      }) {
      items {
        size_group { size length }
        product_configs {
          color_primary { 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": "917",
                  "localized": {
                    "en": "multi-coloured"
                  }
                },
                "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"
                  }
                },
                "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 code for all live products for a specified Merchant ID.

This kind of 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]
      , season_codes: []
      , brand_codes: []
      , country_codes: ["de"]
      , limit: 10
      }) {
      items {
        product_configs {
          product_simples {
            ean
            status { status_detail_code status_cluster }
          }
        }
      }
    }
  }
}

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"
                      },
                      {
                        "status_detail_code":"ZANOP_01",
                        "status_cluster": "BLOCKED"
                      }
                    ]
                  },
                  {
                    "ean":"4351261305361",
                    "status":[
                      {
                        "status_detail_code":"ZANOP_01",
                        "status_cluster": "BLOCKED"
                      }
                    ]
                  },
                  {
                    "ean":"4351261305362",
                    "status":[
                      {
                        "status_detail_code":"ZAON_01",
                        "status_cluster": "BLOCKED"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

You can see multiple status codes for a simple with 4351261305360 ean. 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. For an example, see the following Offer Status Example.

Offer Status Example

To get more detailed information about offer status, 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]
      , season_codes: []
      , brand_codes: []
      , 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 }
              }
              country { code localized { en } }
              stock { amount }
              price {
                regular_price { amount currency }
                discounted_price { amount currency }
              }
            }
          }
        }
      }
    }
  }
}

offers contain sales-channel-specific information, such as price, stock, status, and more, as illustrated in the following example reply:

{
  "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"
                          }
                        }
                      },
                      {
                        "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
                      }
                    ]
                  },
                  {
                    "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
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  }
}

For more information, see the preceding Overall Product Data and Specific Offer Data.

Additional Resources

Contact Support