Stock Movements API

Track and record stock movements across your warehouses. Every inventory change is logged as a movement.

Endpoints
GET

/stock-movements

stock_movements:read

Retrieve a paginated list of stock movements. Supports filtering by product, warehouse, type, and date range.

POST

/stock-movements

stock_movements:write

Record a new stock movement. This will update inventory levels automatically.

Field Reference
FieldTypeRequiredDescription

id

string

No

Unique stock movement identifier (read-only)

productId

string

Yes

Product identifier

productSku

string

No

Product SKU (read-only)

productName

string

No

Product name (read-only)

warehouseId

string

Yes

Warehouse identifier

warehouseName

string

No

Warehouse name (read-only)

variantId

string

No

Product variant identifier (if applicable)

quantity

integer

Yes

Movement quantity (positive integer)

movementType

string

Yes

IN, OUT, ADJUSTMENT, TRANSFER_OUT, or TRANSFER_IN

reference

string

No

Reference number (e.g. purchase order)

unitCost

integer

No

Unit cost in cents

batchNumber

string

No

Batch or lot number

notes

string

No

Additional notes

createdAt

datetime

No

ISO 8601 timestamp (read-only)

Query Parameters (List)
FieldTypeRequiredDescription

page

integer

No

Page number (default: 1)

limit

integer

No

Items per page (default: 20, max: 100)

productId

string

No

Filter by product ID

warehouseId

string

No

Filter by warehouse ID

movementType

string

No

Filter by type: IN, OUT, ADJUSTMENT, TRANSFER_OUT, TRANSFER_IN

from

string

No

Start date filter (ISO 8601)

to

string

No

End date filter (ISO 8601)

Example
List stock movements
bash
curl "https://api.mercozy.com/api/v1/external/stock-movements?page=1&limit=20&movementType=IN" \
  -H "X-API-Key: mk_live_xxxxx"
Create a stock movement
bash
curl -X POST "https://api.mercozy.com/api/v1/external/stock-movements" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "product-uuid",
    "warehouseId": "warehouse-uuid",
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "notes": "Initial stock"
  }'
Example Response
json
{
  "data": {
    "id": "sm_abc123",
    "productId": "product-uuid",
    "productSku": "WDG-001",
    "productName": "Premium Widget",
    "warehouseId": "warehouse-uuid",
    "warehouseName": "Main Warehouse",
    "variantId": null,
    "quantity": 100,
    "movementType": "IN",
    "reference": "PO-2024-001",
    "unitCost": null,
    "batchNumber": null,
    "notes": "Initial stock",
    "createdAt": "2025-12-15T10:30:00Z"
  }
}