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 number

  • status - status

  • created_date - creation date

  • expected_date - expected date

  • payment_date - payment date

  • shipment_date - shipment date

  • received_date - received date (last)

  • last_modified - last modified at

  • readonly - true if PO cannot be edited in Inventory Planner

  • source_type - 'warehouse' for transfers and assembly orders, 'vendor' for purchase orders

  • type - 'assembly' for assembly orders, 'transfer' for transfers, 'po' or empty for purchase orders

  • vendor - vendor

  • source_warehouse - source warehouse for transfers and assembly orders

  • source - vendor or source_warehouse

  • warehouse - warehouse

  • vendor_address - vendor address

  • billing_address - billing address

  • shipping_address - shipping address

  • email - vendor email

  • attn - Attn

  • notes - Notes

  • shipment_method - shipment method

  • payment_terms - payment terms

  • shipping_handling - shipping/handling charges in order currency

  • shipping_handling_tax shipping/handling tax in order currency

  • currency - order currency

  • discount_enabled - true if discount column is enabled

  • default_discount - default discount for line items

  • uom_ordering

  • uom_round

  • moq

  • items - 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 PDF

  • addMySKUs - true to add variant SKU to line items

  • addVendorSKUs - true to add variant vendor reference/SKU to line items

  • addBarcodes - true to add variant barcode to line items

  • addCategories - true to add variant categories to line items

  • useTitlesAsVendorName - true to use variant title as line item title, false to use variant vendor product name

  • custom_fields - custom fields in field=value format

  • connections - 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 id

  • title - line item title

  • sku - line item sku

  • barcode - line item barcode

  • image - line item image URL

  • vendor_name - line item vendor name

  • vendor_reference - line item vendor reference/SKU

  • uom_ordering - line item UOM

  • vendor_packaging - line item MOQ

  • source_stock - stock snapshot at source warehouse for transfers

  • in_stock - stock snapshot at destination warehouse

  • purchase_orders_qty - on order qty snapshot

  • transfer_units_in - transfer in qty snapshot

  • transfer_units_out - transfer out qty snapshot

  • replenishment - line item ordered (replenished) quantity

  • cost price - line item cost price

  • landing_cost_price - line item landing

  • tax - line item tax

  • discount - line item discount

  • cbm - line item cbm

  • received - line item received quantity

  • received_history - line item received history

  • components - 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 id

  • quantity - component quantity required to produce 1 unit of line item's assembly

  • sku - component SKU

  • title - component title

  • barcode - 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) name

  • connection_id - connection (internal) id

  • save_po - true if PO is saved into this connection

  • id - id of this purchase order for this connection

  • reference - 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 updated

  • items - information about updated line items

Items are an array of documents with the following fields:

  • id - line item variant id

  • stock_before - stock in connection before update

  • delta - stock delta pushed in connection

  • error - 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"

},

}

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

}








Did this answer your question?