Home Integration API reference

Integration API reference

REST API for integrations and external apps

Stock transfers

List stock transfers

Lists stock transfer pairs by reading the parent sell_transfer row and its linked purchase_transfer row.

Endpoint summary

PropertyValue
MethodGET
Path/api/v1/integration/stock-transfers
Permissionstock_transfer.view, stock_transfer.create, or stock_transfer.view_own.
VisibilityIf locations are restricted, a row is returned when either the source or destination location is permitted. With only stock_transfer.view_own, rows are limited to transfers whose purchase side was created by the token user.
Status behaviorCompleted transfers are stored on the sell side as final. The status filter accepts both completed and final, but current API-created completed transfers appear as final in the response.
CSV behaviorformat=csv streams all matching rows with a UTF-8 BOM and ignores page and per_page. location_from and location_to are JSON-encoded in CSV cells.
Success response200 with paginated StockTransferRow rows.

Query parameters

ParameterTypeRequiredDescription
per_page, pageintegerNoPagination controls. per_page accepts 1 to 100 and defaults to 20.
start_date, end_datestringNoOptional Y-m-d bounds on transaction_date. The date filter is only applied when both values are present.
statusstringNopending, in_transit, completed, or final.
location_from_id, location_to_idintegerNoOptional source and destination location filters.
qstringNoMinimum 2 characters when sent. Matches reference number, notes, numeric id, and source or destination location names.
formatstringNojson (default) or csv.

StockTransferRow object

FieldTypeDescription
idintegerParent sell_transfer id.
ref_nostring | nullTransfer reference number.
transaction_datestring | nullISO-8601 transfer timestamp.
statusstring | nullSell-side transfer status. Completed transfers appear as final.
final_total, shipping_chargesnumber | nullStored transfer totals.
additional_notesstring | nullSaved transfer notes.
purchase_transfer_idinteger | nullLinked purchase_transfer id.
location_from, location_toobjectLocation summaries with id and name.

Top-level JSON response

FieldTypeDescription
dataarray<StockTransferRow>The current result page.
meta.current_page, meta.last_page, meta.per_page, meta.totalintegerLaravel paginator metadata.

Status codes

StatusWhen it happensResponse shape
200The stock transfer list was returned successfully.{ "data": [...], "meta": { ... } } or CSV download.
403The token user lacks stock-transfer list access.{ "message": "Unauthorized" }
422The query string failed validation or q was shorter than 2 characters.Laravel validation JSON or { "message": string }.

Get stock transfer

Returns one stock transfer pair by the parent sell_transfer id.

Endpoint summary

PropertyValue
MethodGET
Path/api/v1/integration/stock-transfers/{id}
Path parameter{id} is the parent sell_transfer id returned by the list endpoint.
PermissionSame permission and visibility rules as List stock transfers.
CSV behaviorformat=csv streams one UTF-8 BOM row whose data_json column matches the JSON data payload.
Success response200 with one StockTransferDetail object.

StockTransferLine object

FieldTypeDescription
idintegerSell-line id.
product_id, variation_idintegerProduct and variation ids on the sell side of the transfer.
product_labelstringRendered product label built from the product and variation names.
sub_skustring | nullVariation SKU.
quantitynumberTransferred sell quantity.
unit_price, unit_price_inc_tax, item_taxnumber | nullSell-line pricing fields.
line_taxobject | nullTax summary with id, name, and amount.

StockTransferDetail object

FieldTypeDescription
idintegerParent sell_transfer id.
purchase_transfer_idintegerLinked purchase_transfer id.
ref_nostring | nullTransfer reference number.
transaction_datestring | nullISO-8601 transfer timestamp.
statusstring | nullSell-side transfer status. Completed transfers appear as final.
final_total, shipping_chargesnumber | nullStored transfer totals.
additional_notesstring | nullSaved transfer notes.
location_from, location_toobjectLocation summaries with id and name.
linesarray<StockTransferLine>Sell-side transfer lines in line-id order.

Top-level JSON response

FieldTypeDescription
dataStockTransferDetailThe requested stock transfer payload.

Status codes

StatusWhen it happensResponse shape
200The stock transfer was returned successfully.{ "data": { ... } } or CSV download.
403The token user lacks stock-transfer list access.{ "message": "Unauthorized" }
404The sell-transfer id, linked purchase-transfer row, or visibility check failed.{ "message": "Not found" }
422The query string failed validation.Laravel validation JSON.

Create stock transfer

Creates a stock transfer pair by inserting a parent sell_transfer row and a linked purchase_transfer row.

Endpoint summary

PropertyValue
MethodPOST
Path/api/v1/integration/stock-transfers
Permissionstock_transfer.create.
Demo and subscriptionReturns 403 in demo environments and 402 when the business subscription is inactive.
Location rulelocation_id and transfer_location_id must belong to the business, must be different, and both must be inside the token user's permitted locations when location access is restricted.
Status behaviorThe request accepts pending, in_transit, or completed. When completed is sent, the sell side is stored as final and the purchase side is stored as received.
Stock behaviorWhen the request status is completed, stock is decreased at the source location and increased at the destination for lines whose enable_stock flag resolves truthy, then the transfer lines are mapped to purchase lines.
Reference behaviorref_no is auto-generated from the stock-transfer reference counter when omitted.
Total behaviorfinal_total defaults to the sum of line totals plus shipping_charges when omitted.
Success response201 with one StockTransferDetail object.

