POST /StockMutations

GENERAL INFORMATION

Purpose

This endpoint is used for sharing the mutations of stock on a location/SKU level.

How the data is used

The stock mutations determine the current stock on hand, but can also be used to determine the stock on hand in the past.

The ability to determine the stock on hand in the past makes this dataset mandatory if you want us to be able to do a backtest. If there are no mutations in the source system, the backtest becomes impossible. If there are only stock mutations available for the locations where Wallie needs to create predictions for (the selling locations), this is also enough for the backtest. Only stock mutations available for the warehouse(s) will also make the backtest impossible.

For daily operational use it is also mandatory of course, unless you do not have mutations in the source system and go with the POST /Stock implementation to share your stock information.

Best practices

1. We recommend to send us the stock mutations as fast as possible, so the Wair platform always has the most accurate stock when creating the replenishments/redistributions.

2. If you do not have mutations, then you can switch implement POST /Stock instead. As mentioned above, the backtest becomes impossible.

3. We need the stock information for all locations. See this page of the POST /Locations for a detailed explanation on the different types of locations.

4. If you send us the stock mutations, the following logic must always apply; at any given point of time the sum of the mutations for each location/SKU sent to Wair, needs to reflect the stock on hand in the source system. So make sure to share all stock mutations. This includes, but is not limited to, purchases, transfers, sales, customer/supplier returns, stock counts, distributions, replenishments etc.

5. To ensure the logic point 3 applies, we need all stock mutations dating back to the beginning, because this is the only way that the stock mutations will reflect the actual stock on hand. And yes, we know, this is a very large dataset

6. In case you did a partial cleanup of your stock mutations in the past, and the logic of point 3 does not apply to the remaining mutations, you can either:

   a. Send the end stock of the day from which you decided to delete the mutations, if you preserved this somewhere

   b. Calculate the end stock from current stock level and all the mutations and send the end stock as a mutation or as a snapshot to the POST /Stock endpoint. Note; this is complex and error prone so avoid if possible.

7. Allocations or reservations (e.g., placing a weborder that has not been fulfilled yet) are not considered stock mutations. A mutation only occurs once the physical/administrative action has been executed.

8. We ask for a document type, if you do not have this in your source system you can use code 98 unknown.

Examples of Stock Mutations

To give you some more context regarding the stock mutations, below are some examples. Please note; below examples are illustrative. There are much more scenario’s where stock is mutated.

• Customer order fulfillment (warehouse):

  A warehouse receives a E-Commerce order for 5 pieces of 1 SKU.

  • The creation of the order does not create a mutation.

  • When the SKU is picked, packed, and shipped, the warehouse stock decreases by -5.

• Warehouse to physical store to end consumer and back to the store:

  • A warehouse transfers 1 SKU to a physical store:

    • Warehouse: -1

    • Store: +1

  • The store then sells the SKU:

    • Store: -1

  • The customer returns the SKU for a refund:

    • Store: +1

• Stock count adjustment in warehouse:

  • Administrative stock shows a quantity of 100 of a SKU in the warehouse.

  • Stock count reveals only 98 are still in stock.

  • The stock controller corrects the stock to 98 which results in a stock mutation of -2 for the warehouse.

• Purchase order received in warehouse:

  • A supplier shipped a quantity of 800 for a specific SKU, which is received by the warehouse.

  • The warehouse stock increases +800 for this SKU

Common pitfalls

1. We want to receive the mutations in this endpoint, not the stock level.

2. Not aligning the skuId with the skuId you send to the POST /Items, same goes for the locationId and the POST /Locations endpoint.

3. Do not generated a random id for the stockMutationId field in the integration, only use id’s that are fixed in the source system, this prevents creating duplicate mutations.

4. When you do not have an id for a stock mutation and rely on a method where you put the sku/date/location/etc. in 1 string to generate a unique id,  a common pitfall is that the fields chosen does not make it unique in all cases, make sure to double check this.

5. Not sending all mutations as mentioned in the best practice.

TECHNICAL INFORMATION

Authentication

Bearer token, information on page POST /Token

Headers

QueryParameters:

No queryParameters required.

Body example:

{
  "stockMutations": [
    {
      "stockMutationId": "5680f3ea-1c2a-4391-b52d-d268ef0754a5",
      "code": "COUNTGUID01",
      "locationId": "guid01",
      "skuId": "guid01",
      "stockMutationDateTime": "2023-09-08T09:17:39.254Z",
      "documentType": 2,
      "quantity": -1
    }
  ]
}

Field information:

RESPONSE

StatusCodes:

200 = OK.

401 = Unauthorized, which means an expired/missing/invalid token.

400 = Bad request, see body of the response to check which validation errors have occured.

500 = System error, see body of the response to check which error has occured or contact integration support.

Body Example:

No body in the response.