In this article:
When To Use This API
The Stock Orders API is most commonly used to sync stock order information with a platform that is not connected to Inventory Planner, such as a 3PL. Details about stock orders created in Inventory Planner are pulled by the API, then the information is pushed back to Inventory Planner. The term 'stock order' includes purchase orders, transfers, and assembly orders.
Accurate and timely updates to stock orders in Inventory Planner improve the accuracy of replenishment recommendations by taking incoming stock and the timing of arrivals into consideration.
Working with Inventory Planner APIs
To get started, refer to the Inventory Planner Public API article for information including authorization and making requests.
API endpoints
Purchase orders (api/v1/purchase-orders) and purchase order (api/v1/purchase-orders/{id})
The following fields for purchase order are currently supported:
id- purchase order identifier in Inventory Planner (read-only)reference- number/reference numberstatus- statuscreated_date- creation dateexpected_date- expected datepayment_date- payment dateshipment_date- shipment datereceived_date- received date (last)last_modified- last modified atreadonly- true if PO cannot be edited in Inventory Plannersource_type- 'warehouse' for transfers and assembly orders, 'vendor' for purchase orderstype- 'assembly' for assembly orders, 'transfer' for transfers, 'po' or empty for purchase ordersvendor- vendorsource_warehouse- source warehouse for transfers and assembly orderssource- vendor or source_warehousewarehouse- warehousevendor_address- vendor addressbilling_address- billing addressshipping_address- shipping addressemail- vendor emailattn- Attnnotes- Notesshipment_method- shipment methodpayment_terms- payment termsshipping_handling- shipping/handling charges in order currencyshipping_handling_taxshipping/handling tax in order currencycurrency- order currencydiscount_enabled- true if discount column is enableddefault_discount- default discount for line itemsuom_orderinguom_roundmoqitems- line items (refer to "Purchase order items")total- total cost in order currency (read-only)total_ordered- total ordered qty (read-only)total_received- total received qty (read-only)shop_name- shop name in PDFaddMySKUs- true to add variant SKU to line itemsaddVendorSKUs- true to add variant vendor reference/SKU to line itemsaddBarcodes- true to add variant barcode to line itemsaddCategories- true to add variant categories to line itemsuseTitlesAsVendorName- true to use variant title as line item title, false to use variant vendor product namecustom_fields- custom fields in field=value formatconnections- connection information (refer to "Purchase order connections")stock_updates- information about stock updates pushed to connection (refer to "Purchase order stock updates")
Transfers and Assembly Orders
Transfers and Assembly orders use the same API endpoints as Purchase orders.
To create Assembly orders it is necessary to set warehouse, source_warehouse, type='assembly' and components for each line item.
Purchase order items (api/v1/purchase-orders/{id}/items) and item (api/v1/purchase-orders/{id}/items/{item_id})
The following fields for purchase order item are currently supported (unless marked as Read-Only the field is editable):
id- line item variant idtitle- line item titlesku- line item skubarcode- line item barcodeimage- line item image URLvendor_name- line item vendor namevendor_reference- line item vendor reference/SKUuom_ordering- line item UOMvendor_packaging- line item MOQsource_stock- stock snapshot at source warehouse for transfersin_stock- stock snapshot at destination warehousepurchase_orders_qty- on order qty snapshottransfer_units_in- transfer in qty snapshottransfer_units_out- transfer out qty snapshotreplenishment- line item ordered (replenished) quantitycost price- line item cost pricelanding_cost_price- line item landingtax- line item taxdiscount- line item discountcbm- line item cbmreceived- line item received quantityreceived_history- line item received historycomponents- list of components needed to produce line item (for assembly orders)
Line item received history is an array of the documents with the following fields:
date- received date time stamp (in Unix format)value- received qty
Line item components is an array of documents with the following fields:
id- component variant idquantity- component quantity required to produce 1 unit of line item's assemblysku- component SKUtitle- component titlebarcode- component barcode
Purchase order connections (api/v1/purchase-orders/[id]/connections) and connection (api/v1/purchase-orders/[id]/connections/[connection])
The following fields for purchase order connection are currently supported:
status- One of:success,error,run(save process is running),queued(waiting for QuickBooks Desktop update).connection- connection (internal) nameconnection_id - connection (internal) idsave_po- true if PO is saved into this connectionid- id of this purchase order for this connectionreference- reference of this purchase order for this connection
Purchase order stock updates (api/v1/purchase-orders/{id}/stock_updates)
The following fields for purchase order stock update are currently supported:
forDst- true if stock was updated in destination warehouse, or false if stock was update in source warehouse (possible for transfers only)wh- warehouse where stock was updateditems- information about updated line items
Items are an array of documents with the following fields:
id- line item variant idstock_before- stock in connection before updatedelta- stock delta pushed in connectionerror- non empty error message if stock update for this line item failed
API usage examples
Update variant vendor data/Assign variant vendor
PUT /api/v1/variants/1/vendors/mysupplier
{
"vendor": {
"cost_price": 2.1,
"vendor_reference": "R"
}
}
Response:
{
"vendor": {
"cost_price": 2.1,
"vendor_reference": "R",
"vendor_name": "N",
"t": "vendor",
"s": "user",
"n": "mysupplier"
},
"result": {
"status": "success",
"message": "Vendor data vendor mysupplier updated"
}
}
Use DELETE on variant vendor resources to delete previously assigned vendor and associated data.
Create new purchase order based on current replenishment quantities
This creates a new purchase order containing items for variants of vendor_v1 and current replenishment quantities greater than 3.
POST /api/v1/purchase-orders
{
"purchase-order": {
"status": "OPEN",
"reference": "MY_PO_20",
"expected_date": "2018-03-15",
"vendor": "vendor_1",
"warehouse": "w1",
"variants_filter": {
"vendor": "vendor_1",
"replenishment_gt": 3
}
}
}
Response:
{
"purchase-order": {
"status": "draft",
"vendor": "Wonka Candy (DEMO)",
"expected_date": "2018-03-15",
"items": [
...
],
"id": "5a8322013e7859ae69a5d180",
...
},
"result": {
"status": "success",
"message": "Created purchase-order 5a8322013e7859ae69a5d180"
}
}
Create new transfer based on current replenishment quantities and save it into a Brightpearl connection
POST /api/v1/purchase-orders
{
"purchase-order": {
"status": "OPEN",
"source_warehouse": "w1",
"warehouse": "w2",
"expected_date": "2018-03-15",
"variants_filter": {
"replenishment_gt": 3
},
"connections": [
{
"connection": "inventoryplannerdev.brightpearl.com",
"save_po": true
}
]
}
}
Response:
{
"purchase-order": {
"status": "active",
"source_warehouse": "w1",
"warehouse": "w2",
"expected_date": "2018-03-15",
"connections": [
{
"connection": "inventoryplannerdev.brightpearl.com",
"save_po": true,
"id": "t410034",
"reference": "ST0021",
"status": "success"
}
],
"items": [
...
],
"id": "5a83236c3e78599f6ea5d180",
...
},
"result": {
"status": "success",
"message": "Created purchase-order 5a83236c3e78599f6ea5d180"
}
}
Create new Assembly order
POST /api/v1/purchase-orders
{
"purchase-order": {
"type": "assembly",
"status": "OPEN",
"reference": "MY_AO_20",
"expected_date": "2018-03-15",
"warehouse": "w1",
"source_warehouse": "w1",
"items": [
{
"id": "c1_1",
"sku": "T-1",
"title": "Office table",
"replenishment": 10,
"components": [
{
"id": "c1_2",
"quantity": 1,
"sku": "C-1",
"title": "Table top",
},
{
"id": "c1_3",
"quantity": 4,
"sku": "C-2",
"title": "Table leg"
}
]
}
]
}
}
Update received quantities in the existing purchase order (multiple line items)
This updates (total) received quantity for two line items with variant IDs 123/124.
PATCH /api/v1/purchase-orders/5a8321b33e7859f568a5d180/items
{
"items": [
{
"id": "c20_123",
"received": 7,
},
{
"id": "c20_124",
"received": 5,
}
]
}
Response:
{
"items": [
{
"id": "c20_123",
"replenishment": 10,
"received": 7
},
{
"id": "c20_124",
"replenishment": 20,
"received": 5
}
],
"result": {
"status": "success",
"message": "2 updated, from total 2 items"
},
}
NOTE: Any changes to the stock orders you make via API calls will not affect the current forecast and replenishment analysis but they will reflect once the data is recalculated after the "nightly sync". To make the necessary recalculations right after a change, you can use the parameter "skip_background_jobs" as in "update received quantities" request below:
{
"items": [
{
"id": "c20_123",
"received": 3
},
"skip_background_jobs": false
]
}
Close existing purchase order
Set status field to CLOSED
PATCH /api/v1/purchase-orders/5a8321b33e7859f568a5d180
{
"purchase-order": {
"status": "CLOSED",
}
}
Response:
{
"purchase-order": {
"status": "CLOSED",
"id": "5a8322013e7859ae69a5d180",
...
},
"result": {
"status": "success",
"message": "Updated purchase-order 5a8322013e7859ae69a5d180"
}
}
Update received quantities in existing purchase order (single line item)
This updates (total) received quantity for line item with variant ID 123.
PATCH /api/v1/purchase-orders/5a8321b33e7859f568a5d180/items/123
{
"item": {
"id": "c20_123",
"received": 13
}
}
Response:
{
"items": {
"id": 123,
"replenishment": 20,
"received": 13
},
"result": {
"status": "success",
"message": "Purchase order \"1\" item i2 updated"
}
}
Save existing purchase order into a Brightpearl connection
PUT /api/v1/purchase-orders/5a8321b33e7859f568a5d180/connections/QuickBooksCommerce.30636
{
"connection": {
"save_po": true
}
}
Response:
{
"connection": {
"save_po": true,
"connection": "inventoryplannerdev.brightpearl.com",
"id": 815902,
"reference": "PO0043",
"status": "success"
},
"result":{
"status":"success",
"message":"Updated purchase-order 5a8321b33e7859f568a5d180 connection inventoryplannerdev.brightpearl.com"
}
}
Retrieve stock updates available for push-to-destination connection (computed based on received quantities and previous stock updates)
GET /api/v1/purchase-orders/5c9deeb5178a3816620d8362/stock-update?forDst=true
Response:
{
"items": [
{
"id": 123,
"delta": 10,
"stock_before": 0
},
{
"id": 456,
"delta": 5,
"stock_before": 1,
},
...
],
"forDst": true,
"wh": 13434355
}
Push stock updates to destination connection
POST /api/v1/purchase-orders/5c9deeb5178a3816620d8362/stock-update
{
"stock_update":{
"items": [
{
"id": 123,
"delta": 10,
"stock_before": 0
},
{
"id": 456,
"delta": 5,
"stock_before": 1,
},
...
]
},
"forDst": true
}
Response:
{
"items": [
{
"id": 123,
"delta": 10,
"stock_before": 0
},
{
"id": 456,
"delta": 5,
"stock_before": 1,
"error": "Update request failed"
},
...
],
"forDst": true
}