Home Integration API reference
REST API for integrations and external apps
Stock adjustments
Lists stock adjustment transactions for the business.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/stock-adjustments |
| Permission | stock_adjustment.view, stock_adjustment.create, or view_own_stock_adjustment. |
| Visibility | Rows are limited to permitted locations. When the token user lacks stock_adjustment.view but has view_own_stock_adjustment, rows are further limited to adjustments they created. A user with stock_adjustment.create but without stock_adjustment.view can still list adjustments in permitted locations. |
| Price visibility | final_total and total_amount_recovered are returned only when the token user has view_purchase_price; otherwise those fields are null. |
| CSV behavior | format=csv streams all matching rows with a UTF-8 BOM and ignores page and per_page. The location object is JSON-encoded in CSV cells. |
| Success response | 200 with paginated StockAdjustmentRow rows. |
| Parameter | Type | Required | Description |
|---|---|---|---|
per_page, page | integer | No | Pagination controls. per_page accepts 1 to 100 and defaults to 20. |
start_date, end_date | string | No | Optional Y-m-d bounds on transaction_date. The date filter is only applied when both values are present. |
location_id, created_by | integer | No | Optional location and creator filters. |
adjustment_type | string | No | normal or abnormal. |
q | string | No | Minimum 2 characters when sent. Matches reference number, notes, numeric id, and location name. |
format | string | No | json (default) or csv. |
StockAdjustmentRow object| Field | Type | Description |
|---|---|---|
id | integer | Stock adjustment transaction id. |
ref_no | string | null | Adjustment reference number. |
transaction_date | string | null | ISO-8601 adjustment timestamp. |
adjustment_type | string | null | normal or abnormal. |
additional_notes | string | null | Saved adjustment notes. |
created_by | integer | null | Creator user id. |
final_total, total_amount_recovered | number | null | Adjustment totals. Returned as null when the token user lacks view_purchase_price. |
location | object | Location summary with id and name. |
| Field | Type | Description |
|---|---|---|
data | array<StockAdjustmentRow> | The current result page. |
meta.current_page, meta.last_page, meta.per_page, meta.total | integer | Laravel paginator metadata. |
| Status | When it happens | Response shape |
|---|---|---|
200 | The stock adjustment list was returned successfully. | { "data": [...], "meta": { ... } } or CSV download. |
403 | The token user lacks stock-adjustment list access. | { "message": "Unauthorized" } |
422 | The query string failed validation or q was shorter than 2 characters. | Laravel validation JSON or { "message": string }. |
Returns one visible stock adjustment by id.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/v1/integration/stock-adjustments/{id} |
| Permission | Same permission and visibility rules as List stock adjustments. |
| Price visibility | Header totals, line unit_price, and line line_total are returned only when the token user has view_purchase_price. |
| CSV behavior | format=csv streams one UTF-8 BOM row whose data_json column matches the JSON data payload. |
| Success response | 200 with one StockAdjustmentDetail object. |
StockAdjustmentLine object| Field | Type | Description |
|---|---|---|
id | integer | Stock-adjustment line id. |
product_id, variation_id | integer | Product and variation ids on the adjustment line. |
product_label | string | Variation display label from the loaded variation relation. |
sub_sku | string | null | Variation SKU. |
quantity | number | Stored adjustment quantity. |
unit_price | number | null | Line unit price, or null when the token user lacks view_purchase_price. |
line_total | number | null | Rounded line total quantity * unit_price, or null when the token user lacks view_purchase_price. |
lot | object | null | Optional lot summary with lot_number and exp_date when a lot relation exists. |
StockAdjustmentDetail object| Field | Type | Description |
|---|---|---|
id | integer | Stock adjustment transaction id. |
ref_no | string | null | Adjustment reference number. |
transaction_date | string | null | ISO-8601 adjustment timestamp. |
adjustment_type | string | null | normal or abnormal. |
additional_notes | string | null | Saved adjustment notes. |
created_by | integer | null | Creator user id. |
final_total, total_amount_recovered | number | null | Adjustment totals. Returned as null when the token user lacks view_purchase_price. |
location | object | Location summary with id and name. |
lines | array<StockAdjustmentLine> | Adjustment lines ordered by line id. |
| Field | Type | Description |
|---|---|---|
data | StockAdjustmentDetail | The requested stock adjustment payload. |
| Status | When it happens | Response shape |
|---|---|---|
200 | The stock adjustment was returned successfully. | { "data": { ... } } or CSV download. |
403 | The token user lacks stock-adjustment list access. | { "message": "Unauthorized" } |
404 | The stock adjustment id does not exist in the visible query. | { "message": "Not found" } |
422 | The query string failed validation. | Laravel validation JSON. |
Creates a stock adjustment and immediately maps its lines against purchase quantities.
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/v1/integration/stock-adjustments |
| Permission | stock_adjustment.create. |
| Demo and subscription | Returns 403 in demo environments and 402 when the business subscription is inactive. |
| Location rule | location_id must belong to the business and must be inside the token user's permitted locations. |
| Product rule | Each product_id must belong to the business, and each variation_id must belong to the selected product. |
| Reference behavior | ref_no is auto-generated from the stock-adjustment reference counter when omitted. |
| Default totals | total_amount_recovered and final_total default to 0 when omitted. |
| Stock behavior | Each line immediately decreases available quantity at the selected location before the controller creates the transaction row and maps the adjustment against purchase stock. |
| Success response | 201 with one StockAdjustmentDetail object. |
| Field | Type | Required | Description |
|---|---|---|---|
location_id | integer | Yes | Business location id. |
transaction_date | string | Yes | Date string parsed through ProductUtil::uf_date(..., true). |
adjustment_type | string | Yes | normal or abnormal. |
products | array<StockAdjustmentCreateLineInput> | Yes | One or more adjustment lines. |
additional_notes | string | null | No | Optional adjustment notes. |
total_amount_recovered | number | null | No | Optional recovered amount. Defaults to 0. |
final_total | number | null | No | Optional final total. Defaults to 0. |
ref_no | string | null | No | Optional custom adjustment reference. |
StockAdjustmentCreateLineInput object| Field | Type | Required | Description |
|---|---|---|---|
product_id | integer | Yes | Business product id. |
variation_id | integer | Yes | Variation id belonging to the selected product. |
quantity | number | Yes | Adjustment quantity parsed with num_uf. |
unit_price | number | Yes | Adjustment unit price parsed with num_uf. |
lot_no_line_id | integer | null | No | Optional purchase-line id used to preserve lot linkage on the adjustment line. |
| Field | Type | Description |
|---|---|---|
data | StockAdjustmentDetail | The created stock adjustment payload. |
| Status | When it happens | Response shape |
|---|---|---|
201 | The stock adjustment was created successfully. | { "data": { ... } } |
402 | The business subscription is inactive. | { "message": string } |
403 | Demo mode is active or the token user lacks stock_adjustment.create. | { "message": string } |
422 | The request body failed validation, the selected location is not permitted, the products do not belong to the business, or purchase-to-stock mapping raised a PurchaseSellMismatch. | Laravel validation JSON or { "message": string }. |
500 | The stock adjustment transaction failed unexpectedly. | { "message": "something_went_wrong" } |
Deletes a visible stock adjustment and restores stock quantities for its lines.
| Property | Value |
|---|---|
| Method | DELETE |
| Path | /api/v1/integration/stock-adjustments/{id} |
| Permission | stock_adjustment.delete. |
| Visibility | The target adjustment must be in a permitted location. When the token user lacks stock_adjustment.view but has view_own_stock_adjustment, delete is limited to rows they created. A user with delete permission but without view permissions can still delete visible rows in permitted locations. |
| Demo mode | Returns 403 in demo environments. |
| Delete behavior | The controller reloads all stock-adjustment lines, adds their quantities back to the location, removes purchase-mapping quantities through mapPurchaseQuantityForDeleteStockAdjustment(), then deletes the adjustment transaction. |
| Success response | 200 with the deleted id. |
| Field | Type | Description |
|---|---|---|
message | string | Localized delete-success message. |
data.id | integer | The deleted stock-adjustment id. |
| Status | When it happens | Response shape |
|---|---|---|
200 | The stock adjustment was deleted successfully. | { "message": string, "data": { "id": integer } } |
403 | Demo mode is active or the token user lacks stock_adjustment.delete. | { "message": string } |
404 | The stock adjustment id does not exist in the visible query. | { "message": "Not found" } |
500 | The stock adjustment delete transaction failed unexpectedly. | { "message": "something_went_wrong" } |