Skip to main content

​
Overview

The Inventory API allows you to manage product stock levels across multiple workspaces, perform stock transfers, record adjustments, and track stock movements.
Inventory operations are workspace-specific. Stock levels are tracked separately for each workspace (location).

​
Stock Movement Object

​
id
integer
Unique identifier for the stock movement
​
product_id
integer
Product ID
​
type
enum
Movement type: sale, purchase, transfer_out, transfer_in, adjustment, initial_stock
​
quantity
decimal
Quantity moved (negative for outgoing, positive for incoming)
​
from_workspace_id
integer
Source workspace (for transfers and sales)
​
to_workspace_id
integer
Destination workspace (for transfers and purchases)
​
reference
string
Reference number or description
​
notes
string
Additional notes
​
related_invoice_id
integer
Associated invoice (for sales)
​
created_by
integer
User who created the movement
​
created_at
timestamp
Creation timestamp

​
List Stock Transfers

Retrieve a list of stock transfers for the current workspace.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
per_page
integer
default:"15"
Number of items per page
​
filter[product_id]
integer
Filter by product ID
​
filter[type]
string
Filter by transfer type: transfer_out, transfer_in
​
sort
string
default:"-created_at"
Sort field

​
Response

{
  "data": [
    {
      "id": 450,
      "product_id": 78,
      "type": "transfer_out",
      "quantity": "-50.00",
      "from_workspace_id": 2,
      "to_workspace_id": 3,
      "reference": "TRF-2024-001",
      "notes": "Stock transfer to warehouse",
      "product": {
        "id": 78,
        "name": "Premium Product",
        "sku": "PROD-001"
      },
      "from_workspace": {
        "id": 2,
        "name": "Main Store"
      },
      "to_workspace": {
        "id": 3,
        "name": "Warehouse"
      },
      "created_by": {
        "id": 5,
        "name": "John Doe"
      },
      "created_at": "2024-03-20T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 15,
    "total": 52
  }
}

​
Example

curl -X GET https://acme.yourdomain.com/api/v1/stock-transfers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-ID: 2" \
  -H "Accept: application/json"

​
Get Stock Transfer

Retrieve details of a specific stock transfer.

​
Path Parameters

​
id
integer
required
Stock movement ID

​
Response

{
  "data": {
    "id": 450,
    "product_id": 78,
    "type": "transfer_out",
    "quantity": "-50.00",
    "from_workspace_id": 2,
    "to_workspace_id": 3,
    "reference": "TRF-2024-001",
    "notes": "Stock transfer to warehouse",
    "product": {
      "id": 78,
      "name": "Premium Product",
      "sku": "PROD-001",
      "current_stock": "100.00"
    },
    "from_workspace": {
      "id": 2,
      "name": "Main Store"
    },
    "to_workspace": {
      "id": 3,
      "name": "Warehouse"
    },
    "created_by": {
      "id": 5,
      "name": "John Doe",
      "email": "[email protected]"
    },
    "created_at": "2024-03-20T10:30:00Z"
  }
}

​
Create Stock Transfer

Transfer stock from the current workspace to another workspace.

​
Request Body

​
product_id
integer
required
Product ID to transfer
​
to_workspace_id
integer
required
Destination workspace ID
​
quantity
decimal
required
Quantity to transfer (must be positive)
​
reference
string
Reference number or code
​
notes
string
Additional notes about the transfer

​
Response

{
  "data": {
    "id": 451,
    "product_id": 78,
    "type": "transfer_out",
    "quantity": "50.00",
    "from_workspace_id": 2,
    "to_workspace_id": 3,
    "created_at": "2024-03-20T11:00:00Z"
  },
  "message": "Stock transfer completed successfully."
}

​
Example

curl -X POST https://acme.yourdomain.com/api/v1/stock-transfers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-ID: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 78,
    "to_workspace_id": 3,
    "quantity": 50,
    "reference": "TRF-2024-002",
    "notes": "Monthly inventory transfer"
  }'
Stock transfers create two movements: a transfer_out in the source workspace and a transfer_in in the destination workspace. Both workspaces must belong to the same tenant.

