Inventory Planner Public API

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. 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 , , tab Use Generate key to generate API 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: Account: 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 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 is purchase-orders . , plural name is . api/v1/purchase-orders is the collection resource. is the collection resource. api/v1/purchase-orders/12345 is the single entity resource for the purchase order id 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. 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 or error ) - status of operation ( or ) 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 name - entity name total - total number of items - total number of items count - number of items in this response - number of items in this response limit - limit for this response (if paging) 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) - equal (default) - equal eqi - equal ignoring case - equal ignoring case ne - not equal - not equal gt , gte , lt , lte - greater than, greater than or equal, less then, less than or equal , , , - greater than, greater than or equal, less then, less than or equal range - match numeric value in range (separated by dash), for example, 5-10 - match numeric value in range (separated by dash), for example, 5-10 match - match regular expression - match regular expression in - equal on (comma-separated) values Here are some examples: sku=SKU1 or sku_eq=SKU1 to retrieve variant with given SKU or to retrieve variant with given SKU replenishment_gt=0 (or replenishment_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 _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) - variant identifier (read-only) sku - SKU (read-only) - SKU (read-only) lead_time - lead time - lead time review_period - days of stock - days of stock replenishment - current replenishment number - current replenishment number under_value - forecasted lost revenue - forecasted lost revenue oos - 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 price - vendor cost price landing_cost_price - vendor landing cost price - vendor landing cost price vendor_reference - vendor reference/sku - vendor reference/sku vendor_name - vendor variant name (title) - vendor variant name (title) vendor_packaging - MOQ, minimum order quantity - MOQ, minimum order quantity uom_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) - purchase order identifier in Inventory Planner (read-only) reference - number/reference number - number/reference number status - status - status created_date - creation date - creation date expected_date - expected date - expected date payment_date - payment date - payment date shipment_date - shipment date - shipment date received_date - received date (last) - received date (last) last_modified - last modified at - last modified at readonly - true if PO cannot be edited in Inventory Planner - true if PO cannot be edited in Inventory Planner source_type - 'warehouse' for transfers, 'vendor' for purchase orders - 'warehouse' for transfers, 'vendor' for purchase orders vendor - vendor - vendor source_warehouse - source warehouse for transfers - source warehouse for transfers source - vendor or source_warehouse - vendor or source_warehouse warehouse - warehouse - warehouse vendor_address - vendor address - vendor address billing_address - billing address - billing address shipping_address - shipping address - shipping address email - vendor email - vendor email attn - Attn - Attn notes - Notes - Notes shipment_method - shipment method - shipment method payment_terms - payment terms - payment terms shipping_handling - shipping/handling charges in order currency - shipping/handling charges in order currency shipping_handling_tax shipping/handling tax in order currency shipping/handling tax in order currency currency - order currency - order currency discount_enabled - true if discount column is enabled - true if discount column is enabled default_discount - default discount for line items - default discount for line items uom_ordering uom_round moq items - line items (refer to "Purchase order items") - line items (refer to "Purchase order items") total - total cost in order currency (read-only) - total cost in order currency (read-only) total_ordered - total ordered qty (read-only) - total ordered qty (read-only) total_received - total received qty (read-only) - total received qty (read-only) shop_name - shop name in PDF - shop name in PDF addMySKUs - true to add variant SKU to line items - true to add variant SKU to line items addVendorSKUs - true to add variant vendor reference/SKU to line items - true to add variant vendor reference/SKU to line items addBarcodes - true to add variant barcode to line items - true to add variant barcode to line items addCategories - true to add variant categories to line items - 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 - true to use variant title as line item title, false to use variant vendor product name custom_fields - custom fields in field=value format - custom fields in field=value format connections - connection information (refer to "Purchase order connections") - connection information (refer to "Purchase order connections") stock_updates - information about stock updates pushed to connection (refer to "Purchase order stock updates") 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 id - line item variant id title - line item title - line item title sku - line item sku - line item sku barcode - line item barcode - line item barcode image - line item image URL - line item image URL vendor_name - line item vendor name - line item vendor name vendor_reference - line item vendor reference/SKU - line item vendor reference/SKU uom_ordering - line item UOM - line item UOM vendor_packaging - line item MOQ - line item MOQ source_stock - stock snapshot at source warehouse for transfers - stock snapshot at source warehouse for transfers in_stock - stock snapshot at destination warehouse - stock snapshot at destination warehouse purchase_orders_qty - on order qty snapshot - on order qty snapshot transfer_units_in - transfer in qty snapshot - transfer in qty snapshot transfer_units_out - transfer out qty snapshot - transfer out qty snapshot replenishment - line item ordered (replenished) quantity - line item ordered (replenished) quantity cost price - line item cost price - line item cost price landing_cost_price - line item landing - line item landing tax - line item tax - line item tax discount - line item discount - line item discount cbm - line item cbm - line item cbm received - line item received quantity - line item received quantity received_history - line item received history Line item received history is an array of the documents with the following fields: date - received date time stamp (in Unix format) - received date time stamp (in Unix format) value - received qty 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) name - connection (internal) name save_po - true if PO is saved into this connection - true if PO is saved into this connection id - id of this purchase order for this connection - 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 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 purchase order based on current replenishment quantities and save it into a TradeGecko 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": "TG.30636", "save_po": true } ] } } Response: { "purchase-order": { "status": "active", "source_warehouse": "w1", "warehouse": "w2", "expected_date": "2018-03-15", "connections": [ { "connection": "TG.30636", "save_po": true, "id": "t410034", "reference": "ST0021", "status": "success" } ], "items": [ ... ], "id": "5a83236c3e78599f6ea5d180", ... }, "result": { "status": "success", "message": "Created purchase-order 5a83236c3e78599f6ea5d180" } } 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 TradeGecko connection PUT /api/v1/purchase-orders/5a8321b33e7859f568a5d180/connections/TG.30636 { "connection": { "save_po": true } } Response: { "connection": { "save_po": true, "connection": "TG.30636", "id": 815902, "reference": "PO0043", "status": "success" }, "result":{ "status":"success", "message":"Updated purchase-order 5a8321b33e7859f568a5d180 connection TG.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:

Still puzzling over something?

Attaching documents to Purchase Orders

Changing platforms connected to Inventory Planner

IP Warehouse

Replenishment Report [Video]

Receiving inventory and pushing inventory to your store