Skip to main content

Getting stock data from EVA

You can get all stock data you need in your e-commerce storefront (or ERP system for that matter) straight from EVA by means of so-called stock feeds. This page will guide you through you the process of setting up the feed and explain how you can check stock levels in real-time.

Setting up a stock feed​

To get stock data out of EVA on a regular basis, we have a StockFeed task available. By configuring this task in in Suite's Scheduled tasks, you can create a periodic stock_[name].json file that contains all stock data for a particular OUset. You can then tell your e-commerce front end to retrieve this file periodically from our blobstorage, creating a periodic update of your total e-commerce stock.

With the settings in the stock feed you can determine what kind of stock you would like to see. This may be the OUs own stock, the stock of all OUs which can deliver to your OU, or both. In some cases external stock will be relevant while disregarding your own stock, such as when you want a feed of your Ecommerce stock. Other times, when you for example want a feed of the stock in your warehouse, only your own stock will be relevant while external stock is not at all.

Creating the feed​

To set up this task:

  • navigate to Scheduled tasks in Admin Suite's Control room.
  • Select EVA.Primer.Stock.Stockfeed2(note: StockFeed1 is an older version, used for stock of a single OU)
  • Set a schedule using a cronjob to define the interval by which the feed should be updated
  • Take a look at all the Settings that appear and set those you need to true

Requesting the feed​

The name of the stock feed file is always prefixed by 'stock_' and this name is what we use for this feed. If no name is supplied, it will default to OrganizationUnitSetID for which the stock feed is created. All feeds in EVA are available on GET https://EVA_ENDPOINT/feed/stock_name.json?authorization=AuthorizationKey

Example:

GET https://api.academy.dev.eva-online.cloud/feed/stock_name.json?authorization=0F93A7E96670071023E7396C4A927918AC817EA1B42

  {
    "ID": 29973,
    "BackendID": "TU410980",
    "CustomID": "1100354",
    "OrganizationUnit": {
      "ID": 626,
      "BackendID": "CONSUMER_NL"
    },
    "Stock": {
      "Internal": {
        "OnHand": 0,
        "Available": 0
      },
      "External": {
        "OnHand": 1000,
        "Available": 926
      }
    }
  }
  ...
Calculating committed stock

By calculating the difference between OnHand and Available stock, you can find the committed stock.

Negative stock values in stock feed​

If you want negative stock values to be shown in the stock feed, include the parameter IncludeNegativeAvailability (which defaults to false). If set to true then negative stock is included in the feed. Note that zero stock still isn't - unless ExcludeOutOfStock is set to false.

Combine this with IncludeNegativeAvailabilityAsZero to turn negative quantities into 0.

Headless possibilities​

For a real-time overview of the stock levels for particular products (i.e. on your Product Detail Page), we have the GetProductAvailability service which instantly gives you the real-time stock level. This is especially helpful if you don't want to run total stock updates often or have tight stock margins. It is also used to get real-time data of stock in stores, which you can display on your product page for Click & Collect purposes.

This request contains the desired product's ProductID. Which type of ID is specified at ProductID can be determined at the EVA-IDs-Mode header.

This request can contain as many products as you like.

Below you can see an example of the GetProductAvailability request, with it's mandatory properties. The second tab shows you how to request OU specific information only, while the last one shows you a typical response.

{
  "Products": [{
    "ID" : 14
  }],
  "Options" : {
    "ProductAvailabilityDetails" : {  } // Leave empty to request details for ALL OUs and products
  }
}

Stock updates via event exports​

There are several stock related event export targets available, which allow you to get (close to) real-time updates about your stock depending on the target and its type.

StockMutation: Created​

You can see this particular stock event in action in the Stock event flow - deep dive.

Note that the order of events published is NOT guaranteed to be sequential: always validate this before overwriting your absolute stock levels.

ProductAvailability - Changed​

This event target will update you on all availability changes, but needs to be specifically enabled by specifying OU IDs in the ExportProductAvailabilityChangesForOrganizationUnits setting.

Put in the ID of your Webshop OU for example and you'll get events about the availability for that OU, which will take into account the supplier relationships/allocations for the Webshop.

Mind that these events are not sent straight away. Only after changes to stock/commitments have buffered for 5 minutes, will availability be calculated for all changed products - and then sent as an event. The results contained in the event are based on the current data, meaning that if a product that started at 0, gets +1, -2, +3 during those 5 minutes will get a single event with available = 2.

Note that this does not guarantee an actual change from a previously reported event. Events are raised when something could have affected availability, but it might not result in an actual change and EVA does not keep track of previously reported states to compare against.

Example of the information available in the event export data

{
  "UID": "00000000-0000-0000-0000-000000000000",
  "CreationTime": "2023-02-18T23:03:43.525383Z",
  "TimeZone": null,
  "Target": "ProductAvailability",
  "EventType": "changed",
  "Identifier": "1", // Product ID
  "BackendID": null,
  "BackendSystemID": null,
  "Region": null,
  "Data": {
    "OrganizationUnitID": 6,
    "OrganizationUnitBackendID": "EVA_TEST_SUITE_WEB_SHOP",
    "ProductID": 1,
    "ProductBackendID": "PRODUCT_1",
    "SupplierQuantityAvailable": 9,
    "SupplierQuantityCommitted": 1,
    "SupplierQuantityOnHand": 10, 
    "QuantityOnHand": 0,
    "QuantityCommitted": 0,
    "QuantityAvailable": 0,
    "SupplierAvailabilityDate": "2023-02-18T00:00:00Z",  
    "AvailabilityDate": null
  },
  "Attempt": 1
}

Some additional details about the Quantity fields contained in Data:

Supplier-QuantityAvailable/Committed/OnHand:
The respective quantity that is the sum of all the Webshop’s suppliers, for example a warehouse. If you set this up to listen to webshop availability events, these are likely the most relevant fields.

QuantityOnHand/Available/Committed:
The quantity that the OU has own stock for. If you set this up to listen to warehouse availability events, you probably want to know about the own stock of the warehouse.

(Supplier)AvailabilityDate:
The date on which the OU (or supplier in case of SupplierAvailabilityDate) is expected to have stock.

  • If it has stock right now for a normal product, it returns the current date.
  • If it expects a future PO, but there is no current stock, it returns the time the PO is expected to be delivered.
  • If it’s a manufactured product with capacity plans, it’s the date on which the stock is expected to be produced.