The Inventory Planner API (beta) provides realtime access to data in your Inventory Planner account and is intended to be used by developers. Please note that the API is currently in beta and subject to change.
The two primary use cases for Inventory Planner's API are:
Syncing purchase order information with a platform that is not connected to Inventory Planner. This is typically a 3PL. Detail about purchase orders created in Inventory Planner can be pulled via the API, then receiving information can be pushed back to Inventory Planner.
Pulling data to create custom dashboards or reports. Inventory Planner has over 200 metrics available. These can be queried to create a report outside of Inventory Planner.
Authorization
To access Inventory Planner API, first you need an API authorization key. The key is associated with user. To obtain the key:
Log in to Inventory Planner using web browser
Go to Account, Settings, API tab
Use Generate key to generate API key
Save generated key
Use 'Delete key' if you would like to remove the key.
To authorize using API key, add the following two headers to HTTP requests:
Authorization: <API_key>
Account: <account_id>
Note that you can also access the API from the browser using existing Inventory Planner session. This may be useful for making manual requests with browser.
Making Requests
Requests that modify (POST, PUT, PATCH), set Content-Type: application/json header. We also recommend to set Accept: application/json header.
Resource URLs
There are two kinds of resources: entity collection resource (list of items) and single entity resource (single item). Every entity also has two names: singular name and plural name (usually obtained by adding 's'). The URL for single entity resource is normally the child of corresponding collection resource with entity id appended. Additionally, if the entity has a collection field, corresponding collection resource is the child of the entity resource, with field name appended.
The base URL for API is https://app.inventory-planner.com/
Here is an example:
Singular name is
purchase-order
, plural name ispurchase-orders
.api/v1/purchase-orders
is the collection resource.api/v1/purchase-orders/12345
is the single entity resource for the purchase order id 12345.api/v1/purchase-orders/12345/items
is the collection resource for items for the purchase order id 12345.api/v1/purchase-orders/12345/items/987
is the single entity resource for item id 987 for the purchase order id 12345.
Request and response structure
The response optionally contains result
document with the following fields:
status
- status of operation (success
orerror
)message
- human-readable message describing the operation (optional)
{
"result": {
"status": "success",
"message": "Updated variant 12345"
},
...
Timestamp fields in response/request use RFC822 format (for example, "2018-03-15T10:00:00+01:00")
GET (collection resource)
GET on a collection resource returns entity list in JSON format. The response contains two fields:
meta
is a document with information about result set with the following fields:
name
- entity nametotal
- total number of itemscount
- number of items in this responselimit
- limit for this response (if paging)
<entity_plural_name>
in the response is the list of entity values. See description of particular API endpoint for more information.
{
"meta": {
"name": "variants",
"total": 13,
"limit": "20",
"page": 0
},
"variants": [
{
"id": 17948565252,
...
}
]
}
GET (single resource)
GET on single item resource returns the entity in JSON format. In the response, entity_singular_name
field contains the entity fields.
{
"variant": {
"id": 17948565252,
...
}
}
PATCH (single resource)
PATCH on single item resource partially modifies the entity using update contained in the body of request in JSON format. In the request, entity_singular_name
should contain the updated fields. In the response, entity_singular_name
will return all of the entity fields after update.
Only writable fields can be modified. Read-only and unknown fields in the request are ignored. See the description of particular API endpoint for information about fields.
PATCH request example:
PATCH /api/v1/variants/17948565252
{
"variant": {
"lead_time": 7,
"review_period": 21
}
}
PATCH response example:
{
"variant": {
"id": 17948565252,
"sku": "SKU1",
"lead_time": 7,
"review_period": 21,
...
}
}
PUT (single resource)
This request creates or fully updates entity with id provided in the URL based on request contents. PUT is only available on some resources.
POST (collection resource)
This request creates new collection item based on request contents. In the request, entity_singular_name
should contain the item fields. In the response, entity_singular_name
will contain all of the new entity fields after creation.
Restricting fields
fields
parameter contains comma-separated list of fields to return. For example, fields=id,sku,replenishment
returns 3 fields.
We recommend to always specify fields parameter to reduce bandwidth usage.
Paging
Paging is controlled by two parameters: limit
- the number of results to return and page
- page number. The maximum value for limit is 1000.
Filtering
You can filter by a field by using parameter with same name. You can also use field name and operator (separated by '_').
The following operators are available:
eq
(default) - equaleqi
- equal ignoring casene
- not equalgt
,gte
,lt
,lte
- greater than, greater than or equal, less then, less than or equalrange
- match numeric value in range (separated by dash), for example, 5-10match
- match regular expressionin
- equal on (comma-separated) values
Here are some examples:
sku=SKU1
orsku_eq=SKU1
to retrieve variant with given SKUreplenishment_gt=0
(orreplenishment_gte=1
) to retrieve variants with non-zero replenishment number
Removed variants are not returned by default. To retrieve them, use removed=true
parameter.
Sorting
Add <field>_sort
parameter with possible values asc/desc
or 1/-1
. For example, use replenishment_sort=desc
or replenishment_sort=-1
to sort by replenishment
field in descending order.
Misc
You can pretty print JSON output by adding pretty=1 parameter to the request
API endpoints
Variants (api/v1/variants) and variant (api/v1/variants/{id})
A variant corresponds to one variation of a product with particular features (for example, color and size) and contains both information downloaded from e-commerce platform and computed by Inventory Planner.
The following fields are currently supported:
id
- variant identifier (read-only)sku
- SKU (read-only)lead_time
- lead timereview_period
- days of stockreplenishment
- current replenishment numberunder_value
- forecasted lost revenueoos
- forecasted number of days to sell out
Variant vendors (api/v1/variants/[id]/vendors) and variant vendor (api/v1/variants/[id]/vendor/[vendor_id]
Each variant has associated list of vendor data. Vendor identifier (vendor_id) is the vendor name converted to low case. The following vendor data fields are available:
cost_price
- vendor cost pricelanding_cost_price
- vendor landing cost pricevendor_reference
- vendor reference/skuvendor_name
- vendor variant name (title)vendor_packaging
- MOQ, minimum order quantityuom_ordering
- UOM, units of measurement
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_tax
shipping/handling tax in order currencycurrency
- order currencydiscount_enabled
- true if discount column is enableddefault_discount
- default discount for line itemsuom_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 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
Tramsfers and Assembly orders use the same API endpoints as Purchase orders.
To create Assembly orders it's necesary 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:
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 the 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:
connection
- connection (internal) namesave_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 updated
items - information about updated line items
Items is an array of the 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
Retrieve sku, replenishment and forecasted lost revenue for first 50 variants by forecasted lost revenue
GET /api/v1/variants?fields=sku,replenishment,under_value&under_value_sort=desc&limit=50&page=0
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 resource 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 QuickBooks Commerce 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": "QuickBooksCommerce.30636",
"save_po": true
}
]
}
}
Response:
{
"purchase-order": {
"status": "active",
"source_warehouse": "w1",
"warehouse": "w2",
"expected_date": "2018-03-15",
"connections": [
{
"connection": "QuickBooksCommerce.30636",
"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 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 QuickBooks Commerce connection
PUT /api/v1/purchase-orders/5a8321b33e7859f568a5d180/connections/QuickBooksCommerce.30636
{
"connection": {
"save_po": true
}
}
Response:
{
"connection": {
"save_po": true,
"connection": "QuickBooksCommerce.30636",
"id": 815902,
"reference": "PO0043",
"status": "success"
},
"result":{
"status":"success",
"message":"Updated purchase-order 5a8321b33e7859f568a5d180 connection QuickBooksCommerce.30636"
}
}
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
}