Update your variants’ stock

Now that we’ve configured your warehouses, we’re ready to send stock information using the Admin API.

Stocks represent the number of the available items defined on the variant level. To ensure correct stock information, you can update the stock information with the actual stocks for specific warehouses. You can also fetch the latest stock information of a specific variant for all warehouses.

Breaking down the stock update endpoint

You can use the following endpoint to update the current quantity of a variant:

POST /variants/{variantIdentifier}/stocks

The variantIdentifier either accepts the variant identifier or the reference key.

For more details see Identifiers.

Request Body

Parameter	Type	Details
`quantity`	`INTEGER`	Current sellable quantity of the variant. The quantity sent always represents the sellable quantity. For instance, if you have a quantity of 10 for variant A available and not reserved for any order or blocked by anything else, you would send the quantity of 10. An order containing the quantity of 1 for variant A, would reduce the sellable quantity to 9, so you would need to send 9 in this case. You can normally use an upstream service as the source of truth for this information.
`warehouseReferenceKey`	`STRING`	Reference key of the warehouse that the stock update is related to. You must create the warehouse reference key beforehand.
`changedAt`	`STRING`	Date time when the stock changed in ISO 8601 format. If you provide a `changedAt` date that is older than the last processed stock information, the stock will not change because this would be considered outdated information. In this case, the method will return the current stock. If you would like to see if the information you sent was outdated, compare what you’ve sent to what was returned in the response.
`sellableWithoutStock`	`BOOLEAN`	Determines if the variant can be sold even when the available stock is 0.

For more details see Create Stock Admin API endpoint.

Considerations when integrating this endpoint

When the same stock is sold on multiple platforms (e.g. on one side via SCAYLE and the other via a marketplace), maintain separate stocks to avoid overselling on either platform.
Especially in this case, send stock updates as soon as the stock changes in the upstream service. This keeps stocks from overselling.

The changedAt date must contain the date the stock changed in the upstream service.

The changedAt date is crucial because it determines if you should resolve quantity blockers in SCAYLE or not. Imagine the following process as an example:

Time	Event
15:00	Stock of 10 is sent for variant A.
15:00	Stock of 10 is sellable via SCAYLE.
15:10	An order is placed in SCAYLE including the variant A once.
15:10	Virtual stock handling of SCAYLE reduces available quantity by 1.
15:10	Stock of 9 is sellable via SCAYLE.
15:11	Order is delegated to the upstream service.
15:11	Stock for variant A is reduced by one in the upstream service.
15:11	Stock of 9 is sent for variant A with a timestamp younger than the one of the previous stock update and younger than the order-creation date → Stock is updated and virtual stock is resolved.
15:12	Stock of 9 is sellable via SCAYLE.
15:15	Stock of 20 is sent for variant A but with a timestamp older than the one of the previous stock update → Stock is not updated.

It is also possible to update stock via an import. However, this is not easily maintained. We recommend an automated Admin API integration.

Let’s update the stock information for our demo shop

Now you’ve successfully imported variants and configured warehouses, so it’s time to make our variants sellable by providing stock information. We’ll use the update endpoint for this task. Since we created two warehouses, let's set the stock for one example variant that’s stored in both warehouses.

First, let’s update the stock for the variant with the referenceKey “FS-100-black-S”.
For now, we assume the stock is 10. The source of truth for the latest stock is normally another system provided by the client.

URL /variants/key%3DFS-100-black-S/stocks

Request Body

{
  "quantity": 10,
  "warehouseReferenceKey": "warehouse_frankfurt",
  "changedAt": "2020-07-23T11:30:58+00:00"
}

In case the stock of this variant changes, you can update it the same way. Just make sure that the property changedAt shows the date and time when the stock changed in the upstream system.

Setting the stock for the other warehouse is simple, displayed in the request above. However, instead of sending the warehouseReferenceKey "warehouse_frankfurt" you would send "warehouse_basel".

Well done! You’ve now learned how to update stocks using the Admin API. Time to put in the last piece of the puzzle and start selling products.