Tutorial: Using the PSR API

Overview

In this tutorial, we will walk through how to use the PSR API interactive documentation to construct a query using the Insomnia GraphQL client.

We will write a GraphQL query that will get the EAN and current stock levels of all product simples that we currently sell in the UK for a specified Merchant ID.

These instructions are based on Insomnia version 7.1.0 for Windows.

Getting Started

Prerequisites

Before using this tutorial:

  1. Read through the page Product Status Report API, if you have not already done so.
  2. Install the Insomnia GraphQL client as explained in our PSR API guide.
  3. Be sure you understand how to get access tokens for the zDirect APIs explained in our Authentication guide.

Authorization

  1. Use the zDirect Authentication API to generate an access token as described in Authentication.
  2. In the Auth tab on the Insomnia client, select "Bearer Token"
  3. Enter your access token in the TOKEN field.

Writing the Query

Let's take this example query as our starting point:

{
  psr {
    product_models(
      input:
      { merchant_ids: [""]
      , status_clusters: []
      , status_detail_codes: []
      , season_codes: []
      , brand_codes: []
      , country_codes: []
      , has_approved_sustainability_related_claim = null
      , limit: 10
      , search_value: ""
      }) {
      items {
        product_configs {
          product_simples {
            ean
          }
        }
      }
    }
  }
}

In this query, the request parameters are specified in the product_models field, and the data we want back is specified in the items field.

In product_models.input, we will specify that this search will return data for products that are:

  1. sold by a specific Merchant ID,
  2. currently live, and
  3. available for sale in the UK.

In the items field, we will specify that we want to get:

  1. the EAN, and
  2. the amount of available stock.

Open the Interactive Documentation

Begin by opening the documentation. To do so, you will need to have sent a valid and authenticated query to the PSR API at least once. If you have not already done so, follow the instructions in the section Using Insomnia to View the PSR API Documentation of the PSR API Guide.

Note

If you have previously sent a query using Insomnia, you may need to click "Refresh Schema" before the "Show Documentation" option is selectable.

Specify Filters

The landing page of the documentation looks like this:

We can see in the Root Types enumeration that there are two available types of request:

  1. Query
  2. Mutation

Queries return a JSON, and mutations are only for internal usage.

Let's choose Query for our root type. Click on Root Types > query > Query to open the Fields page.

In the Fields page, we can see that all queries pertain to Product Status Reports, so we have only one option. Click on Fields > psr > PsrQuery! to continue.

Now we see available fields such as product_models, countries, brands, and so forth.

We want to specify that our query should get products only for sale in the UK and with a status of Live. Both of these values are specified at the product model level, so select product_models.ModelsInputType! to view the input options for the product model tier.

Now we see the following fields:

Our fields of interest here are country_codes, status_clusters, and merchant_ids.

Country Codes

Looking at country_codes, we find this field takes a two-letter value for country. To get product data for products for sale in the UK, enter the following value:

      , country_codes: ["uk"]

Status Clusters

Looking at status_clusters, we see that we enter an all-caps status value as an argument. To get results only for products that are live, enter the following value:

      , status_clusters: [LIVE]

Merchant ID

The entry for merchant_ids tells us to specify the ID with a string. Enter one or more Merchant ID in the following field:

      { merchant_ids: ["YOUR_MERCHANT_ID"]

Insomnia Auto-Complete

One extremely useful feature that Insomnia provides is auto-complete when you are authoring GraphQL queries.

Let's go back to the status_clusters example above. Say you were not sure what values are legal for that attribute. Instead of entering a value, enter Ctrl + space, and you will see the following pop-up:

For any key with pre-defined values, Insomnia will provide you with available options in this way.

Specify Return Data

Now we will specify that we want to get the EAN and stock for each of the products that meets the filter criteria we previously set.

Stock levels and EAN are set per product simple, so this data must be specified in the product_simples field. For more information on these values, click on product_simples > Simple!.

EAN

Looking at ean, we see that the value is returned as a string. Nothing additional is needed than what we already have in our sample:

      items {
        product_configs {
          product_simples {
            ean

Offers

Available stock and price are defined by offers, so click the field Offer! to see what options are available:

We want to specify stock, so click on the Stock! field:

To get current stock levels back per EAN, we must specify that we want the amount as in this example:

      items {
        product_configs {
          product_simples {
            ean
            offers {
              stock { amount }

Auto-Complete Again

As with status_clusters, we can use Insomnia auto-complete to display legal values for stock attributes by entering Ctrl + space in the input field:

Complete Query

We now have everything we need for our complete query, which will return all available stock per EAN for items currently sold by a specified Merchant ID in the UK:

{
  psr {
    product_models(
      input:
      { merchant_ids: ["YOUR_MERCHANT_ID"]
      , status_clusters: [LIVE]
      , season_codes: []
      , brand_codes: []
      , country_codes: ["uk"]
      , limit: 10
      , search_value: ""
      }) {
      items {
        product_configs {
          product_simples {
            ean
            offers {
              stock { amount }
            }
          }
        }
      }
    }
  }
}

Note that in this example the limit field is set to its default value of 10. This will limit the number of returned results to the first 10 product_models in the system.

Go ahead and try running this query by clicking Send. Be sure that you have a valid access token entered in Bearer > TOKEN.

We can see in the timeline tab on the right hand side of Insomnia what has really happened. The payload of the HTTP request will look like this:

{"query":"{\n  psr {\n    product_models(\n      input:\n      { merchant_ids: [\"YOUR_MERCHANT_ID\"]\n      , status_clusters: [LIVE]\n      , season_codes: []\n      , brand_codes: []\n      , country_codes: [\"uk\"]\n      , limit: 10\n      , search_value: \"\"\n      }) {\n      items {\n        product_configs {\n          product_simples {\n            ean\n            offers {\n              stock { amount }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n\n"}

If you are not using a GraphQL client library, such as when sending commands from a simple REST client or curl, then you must encode the query as a JSON string as shown in the example above .

Contact Support