Virtualstock is a modular SaaS platform that sits between the retailer and their suppliers

Suppliers could be manufacturers, distributors, vendors or the retailer’s own warehouses or store network. In most cases these suppliers are fulfilling dropship or marketplace orders for their client retailers.

While Virtualstock has a range of modules and features, it has been predominantly deployed as a Dropship Solution.

Virtualstock allows the supplier to efficiently share up-to-date order status, delivery status and stock availability information. Virtualstock also has Invoicing and Price Management modules.

In addition, Virtualstock can be used for rich product induction - where the supplier’s product data is validated against the retailer’s data model, before it is published to the retailer’s systems.

The purpose of the Virtualstock's APIs are to enable Retailers and Suppliers to create and manage their suppliers, products, stock availability, orders and order status.

Please note that Linnworks has a reusable connector to Virtualstock, so if you are a customer of Linnworks already you can instantly configure the integration and you don't need to do any bespoke integration. If you are not a customer of Linnworks already, but you sell through multiple channels and would be interested in having a system where you can centralise your stock and order management, automatically into all your channels including any Virtualstock customers, please see here for more info:

https://www.linnworks.com/connect/lw-virtualstock-emea

Overview

In order to begin using this API, you should first have been set up and have been provided with at least a test supplier have credentials for the API.

If you want to verify API calls via Postman, you can acquire the Postman pack here. See the "Run in postman" button at the top right of this page.

Breaking Change Policy

As our APIs evolve, we will make reasonable efforts to notify you of breaking changes in advance with sufficient time to adapt to these changes.

Important!

Review this guide carefully to understand what kind of changes we consider to be breaking and non-breaking, and how to ensure that your application can adapt automatically to any change we categorise as non-breaking.

Definition

A breaking change is a change that may require you to make changes to your application in order to avoid disruption to your integration. The following are a few examples of changes we consider breaking:

• Changes to existing permission definitions

• Removal of an allowed parameter, request field or response field

• Addition of a required parameter or request field without default values

• Changes to the intended functionality of an endpoint. For example, if a DELETE request previously used to archive the resource but now hard deletes the resource.

• Introduction of a new validation

A non-breaking change is a change that you can adapt to at your own discretion and pace without disruption. In most cases, we will communicate non-breaking changes after they are already made. Ensure that your application is designed to be able to handle the following types of non-breaking changes without prior notice:

• Addition of new endpoints

• Addition of new methods to existing endpoints

• New fields in responses

• New optional request fields or parameters

• New required request fields that have default values

• Addition of a new value returned for an existing text field

• Changes to the order of fields returned within a response

• Addition of an optional request header

• Removal of redundant request header

• Changes to the length of data returned within a field

• Changes to the overall response size

• Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.

• Fixes to HTTP response codes and error codes from incorrect code to correct code

You can either request an SFTP server to be set up for you, or use your own. In either case you will be authenticating using the username and password for SFTP account.

REST API Error Codes

Throttling limit

All api requests are limited to 250 requests per minute. You will be given an error message informing you when you are next able to make another API call if you exceed these this limit. So for example you can call the API 250 times in the first few seconds of the minute, but have to then wait until the next minute to call again.

The API will return a status code of 429 and a message in the response Request was throttled. Request was throttled. Expected available in XX.0 seconds.

Flat file API (CSV via SFTP) for Suppliers

If you are unable to integrate your applications with our REST API or have a previous integration to Virtualstock with our Flat file SFTP API that you would like to replicate for your integration, then please download our Flat file CSV over SFTP API documentation.

VIEW FLAT FILE SFTP API DOCUMENTATION

Invoice as JSON files via SFTP for Retailers

This interface is for retailers to receive invoices created by suppliers as single JSON files over SFTP for each invoice.
DOWNLOAD JSON FILE SFTP INVOICES API DOCUMENTATION

Order Events report CSV via SFTP for Retailers

This interface is for retailers to receive CSV files over SFTP all events made by suppliers or carriers to orders. "Events:" are order line status changes, order comments and tracking.
DOWNLOAD EVENT REPORT DOCUMENTATION

Order tracking status updates via Webhook

Introduction

The purpose of this Webhook API is for a retailer to receive all the orders tracking status updates that are made by suppliers or their carriers. The retailer will need to build a REST API to the specifications detailed below, and Virtualstock will require the URL and credentials to start receiving these updates.

Authentication

The Webook APIs use Basic Authentication. Usernames and passwords for the environment that Virtualstock needs to interact with need to be provided to Virtualstock when the API is ready for testing.

Content types

This service sends JSON content with a Content-Type header set to application/json.

Payload, method and endpoint

POST the following payload to a URL of your choosing.

{
    "channel": "CHANNEL1", //(optional)  
    "carrier": "DPD",
    "dispatched_date": "2019-05-23T00:00:00+0000",
    "estimated_delivery_date": "2019-05-23T00:00:00+0000",
    "order_number": "ORDER121821",
    "tracking_number": "TXD98798798798",
    "tracking_url": "https://www.some.site.com/tracking",
    "status": "DELIVERED",
    "checkpoint_time": "2019-05-23T13:09:51+0000",
    "tracking_message": "Manchester HUB",
    "items": [
        {
            "line_ref": "001",
            "part_number": "sku-002014",
            "quantity": 10
        }
    ],
    "ts": 15484698531106 //(unique timestamp)
}

Exceptions & Error handling

The expectation is that the Retailer building this Webhook API will respond with the following response codes when Virtualstock calls their API. For any of these errors, if Virtualstock fails to deliver the update, it will attempt to replay failed messages several times over the course of 24 hours. Virtualstock will log the failure and an alert will be monitored by our Service Desk team, who will be in touch to help resolve connectivity.

ParseError
Raised if the request contains malformed data when accessing request.data.
This exception results in a response with the HTTP status code "400 Bad Request".
**
AuthenticationFailed**
Raised when an incoming request includes incorrect authentication.
This exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use.

NotAuthenticated
Raised when an unauthenticated request fails the permission checks.
This exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.

PermissionDenied
Raised when an authenticated request fails the permission checks.
This exception results in a response with the HTTP status code "403 Forbidden".

Throttled
Raised when an incoming request fails the throttling checks.
This exception results in a response with the HTTP status code "429 Too Many Requests". Virtualstock are reviewing the API performance metrics and as such are not able to share the throttling limits that will apply.

ValidationError
This exception results in a response with the HTTP status code "400 Bad Request".

REST API Endpoints

Listed below are all the endpoints that you are able to use for your integration