​
List Inventory Adjustments

Retrieve a list of inventory adjustments (manual stock corrections).

​
Response

Similar structure to stock transfers, with type adjustment.

​
Create Inventory Adjustment

Create a manual inventory adjustment to correct stock levels.

​
Request Body

​
items
array
required
Array of products to adjust
​
items[].product_id
integer
required
Product ID
​
items[].quantity_adjustment
decimal
required
Adjustment quantity (positive to increase, negative to decrease)
​
items[].reason
string
required
Reason for adjustment: damaged, lost, found, recount, other
​
items[].notes
string
Additional notes
​
reference
string
Reference number

​
Response

{
  "data": {
    "id": 25,
    "workspace_id": 2,
    "reference": "ADJ-2024-003",
    "items": [
      {
        "product_id": 78,
        "quantity_adjustment": "-5.00",
        "reason": "damaged",
        "notes": "Water damage from roof leak"
      }
    ],
    "created_at": "2024-03-20T12:00:00Z"
  },
  "message": "Inventory adjustment created successfully."
}

​
Example

curl -X POST https://acme.yourdomain.com/api/v1/inventory-adjustments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-ID: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ADJ-2024-003",
    "items": [
      {
        "product_id": 78,
        "quantity_adjustment": -5,
        "reason": "damaged",
        "notes": "Water damage from roof leak"
      }
    ]
  }'
Inventory adjustments create stock movements with type adjustment and update the product’s stock level in the current workspace.

​
Set Initial Stock

Set initial stock levels when first setting up inventory tracking for existing products.

​
Request Body

​
items
array
required
Array of products with initial stock
​
items[].product_id
integer
required
Product ID
​
items[].quantity
decimal
required
Initial quantity
​
items[].cost
decimal
Cost per unit (optional)

​
Response

{
  "message": "Initial stock set for 15 products.",
  "summary": {
    "total_products": 15,
    "total_quantity": "1250.00",
    "total_value": "45000.00"
  }
}

​
Get Product Stock by Workspace

Get stock levels for a specific product across all workspaces.

​
Path Parameters

​
id
integer
required
Product ID

​
Response

{
  "data": {
    "product_id": 78,
    "product_name": "Premium Product",
    "total_stock": "250.00",
    "workspace_stocks": [
      {
        "workspace_id": 1,
        "workspace_name": "Main Store",
        "quantity": "100.00",
        "minimum_quantity": "20.00",
        "is_low_stock": false
      },
      {
        "workspace_id": 2,
        "workspace_name": "Warehouse",
        "quantity": "150.00",
        "minimum_quantity": "50.00",
        "is_low_stock": false
      }
    ]
  }
}

​
Low Stock Alerts

Get products with stock below minimum quantity threshold.

​
Query Parameters

​
workspace_id
integer
Filter by specific workspace (defaults to current workspace)

​
Response

{
  "data": [
    {
      "product_id": 85,
      "product_name": "Another Product",
      "sku": "PROD-085",
      "workspace_id": 2,
      "workspace_name": "Main Store",
      "current_quantity": "8.00",
      "minimum_quantity": "20.00",
      "deficit": "12.00"
    }
  ]
}

​
Stock Movements Report

Get detailed stock movements for auditing and reporting.

​
Query Parameters

​
product_id
integer
Filter by product
​
workspace_id
integer
Filter by workspace
​
type
string
Filter by movement type
​
date_from
date
Start date (YYYY-MM-DD)
​
date_to
date
End date (YYYY-MM-DD)

​
Response

{
  "data": [
    {
      "id": 450,
      "product_id": 78,
      "product_name": "Premium Product",
      "type": "sale",
      "quantity": "-10.00",
      "workspace_id": 2,
      "reference": "INV-0042",
      "created_at": "2024-03-20T10:30:00Z"
    }
  ]
}

Products

Manage product catalog

Workspaces

Manage workspace locations

Invoices

Stock is reduced when invoices are created

Build docs developers (and LLMs) love

Get started for freeTalk to us