Skip to main content
The Inventory & Stock domain manages physical goods across one or more warehouses. It covers Warehouses (storage locations), Stocks (SKU-level inventory records with per-warehouse quantities), Stock History (audit log of quantity changes), Stock Movements (inter-warehouse transfers), Stock Inventories (physical count sessions), and Transfers (treasury-account fund movements). All write operations are scoped to the authenticated company and respect the active shop/warehouse access rules. Base URL https://api.genuka.com · Auth Authorization: Bearer <token> + X-Company: <companyId> · See Getting Started for shared conventions, pagination & error formats.

​
Endpoints at a glance

​
Warehouses

​
GET /2023-11/admin/warehouses

List all warehouses accessible to the authenticated user. Managers with assigned warehouses see only their subset.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company header
  • 401 — invalid or expired token

​
POST /2023-11/admin/warehouses

Create a new warehouse for the company.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company header
  • 401 — invalid token
  • 500 — internal error (e.g. image upload failure)

​
GET /2023-11/admin/warehouses/{warehouse}

Retrieve a single warehouse by ID.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — warehouse not found or not accessible

​
PUT /2023-11/admin/warehouses/{warehouse}

Update an existing warehouse.
  • Path parameters:
  • Request body: All fields are optional. Only provided fields are updated.
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — warehouse not found
  • 500 — internal error

​
DELETE /2023-11/admin/warehouses/{warehouse}

Permanently delete a warehouse (force-deletes, bypassing soft-delete).
  • Path parameters:
Request example:
Success response 204 No Content:
Error responses:
  • 401 — invalid token
  • 404 — warehouse not found

​
Stocks

A Stock is a company-level inventory record for one product variant, with quantities tracked per warehouse via stocks_warehouse pivot entries.

​
GET /2023-11/admin/stocks

List stocks with optional filtering, sorting, and relationship loading.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company header
  • 401 — invalid token

​
POST /2023-11/admin/stocks

Create a new stock record, optionally linking it to a product variant and assigning warehouse quantities.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company header
  • 401 — invalid token
  • 422 — title already exists for this company, or validation errors
  • 500 — internal error (warehouse sync or media upload failure)

​
GET /2023-11/admin/stocks/analytics

Returns aggregate inventory statistics for the company (or active shop). Request example:
Success response 200 OK:
  • inventory_value — total cost of all stock on hand, computed as SUM(quantity × COALESCE(supplier_price, stock_price, variant_price, 0))
  • total_stocks — total unit quantity across all warehouses
Error responses:
  • 401 — invalid token
  • 400 — missing X-Company header

​
POST /2023-11/admin/stocks/export

Trigger an asynchronous export of the stocks list. Returns immediately; the export is processed in the background.
  • Request body:
Request example:
Success response 200 OK:
The export runs asynchronously. Poll the returned job record or wait for the notification to retrieve the download_url once status becomes completed. Error responses:
  • 401 — invalid or unauthenticated request

​
GET /2023-11/admin/stocks/export/fields

List all available column keys that can be requested in a stock export. Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token

​
POST /2023-11/admin/stocks/add-stock

Receive stock into a warehouse. Each line creates a new stock_warehouse lot entry. The system resolves or auto-creates a stock record from a product_variant_id if no stock_id is given.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — insufficient stock, mismatched warehouse, or general error
  • 403 — warehouse not found or not accessible
  • 422 — validation errors (missing required fields, invalid quantity)

​
POST /2023-11/admin/stocks/move-stock

Manually adjust (add or remove) stock quantities in a warehouse belonging to the active shop. Requires X-Shop header (or shopId in the body).
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — shop not provided, insufficient stock, or warehouse mismatch
  • 403 — company or shop not found / not accessible
  • 422 — validation errors

​
GET /2023-11/admin/stocks/{stock}

Retrieve a single stock with related product variant, compositions, and warehouses.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — stock not found

​
PUT /2023-11/admin/stocks/{stock}

Update a stock record. All fields are optional on update.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — stock not found
  • 500 — internal error

​
DELETE /2023-11/admin/stocks/{stock}

Soft-delete a stock record and cascade-delete all its stock_warehouse entries.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — stock not found

​
Stock History

Stock history records an audit log of every quantity change per warehouse lot. Each entry has a type (e.g. sale, purchase, adjustment, inventory, movement), a signed quantity_delta, and the running balance after the change (balance_after). Unlike the old ledger format, entries are immutable — the PUT endpoint route exists but its controller method is not yet implemented.

​
GET /2023-11/admin/stockHistory

List stock history entries. Results are automatically filtered to warehouses accessible to the current user.
  • Query parameters:
Request example:
Success response 200 OK:
Field notes:
  • quantity_delta — signed change: positive = stock in, negative = stock out
  • balance_after — running total of the stock in that warehouse after this entry (aliased from quantity column)
  • total_quantity — present only when the list was built with a cumulative running total query; omitted otherwise
  • source_type — short alias (order, bill, return, inventory, movement)
Error responses:
  • 400 — missing X-Company
  • 401 — invalid token

​
POST /2023-11/admin/stockHistory/{stock}

Manually append a stock history entry for a given stock.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — stock not found
  • 500 — internal error

​
GET /2023-11/admin/stockHistory/{stockHistory}

Retrieve a single stock history entry.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — history entry not found

​
PUT /2023-11/admin/stockHistory/{stockHistory}

Note: The controller update method is not yet implemented. The route exists but currently returns an empty response. Stock history entries are immutable audit records; use this endpoint only if the controller is updated in a future release.
  • Path parameters:
  • Request body (anticipated):
Success response 200 OK (anticipated once implemented):

​
DELETE /2023-11/admin/stockHistory/{stockHistory}

Delete a stock history entry.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — history entry not found

​
Stock Movements

