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

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

curl

curl -i 'https://localhost/api/binLocations?filter%5B0%5D%5Bproperty%5D=binLocation.code&filter%5B0%5D%5Bvalue%5D=A01' -H 'Accept: application/json'

wget

wget -S -O- 'https://localhost/api/binLocations?filter%5B0%5D%5Bproperty%5D=binLocation.code&filter%5B0%5D%5Bvalue%5D=A01' --header='Accept: application/json'

httpie

http 'https://localhost/api/binLocations?filter%5B0%5D%5Bproperty%5D=binLocation.code&filter%5B0%5D%5Bvalue%5D=A01' 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

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

curl

curl -i https://localhost/api/binLocations/12 -H 'Accept: application/json'

wget

wget -S -O- https://localhost/api/binLocations/12 --header='Accept: application/json'

httpie

http https://localhost/api/binLocations/12 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

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

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

curl

curl -i -X POST https://localhost/api/binLocations -H 'Content-Type: application/json' --data-raw '{"code": "A01-A01", "warehouseId": 1}'

wget

wget -S -O- https://localhost/api/binLocations --header='Content-Type: application/json' --post-data='{"code": "A01-A01", "warehouseId": 1}'

httpie

echo '{
  "code": "A01-A01",
  "warehouseId": 1
}' | http POST https://localhost/api/binLocations Content-Type:application/json

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

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

{
    "code": "A01-A02"
}

curl

curl -i -X PUT https://localhost/api/binLocations/12 -H 'Content-Type: application/json' --data-raw '{"code": "A01-A02"}'

wget

wget -S -O- --method=PUT https://localhost/api/binLocations/12 --header='Content-Type: application/json' --body-data='{"code": "A01-A02"}'

httpie

echo '{
  "code": "A01-A02"
}' | http PUT https://localhost/api/binLocations/12 Content-Type:application/json

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

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

curl

curl -i -X DELETE https://localhost/api/binLocations/12

wget

wget -S -O- --method=DELETE https://localhost/api/binLocations/12

httpie

http DELETE https://localhost/api/binLocations/12

Example response:

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

{
    "success": true
}