Browsing products

Products in procurement are stored internally using 3 different objects to allow aggregation, filtering & search mechanisms that would not be possible with a single list. Articles group the products together which have the same name/description/manufacturer and core attributes; variants uniquely identify the individual product you wish to order; and skus represent the different orderable combinations of that product (e.g. the packaging, size, whether it comes on a pallet, etc).

As a consumer of this API, you can query for variants, and ultimately will purchase "skus". It isn't possible to directly query for article data, however they are included in the variants response to support aggregation.

All queries for variants begin with a search. In the following example, we're looking for a sheet_substrate (paper) product and we'd like to match any of the names/descriptions against the string "Magno":

GET /api/v2/variants?type=sheet_substrate&query=Magno
Accept: application/json
Accept-Language: en-US

HTTP 200 OK
{
  "results": [
    {
      "id": "0167d323-57ac-52dc-9c81-c7514f8eab12",
      "summary": "PS1 - Premium Coated, 880 × 630 mm, 90 g/㎡, short",
      "article": { ... },
      "skus": [
        {
          "amount: 1,
          "amount_in_base_unit": 1,
          "environmental_certification": "FSC Mix Credit",
          "order_number": "ABCDE1234",
          "palletized": false,
          "unit": "sheet",
        }
      ]
    },
    ...
  ],
  "available_filters": [
    {
      "name": "article_finish",
      "label": "Finish",
      "total_count": 12,
      "options": [
        { "value": "GLOSSY", "count": 1 },
        { "value": "MATT", "count": 3 }
      ]
    },
    ...
  ]
}

Like all Zaikio APIs, this API is internationalised. If you specify an Accept-Language (opens new window) header, we will try to provide summary and label fields using your preferred languages (or those of your customers). If you get error responses, they should also be translated.

Also included in the response is a list of available_filters, which represent the list of possible ways that the result set could be filtered. Each of these can be appended as query parameters, under the filters[] namespace, to subsequent requests, allowing fine-grained filtering and searching as needed by your application.

For example, if we wanted to only find products which had the finish "GLOSSY":

GET /api/v2/variants?type=sheet_substrate&filters[article_finish]=GLOSSY

You can also select multiple filter values by joining them with a comma. For example to find products where the finish was either "GLOSSY" or "MATT":

GET /api/v2/variants?type=sheet_substrate&filters[article_finish]=GLOSSY,MATT

Please note that ?type is always required, and you must also specify either a ?query or at least one ?filter argument. Over time, we will add more product types, and document them using our API schema. We recommend that:

• If you are working in a specific business domain using a subset of types, or your software is written in a strongly-typed language which cannot handle changing response fields, you should always restrict the ?type on your search to known values (e.g. ?type=ink,envelope).

• If you are able to handle new API response structures, and don't need to restrict the values for your customers, you can use the special ?type=all parameter to search everything.

We recommend that you don't cache or store the data that you get back from querying variants, where possible. This is because suppliers can update the information at any time (including providing more attributes, refining the accuracy of existing data, etc). Our aim is that this API remains fast and available, so you should be able to safely re-query this before e.g. rendering a user interface.

Once your customer has found the variants they are looking for, they should then tell us more about how much they need, and when/where they want it delivered. We call these instructions a material requirement, and that's where we'll go next.