A Stock Movement represents an inter-warehouse transfer of stock. Status values: scheduled, in_progress, completed. A completed movement cannot be modified.

​
GET /2023-11/admin/stockMovement

List stock movements with filtering and sorting.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company
  • 401 — invalid token

​
POST /2023-11/admin/stockMovement

Create a new stock movement between two warehouses.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 422 — source and destination warehouses are the same; lines missing; validation errors

​
GET /2023-11/admin/stockMovement/{stockMovement}

Retrieve a single stock movement with all related data.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — movement not found

​
PUT /2023-11/admin/stockMovement/{stockMovement}

Update a stock movement. All fields are optional.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — movement not found
  • 422 — validation errors

​
DELETE /2023-11/admin/stockMovement/{stockMovement}

Soft-delete a stock movement. Pass force=true to permanently delete.
  • Path parameters:
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — movement not found

​
PATCH /2023-11/admin/stockMovement/{stockMovement}/status

Transition a stock movement to a new status. When transitioning to completed, source stock quantities are decremented and destination stock quantities are incremented atomically.
A movement that is already completed cannot be modified and returns 400.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — movement is already completed
  • 401 — invalid token
  • 404 — movement not found
  • 422 — invalid status value

​
Stock Inventories

A Stock Inventory is a physical count session for one warehouse. Statuses: draft → in_progress → validated (or cancelled). Only draft and in_progress inventories are editable. Validation generates accounting adjustment entries.

​
GET /2023-11/admin/inventories

List stock inventories with filtering and sorting.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company
  • 401 — invalid token

​
POST /2023-11/admin/inventories

Create a stock inventory session. If stock_ids is omitted, all stocks with quantity > 0 in the target warehouse are automatically included as lines (streamed in batches).
  • Request body:
Request example:
Success response 201 Created:
Error responses:
  • 401 — invalid token
  • 422 — validation errors

​
GET /2023-11/admin/inventories/{inventory}

Retrieve a single inventory with all its lines, media, and related warehouse.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 401 — invalid token
  • 404 — inventory not found

​
PUT /2023-11/admin/inventories/{inventory}

Update an inventory’s top-level metadata (reason, notes, date) and manage proof media attachments. Only editable when status is draft or in_progress.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — inventory is not in an editable state
  • 401 — invalid token
  • 404 — inventory not found

​
POST /2023-11/admin/inventories/{inventory}/cancel

Cancel a draft or in_progress inventory. Cannot cancel a validated inventory.
  • Path parameters:
Request example: Request body: None — no body required for this action endpoint.
Success response 200 OK:
Error responses:
  • 400 — inventory cannot be cancelled (e.g. already validated)
  • 401 — invalid token
  • 404 — inventory not found

​
PATCH /2023-11/admin/inventories/{inventory}/lines/{line}

Update the counted quantity for a single inventory line. The first count on any line auto-transitions the inventory from draft to in_progress.
  • Path parameters:
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — inventory not editable
  • 401 — invalid token
  • 404 — inventory or line not found
  • 422 — counted_quantity missing or invalid
  • 422 — line does not belong to this inventory

​
DELETE /2023-11/admin/inventories/{inventory}/medias/{media}

Remove a proof media attachment from an inventory. Only allowed while the inventory is still editable.
  • Path parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — inventory not editable
  • 401 — invalid token
  • 404 — inventory or media not found

​
POST /2023-11/admin/inventories/{inventory}/validate

Validate a fully-counted inventory. Requirements: (1) inventory must be in_progress, (2) all lines must have a counted_quantity, (3) at least one proof media must be attached. On success: stock quantities are adjusted in the warehouse, one accounting transaction is generated for all differences, and the inventory status is set to validated.
  • Path parameters:
  • Request body: None — this is a pure action endpoint. No body is required.
Request example:
Success response 200 OK:
Error responses:
  • 400 — inventory cannot be validated (wrong status, uncounted lines, or missing proof media). Error messages:
    • "N lines have not been counted yet" — not all lines have counted_quantity
    • "No proof attached" — no media on inventory or lines
    • "Cannot validate inventory with status: draft" — wrong status
  • 401 — invalid token
  • 404 — inventory not found

​
Transfers

A Transfer is a treasury-account fund movement. Deducts from the source account balance and credits the destination. Automatically creates accounting book entries.

​
GET /2023-11/admin/transfers

List treasury transfers.
  • Query parameters:
Request example:
Success response 200 OK:
Error responses:
  • 400 — missing X-Company
  • 401 — invalid token

​
POST /2023-11/admin/transfers

Create a treasury transfer. Immediately deducts from source and credits destination; fails if the source has insufficient balance.
  • Request body:
Request example:
Success response 200 OK:
Error responses:
  • 400 — source balance insufficient ("Insufficient balance")
  • 401 — invalid token
  • 404 — source or destination treasury account not found

​
GET /2023-11/admin/transfers/{transfer}

Retrieve a single transfer.
  • Path parameters:
Request example:
Note: The controller show method body is not yet implemented. The route exists but currently returns an empty response. When implemented, it will return a TransferResource object matching the shape shown in the POST success response.
Success response 200 OK (anticipated once implemented):

​
PUT /2023-11/admin/transfers/{transfer}

Update a transfer.
  • Path parameters:
  • Request body (anticipated):
Request example:
Note: The controller update method body is not yet implemented. The route exists but currently returns an empty response.
Success response 200 OK (anticipated once implemented):

​
DELETE /2023-11/admin/transfers/{transfer}

Delete a transfer. Automatically reverses the source/destination balance changes and reverts all associated book entries.
  • Path parameters:
Request example:
Note: The controller destroy method body is not yet implemented. The route exists but balance reversal logic is defined in the model’s deleting observer.
Success response 200 OK (anticipated once implemented):