Request body

FieldTypeRequiredDescription
location_idintegerYesSource location id.
transfer_location_idintegerYesDestination location id. Must differ from location_id.
transaction_datestringYesDate string parsed through ProductUtil::uf_date(..., true).
statusstringYespending, in_transit, or completed.
productsarray<StockTransferCreateLineInput>YesOne or more transfer lines.
ref_nostring | nullNoOptional custom transfer reference.
additional_notesstring | nullNoOptional transfer notes.
shipping_chargesstring | number | nullNoOptional shipping amount parsed with num_uf. Defaults to 0.
final_totalstring | number | nullNoOptional explicit final total parsed with num_uf.

StockTransferCreateLineInput object

FieldTypeRequiredDescription
product_idintegerYesBusiness product id. The controller performs a business-level existence check after validation.
variation_idintegerYesVariation id belonging to the selected product.
quantitystring | numberYesTransfer quantity parsed with num_uf.
unit_pricestring | numberYesTransfer unit price parsed with num_uf.
enable_stockboolean | nullNoOptional stock flag. When omitted, the controller falls back to the product's enable_stock setting.
product_unit_id, sub_unit_idinteger | nullNoOptional sub-unit metadata copied into the sell-side line builder.
base_unit_multipliernumber | nullNoOptional multiplier used to convert purchase-side quantity and price values into base-unit storage.
lot_no_line_idinteger | nullNoOptional purchase-line id used to copy lot number and expiry metadata into the purchase-transfer line when a matching purchase line exists.

Top-level JSON response

FieldTypeDescription
dataStockTransferDetailThe created stock transfer payload.

Status codes

StatusWhen it happensResponse shape
201The stock transfer pair was created successfully.{ "data": { ... } }
402The business subscription is inactive.{ "message": string }
403Demo mode is active, the token user lacks stock_transfer.create, or the token user may not access both transfer locations.{ "message": string }
422The request body failed validation or a product or variation check failed during line enrichment.Laravel validation JSON.
500The transfer transaction failed unexpectedly or the linked purchase-transfer row could not be reloaded after creation.{ "message": string }

Update stock transfer status

Updates the workflow state of an existing stock transfer pair.

Endpoint summary

PropertyValue
MethodPOST
Path/api/v1/integration/stock-transfers/{id}/update-status
Path parameter{id} is the parent sell_transfer id.
Permissionstock_transfer.update.
VisibilityThe endpoint checks the same permitted-location logic as list and show. The view_own owner restriction is applied only when the token user has stock_transfer.view_own but not stock_transfer.view.
Demo modeReturns 403 in demo environments.
Status behaviorThe request accepts pending, in_transit, or completed. When completed is sent, the sell side is saved as final and the purchase side is saved as received.
Stock behaviorStock movement and purchase/sell mapping are applied only when transitioning to completed from pending or in_transit, preventing double-application when the sell side is already final.
Success response200 with one StockTransferDetail object.

Request body

FieldTypeRequiredDescription
statusstringYespending, in_transit, or completed.

Top-level JSON response

FieldTypeDescription
dataStockTransferDetailThe updated stock transfer payload.

Status codes

StatusWhen it happensResponse shape
200The transfer status was updated successfully.{ "data": { ... } }
403Demo mode is active or the token user lacks stock_transfer.update.{ "message": string }
404The sell-transfer id, linked purchase-transfer row, or visibility check failed.{ "message": "Not found" }
422The request body failed validation.Laravel validation JSON.
500The status update transaction failed unexpectedly or the linked purchase-transfer row could not be reloaded afterward.{ "message": string }

Delete stock transfer

Deletes a stock transfer pair by the parent sell_transfer id.

Endpoint summary

PropertyValue
MethodDELETE
Path/api/v1/integration/stock-transfers/{id}
Path parameter{id} is the parent sell_transfer id.
Permissionstock_transfer.delete.
VisibilityThe same permitted-location and optional view_own owner checks used by the integration visibility helper are applied before deletion.
Demo modeReturns 403 in demo environments.
Edit-window ruleThe business transaction_edit_days value must still allow the sell-transfer row to be edited.
Delete blockersThe delete is rejected when any purchase line on the linked purchase_transfer has quantity_sold > 0.
Delete behaviorWhen mapped sell/purchase links exist, the controller decrements quantity_sold on purchase lines, reverses stock from destination to source, deletes the line-mapping rows, then deletes both transfer transactions.
Success response200 with the deleted id.

Top-level JSON response

FieldTypeDescription
messagestringLocalized delete-success message.
data.idintegerThe deleted parent sell_transfer id.

Status codes

StatusWhen it happensResponse shape
200The stock transfer pair was deleted successfully.{ "message": string, "data": { "id": integer } }
403Demo mode is active or the token user lacks stock_transfer.delete.{ "message": string }
404The sell-transfer id, linked purchase-transfer row, or visibility check failed.{ "message": "Not found" }
422The business edit window expired or one of the linked purchase lines has already been sold from the destination side.{ "message": string }
500The delete transaction failed unexpectedly.{ "message": "something_went_wrong" }