Skip to main content

Updating stock in EVA using stock files

Most services in EVA can be used directly, as is the case for all services mentioned here. Despite that, you might first want to ensure the available UI in Admin Suite isn't more appropriate. In regards to stock mutations in particular, we advise checking out the Overview and mutation docs.

Small batch updates​

The UpdateStock service can be used to synchronize a full stock set using a single web service.

The service updates the sellable stock of the given products for a specified OrganizationUnitID, or when left blank, your current organization unit. Products that are not mentioned will not be modified.

Things to keep in mind

Size < 4MB Only batches smaller than 4MB are accepted by the UpdateStock service.

Timing Care for concurrency and timing issues when using this service.

Example request
{
  "OrganizationUnitID": 42,
  "Products": [
    {
        "ID": 3,
        "Quantity": 10
    },
    {
        "ID": 4,
        "Quantity": 15
    }
  ]
}

Large batch updates​

To process larger stock files from your system, we support a two step approach:

  1. Create a blob
  2. Insert the blob for processing

1. Creating a Blob​

To do so, call the StoreBlob service. This service contains a Data parameter where you can store your data. To do so, create a JSON file for your data.

Then encode this file in Base64 and use it under Data as a string value. As a response to this call, you’ll receive a Guid (the BlobID). You can see the entire process in the example requests below.

[
  {
    "ProductID": "Optional, int",
    "ProductBackendID": "Optional, string",
    "QuantityOnHand": "Required, int, value >= 0"
  },
  {
    "ProductID": "yourproductid",
    "ProductBackendID": "yourbackendid",
    "QuantityOnHand": "15"
  },
  ...
]

{
  "Category": "123",
  "OriginalName": "123",
  "MimeType": "application/json",
  "Data": "WwogICAgewogICAgICBQcm9kdWN0SUQ6IDEyMywKICAgICAgUHJvZHVjdEJhY2tlbmRJRDogIjEyMyIsCiAgICAgIFF1YW50aXR5T25IYW5kOiAxMgogICAgfSwKICAgIHsKICAgICAgUHJvZHVjdElEOiAxMjQsCiAgICAgIFByb2R1Y3RCYWNrZW5kSUQ6ICIxMjQiLAogICAgICBRdWFudGl0eU9uSGFuZDogOTUKICAgIH0sCiAgXQ==",
  "ExpireDate": "2025-06-25"
}

{
  "Guid": "bb190999-0bde-44c4-a298-b806964c32fd",
  "Url": "https://assets.hrx3h5tr.on-eva.io/blob/bb190999-0bde-44c4-a298-b806964c32fd"
}

2. Inserting your Blob for processing​

Secondly, you call the ProcessStockMutationFile service, in which you can provide the OrganizationUnitID, StockLabelID, IsFullStockMutationFile and BlobID.

  • The BlobID(Guid) you got from the previous call is required.
  • When OrganizationUnitID is not given, the OrganizationUnitID of the callers context will be used.
  • When StockLabelID is not given, the 'Sellable' stock label is used.
  • When IsFullStockMutationFile is set to true, the stock of all products that are not provided in the file will be set to 0. If set to false, only the products in the file are processed.

Bear in mind that when calling the ProcessStockMutationFile service, a task will be started within EVA to process the file. The completion time of this process depends on the amount of work that needs to be done.

Example call:

{
  "FileBlobID": "bb190999-0bde-44c4-a298-b806964c32fd",
  "IsFullStockMutationFile": false
}

Services for adjusting and moving stock​

AdjustStock​

The AdjustStock service can be used to create a (delta) stock adjustment. Delta stock adjustments don't provide a whole new stock level, they adjust an existing stock level by adding or removing a certain quantity.

This service is mainly used when new stock is 'found' or 'lost' following e.g. a cycle count in the warehouse.

This services uses relative mutations to your existing stock values in the Quantity field (e.g. '12' for adding stock or '-5' for subtracting stock). This service is not used for uploading absolute stock values.

Example call:

{
  "BackendSystemID": "123",
  "Adjustments": [
    {
      "BackendID": "123",
      "ProductBackendID": "P123",
      "OrganizationUnitID": 42,
      "StockLabelID": 1,
      "StockMutationReasonID": 3,
      "Quantity": 12,
      "Remark": "Manual stock movement"
    }
  ]
}
Admin Suite UI

As mentioned in the introduction, you might want to consider using our UI to Upload stock mutations instead.

MoveStock​

MoveStock service can be used to move stock between stock labels. The service does not 'create' or 'remove' any stock (like AdjustStock could) - it merely changes the stock label of existing stock. It is for example used when moving stock items with the sellable label to the damaged label, in case of a damage inspection.

Example request:

{
  "BackendSystemID": "123",
  "Movements": [
    {
      "BackendID": "123",
      "ProductBackendID": "P123",
      "OrganizationUnitID": 42,
      "SourceStockLabelID": 1,
      "DestinationStockLabelID": 2,
      "StockMutationReasonID": 3,
      "Quantity": 12,
      "Remark": "Manual stock movement"
    }
  ]
}

Settings relevant to moving and adjusting stock​

Not all stock can be moved via the MoveStock service by default. It's hardcoded to include the Clearance, Demo and Damaged labels along with all of the labels mentioned in the Stock:SellableSourceStockLabels setting - which itself defaults to Sellable. This means you can expect to be able to move these 4 mentioned labels, unless you configure this differently.

The setting Returns:AlwaysReturnToSellable ties in with this as well, since it looks at the same Stock:SellableSourceStockLabels setting + Damaged for its values. In the same vein: if you want returned stock to not pop up in your stock feeds as sellable, first move it to a stock label which is explicitly not sellable, such as Demo. This is useful in a scenario where you might want to inspect any returned orders, before making them available to sell again.

Syncing external stock mutations​

When syncing external stock mutations, all stock of the related products is updated in EVA immediately. However, in addition to storing them in the EVA database, the mutations are also copied to a separate CosmosDB database. This allows for better performance when viewing and interacting with these stock mutations in the EVA UIs.

The sync with the CosmosDB is based on the following task: EVA.Azure.StockMutations.SyncStockMutationsTask. In this task you can set the synchronization interval, to make it run hourly for example.

As you can see, the dates in the example below can be set as wide as you like.