Get product stock

Retrieve Product Stock Across Warehouses and Stores

This API provides the ability to retrieve stock levels of a specific product identified by its ITEM_CODE. The response includes details for each store or warehouse where the product is stocked, segmented by SKU. Pagination is supported for managing large datasets.

The API supports pagination to navigate through large lists of product stocks.

Paginated Responses

The service is paginated to handle large sets of data efficiently.
For detailed information on how to handle pagination, refer to our Paginated Responses

Actors

API Client: The system or user initiating the request.

4ws.suite Platform: The backend system that processes the request and returns the stock data.

Preconditions

The external system must have the necessary permissions and access to the service, please refer to Authentication.

The ITEM_CODE provided must correspond to an existing product in the system.

Pagination parameters cursor and nextCursor must be correctly configured in the request.

Main Success Scenario

If the request is successful, the system will return an HTTP 200 response with the paginated list of product stock and a nextCursor indicating whether there are more stock to retrieve. If nextCursor is setted, the external system must be call again, this service, setting cursor as nextCursor value.

Sample Success Response

Other types of quantities

The API returns the quantities tracked by the document movements.
Those who use the API will therefore have to take care of any calculations to deduce other types of quantities.
For example, if you need to know the available quantity, this can be obtained with the formula: quantity_stock - quantity_committed.

Using API for ecommerce inventory data

The e-commerce system sends a GET request to the getStock API.

The API fetches inventory data for the requested barcode from entities with the ECOMMERCE channel enabled.

The API responds with the available stock details, including the stock count and branch information.

Here is a code example.

Alternate Flows

Authentication Error: If the client does not provide valid credentials, an error response is returned.

Error Example

No Stock Available: If no entities have available stock for the given barcode, the API returns an empty stock response.

Invalid Product Code: If the provided ITEM_CODE does not exist or is incorrect, the API responds with HTTP 422 and an error message

Error Example

Invalid barcode :The specified barcode is not associated with any SKU.

Error Example

barcode not associated with the product: The specified barcode is not associated with the product.

Error Example

Cursor & PageSize Used Together: Cursor and PageSize parameters in the request: If you specify a Cursor you cannot specify the page size. This information will already be contained within the cursor.

Error Example

Pagination Error: If invalid cursor parameters are provided, an error response is returned.

Rate Limiting: If the API rate limits are exceeded, the client must respect the retry interval indicated in the response headers Rate Limits.

Sequence Diagram

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Examples in Node.js

Example Request with Pagination Handling:

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200GET Product stocks

application/json

Body

Example

{
    "stocks": [
        {
            "entity_code": 123,
            "item_code": "string",
            "dimension_level1": "0-3",
            "dimension_level2": "7",
            "quantity_stock": 100
        },
        {
            "entity_code": 123,
            "item_code": "string",
            "dimension_level1": "0-3",
            "dimension_level2": "8",
            "quantity_stock": 10
        }
    ],
    "nextCursor": "eyJwYWdlIjoyLCJwYWdlU2l6ZSI6MTB2"
}

🟠422Invalid pageSize

🟠401Authentication failed

🟠404Product not found with item_code

Retrieve Product Stock Across Warehouses and Stores#

Actors#

Preconditions#

Main Success Scenario#

Using API for ecommerce inventory data#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrieve Product Stock Across Warehouses and Stores

Actors

Preconditions

Main Success Scenario

Using API for ecommerce inventory data

Alternate Flows

Sequence Diagram

Code Examples in Node.js