Inventory API: Adjust Stock Levels and Log Movements

Mutasib tracks stock automatically — every time you record a sale, the quantity for each sold product decrements in real time. Use the inventory endpoints to view the current state of your stock, make manual adjustments (for purchases, returns, or damage), and audit every stock change through the movement log.

List Inventory

Fetch the current stock snapshot for every product in a shop. Each entry reflects the live quantity after all sales and manual adjustments. GET /api/v1/shops/{shop_id}/inventory/

curl https://api.mutasib.com/api/v1/shops/42/inventory/ \
  -H "Authorization: Bearer <token>"

Example response

[
  {
    "id": 101,
    "name": "Whole Milk 1L",
    "barcode": "6281234567890",
    "stock": 48,
    "low_stock_threshold": 10,
    "is_low_stock": false,
    "unit": "piece",
    "price": "1.50",
    "category_name": "Dairy"
  },
  {
    "id": 205,
    "name": "Bottled Water 500ml",
    "barcode": "6289876543210",
    "stock": 7,
    "low_stock_threshold": 20,
    "is_low_stock": true,
    "unit": "piece",
    "price": "0.75",
    "category_name": "Beverages"
  }
]

Returns an array of InventorySnapshotOut objects.

Adjust Inventory

Apply a manual stock adjustment to a single product. The adjustment field is a delta — pass a positive number to add stock (e.g. after a purchase delivery) or a negative number to remove it (e.g. for spoilage or damage). PATCH /api/v1/shops/{shop_id}/inventory/{product_id}/

Request body

integer

The quantity to add (positive) or remove (negative) from current stock. Defaults to 0.

integer

Update the threshold at which this product is flagged as low stock. Optional.

string

Why the adjustment is being made. Defaults to adjustment. Accepted values:

Value	When to use
`adjustment`	Generic manual correction
`purchase`	Stock received from a supplier
`return`	Customer or supplier return
`damage`	Items damaged or expired
`correction`	Fixing a data entry mistake

string

An optional free-text note attached to this movement record. Defaults to "".

# Add 24 units after a supplier delivery
curl -X PATCH https://api.mutasib.com/api/v1/shops/42/inventory/101/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adjustment": 24,
    "reason": "purchase",
    "note": "Supplier invoice #INV-2024-0881"
  }'

# Remove 3 units for damaged goods
curl -X PATCH https://api.mutasib.com/api/v1/shops/42/inventory/101/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adjustment": -3,
    "reason": "damage",
    "note": "Broken during shelf restocking"
  }'

Returns an updated InventorySnapshotOut object reflecting the new stock level.

Low Stock List

Retrieve only the products currently at or below their configured low_stock_threshold. Use this endpoint to drive reorder workflows or surface alerts on your dashboard. GET /api/v1/shops/{shop_id}/inventory/low-stock/

curl https://api.mutasib.com/api/v1/shops/42/inventory/low-stock/ \
  -H "Authorization: Bearer <token>"

Returns an array of InventorySnapshotOut objects where is_low_stock is true.

Inventory Movements

Every stock change — whether from a sale, a manual adjustment, or an import — is recorded as an InventoryMovementOut entry. Use the optional query parameters to filter the log by product or reason. GET /api/v1/shops/{shop_id}/inventory/movements/

integer

Filter movements to a single product.

string

Filter by reason. Accepted values: sale, adjustment, purchase, return, damage, correction.

curl "https://api.mutasib.com/api/v1/shops/42/inventory/movements/?product_id=101&reason=purchase" \
  -H "Authorization: Bearer <token>"

`InventoryMovementOut` fields

integer

Unique movement record ID.

integer

ID of the affected product.

string

Name of the affected product at the time of the movement.

integer

The delta applied. Positive means stock increased; negative means stock decreased.

integer

The stock level immediately after this movement was applied.

string

The reason code for the movement (e.g. sale, purchase, damage).

string

Name of the user who triggered the movement.

string

Free-text note attached to the movement, if any.

string

ISO 8601 timestamp of when the movement was recorded.

`InventorySnapshotOut` Fields

integer

Product ID.

string

Product display name.

string

Product barcode (EAN, UPC, or custom), if assigned.

integer

Current on-hand quantity.

integer

The quantity at or below which is_low_stock becomes true.

boolean

true when stock <= low_stock_threshold.

string

Unit of measure (e.g. piece, kg, litre).

string

Current selling price as a decimal string.

string

Name of the product’s category, if assigned. May be null.

Set a meaningful low_stock_threshold for each product based on your reorder lead time and average daily sales. A product that sells 10 units per day and takes 3 days to restock should have a threshold of at least 30 — otherwise you risk running out before the next delivery arrives.

Shops

Products

Sales & Inventory

Public & Misc

Inventory API: Adjust Stock Levels and Log Movements

List Inventory

Adjust Inventory

Request body

Low Stock List

Inventory Movements

`InventoryMovementOut` fields

`InventorySnapshotOut` Fields

​List Inventory

​Adjust Inventory

​Request body

​Low Stock List

​Inventory Movements

​InventoryMovementOut fields

​InventorySnapshotOut Fields

List Inventory

Adjust Inventory

Request body

Low Stock List

Inventory Movements

`InventoryMovementOut` fields

`InventorySnapshotOut` Fields