Bin Locations API

The /api/binLocations endpoint exposes the Bin Location Model as a resource. Bin locations represent individually identifiable shelf spaces or boxes within a warehouse which can hold product stock.

GET /api/binLocations

Query all bin locations or a subset of bin locations according to a set of criteria. This endpoint returns a plain representation of bin locations which does not include the mapping of products to the bin locations and their associated stock quantities. To retrieve this type of information, the single-bin-location endpoint must be used instead.

Query Parameters:
 
  • start (integer) – the starting offset into the result list (default: 0)
  • limit (integer) – the maximum number of results (default: 1000)
  • filter (object) – a search filter (see Filter and Sort Query Parameters), with property names prefixed by binLocation., for example binLocation.code
  • sort (object) – a sorting specification (see Filter and Sort Query Parameters), with property names prefixed by binLocation., for example binLocation.code
Response JSON Object:
 
  • success (boolean) – whether the operation was successful
  • total (integer) – the total number of bin locations which matched the query
  • data (array) – an array of bin locations
  • data[*].id (integer) – the database ID of the bin location
  • data[*].warehouseId (integer) – the database ID of the warehouse this bin location is located within
  • data[*].code (string) – the shorthand code of the bin location

Example request:

http

curl

wget

httpie

GET /api/binLocations?filter%5B0%5D%5Bproperty%5D=binLocation.code&filter%5B0%5D%5Bvalue%5D=A01 HTTP/1.1
Host: localhost
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true,
    "data": [
        {
            "id": 12,
            "warehouseId": 1,
            "code": "A01"
        }
    ],
    "total": 1
}
GET /api/binLocations/{id}

Fetch a single bin location by its database ID as well as any product stock mapped to it.

Parameters:
  • id (integer) – the database ID of the bin location to fetch
Response JSON Object:
 
  • success (boolean) – whether the operation was successful
  • data (object) – the bin location with the given ID
  • data.id (integer) – the database ID of the bin location
  • data.warehouseId (integer) – the database ID of the warehouse this bin location is located within
  • data.code (string) – the shorthand code of the bin location
  • data.articleDetailBinLocationMappings (array) – an array of article detail (product) mappings for this bin location
  • data.articleDetailBinLocationMappings[*].id (integer) – the database ID of the bin location mapping
  • data.articleDetailBinLocationMappings[*].binLocationId (integer) – the database ID of the bin location
  • data.articleDetailBinLocationMappings[*].articleDetailId (integer) – the database ID of the article detail (product) being mapped to this bin location
  • data.articleDetailBinLocationMappings[*].stock (integer) – the number of pieces of the mapped article detail (product) which currently reside on this bin location
  • data.articleDetailBinLocationMappings[*].defaultMapping (boolean) – whether this is the default bin location for this article detail (product)
  • data.articleDetailBinLocationMappings[*].reservedStock (integer) – the number of pieces of the mapped article detail (product) which reside on this bin location, but are reserved for ongoing picking processes
  • data.articleDetailBinLocationMappings[*].lastStockTake (timestamp) – the timestamp of the last time the stock quantity of the mapped article detail (product) was manually verified on this bin location

Example request:

http

curl

wget

httpie

GET /api/binLocations/12 HTTP/1.1
Host: localhost
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true,
    "data": {
        "id": 12,
        "warehouseId": 1,
        "code": "A-01",
        "articleDetailBinLocationMappings": [
            {
                "id": 56,
                "binLocationId": 12,
                "articleDetailId": 34,
                "stock": 50,
                "defaultMapping": false,
                "reservedStock": 0,
                "lastStockTake": "2019-01-03T14:23:12+0200"
            }
        ]
    }
}
POST /api/binLocations

Create a new bin location.

Request JSON Object:
 
  • warehouseId (integer) – the database ID of the warehouse this bin location should be created in
  • code (string) – the shorthand code of the bin location. This must be unique within the warehouse and must not be pickware_null_bin_location.

Example request:

http

curl

wget

httpie

POST /api/binLocations HTTP/1.1
Content-Type: application/json
Host: localhost

{
    "warehouseId": 1,
    "code": "A01-A01"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "success": true,
    "data": {
        "id": 12,
        "location": "https://localhost/api/binLocations/12"
    }
}
PUT /api/binLocations/{id}

Update the bin location with the given database ID using the data in the request body.

Parameters:
  • id (integer) – the database ID of the bin location to update
Request JSON Object:
 
  • code (string) – the shorthand code of the bin location. This must be unique within the warehouse and must not be pickware_null_bin_location.

Example request:

http

curl

wget

httpie

PUT /api/binLocations/12 HTTP/1.1
Content-Type: application/json
Host: localhost

{
    "code": "A01-A02"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}
DELETE /api/binLocations/{id}

Delete the bin location with the given database ID.

Parameters:
  • id (integer) – the database ID of the bin location to delete
Status Codes:
  • 400 Bad Request – if the bin location cannot be deleted because it still has stock or it is the default bin location for a product

Example request:

http

curl

wget

httpie

DELETE /api/binLocations/12 HTTP/1.1
Host: localhost

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}