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
extra_reference - secondary/extra 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-update - 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 the following:

warehouse
source_warehouse
type='assembly'
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 items 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)

The 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

The 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-update)

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 a 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 a new purchase order based on current replenishment quantities

This request 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 a 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 a 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 request updates the (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 be counted 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 the "update received quantities" request below:

{
    "items": [
        {
            "id": "c20_123",
            "received": 3
        },
        "skip_background_jobs": false
    ]
}

Close an existing purchase order

Sets the 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 the received quantities in existing purchase order (single line item)

This request updates the (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
}