Stock Movements API

Stock movements represent the transfer of goods between locations. They are the primary mechanism for requesting, shipping, and receiving inventory in OpenBoxes.

List Stock Movements

Retrieve a paginated list of stock movements:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements?max=25&offset=0"

Query Parameters

Parameter	Type	Default	Description
max	integer	all	Maximum records to return
offset	integer	0	Number of records to skip
direction	string	--	Filter by direction: INBOUND or OUTBOUND
receiptStatusCode	string	--	Filter by receipt status
exclude	string	--	Comma-separated statuses to exclude

Example: List Outbound Movements

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements?direction=OUTBOUND&max=10"

Response

{
  "data": [
    {
      "id": "sm-001",
      "name": "Transfer to Regional Depot",
      "description": "Monthly resupply",
      "identifier": "SM-00142",
      "status": "SHIPPED",
      "origin": {
        "id": "loc-001",
        "name": "Central Warehouse"
      },
      "destination": {
        "id": "loc-002",
        "name": "Regional Depot"
      },
      "dateRequested": "2025-03-01T00:00:00Z",
      "dateShipped": "2025-03-05T14:30:00Z",
      "requestedBy": {
        "id": "user-001",
        "name": "Jane Smith"
      }
    }
  ]
}

Get Stock Movement Details

Retrieve a single stock movement with full details including line items:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements/sm-001"

Response

{
  "data": {
    "id": "sm-001",
    "name": "Transfer to Regional Depot",
    "identifier": "SM-00142",
    "status": "SHIPPED",
    "origin": { "id": "loc-001", "name": "Central Warehouse" },
    "destination": { "id": "loc-002", "name": "Regional Depot" },
    "dateRequested": "2025-03-01T00:00:00Z",
    "requestedBy": { "id": "user-001", "name": "Jane Smith" },
    "lineItems": [
      {
        "id": "li-001",
        "product": { "id": "prod-001", "name": "Ibuprofen 200mg", "productCode": "IBU200" },
        "quantityRequested": 1000,
        "quantityShipped": 1000,
        "quantityReceived": null,
        "sortOrder": 0
      }
    ]
  }
}

Create Stock Movement

Create a new stock movement request:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements" \
  -d '{
    "name": "Emergency Resupply",
    "description": "Urgent stock transfer for Q2 demand",
    "origin": { "id": "loc-001" },
    "destination": { "id": "loc-002" },
    "dateRequested": "2025-04-01T00:00:00Z",
    "requestedBy": { "id": "user-001" }
  }'

Required Fields

Field	Type	Description
name	string	Descriptive name for the movement
description	string	Additional details about the movement
origin	object	Source location with id
destination	object	Destination location with id
dateRequested	string	Requested date in ISO 8601 format
requestedBy	object	Requesting user with id

Add Line Items

After creating a stock movement, add items to it:

curl -X POST \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements/sm-001" \
  -d '{
    "lineItems": [
      {
        "product": { "id": "prod-001" },
        "quantityRequested": 1000,
        "sortOrder": 0
      },
      {
        "product": { "id": "prod-002" },
        "quantityRequested": 500,
        "sortOrder": 1
      }
    ]
  }'

Update Line Items

Modify existing line items on a stock movement:

curl -X PUT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements/sm-001" \
  -d '{
    "lineItems": [
      {
        "id": "li-001",
        "quantityRequested": 1500
      }
    ]
  }'

Remove Line Items

Remove a line item by including it with the delete flag:

curl -X PUT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements/sm-001" \
  -d '{
    "lineItems": [
      { "id": "li-002", "delete": true }
    ]
  }'

Stock Movement Statuses

Stock movements progress through a defined workflow:

Status	Description
REQUESTING	Draft -- items are being added
REQUESTED	Submitted for fulfillment
CHECKING	Being reviewed and validated
PICKING	Items are being picked from shelves
PICKED	All items picked, ready to pack
PACKING	Items being packed for shipment
PACKED	Packed and ready to ship
SHIPPED	In transit to destination
RECEIVED	Delivered and received at destination

Filtering by Status

Exclude specific statuses from the list response:

# Get all movements except received ones
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/stockMovements?exclude=RECEIVED"

Important Notes

• Required parameters for list: The list endpoint may return 400 if pagination parameters are missing. Always include max and offset.
• Location context: Stock movements are filtered based on the location in your session. Outbound movements show shipments FROM your location; inbound movements show shipments TO your location.
• Status transitions: Not all status transitions are valid. The API returns an error if you attempt an invalid transition (e.g., skipping from REQUESTING directly to SHIPPED).