The Inventory Planner APIs (beta) provide real-time access to data in your Inventory Planner account and are intended for use by developers. Please note that the APIs are currently in beta and subject to change.

In this article:

APIs available

Stock Orders API
- Primarily used to sync purchase order information with a platform that is not connected to Inventory Planner, typically a 3PL. Information about purchase orders created in Inventory Planner can be pulled via the API, then information about receiving goods can be pushed back to Inventory Planner.
Reports API
- Commonly employed to pull data to create custom dashboards or reports. Inventory Planner has over 200 metrics available which can be queried to create a report outside of Inventory Planner.

Note: At this stage, data for products and variants cannot be pushed into Inventory Planner using the API. To push product and variant information into Inventory Planner, please use a CSV integration in tandem with the API in lieu of an established connected platform.

Authorization

To access an Inventory Planner API, you will first need an API authorization key. These keys are user-specific and only work for users with full access to the account.

To obtain a key:

Log in to Inventory Planner using your web browser
Go to Account > Settings > API
Click Generate key to generate API key
Save generated key

Use 'Delete key' if you would like to remove the key.

To authorize using your 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 your browser using your existing Inventory Planner session. This may be useful for making manual requests with your browser.

Making requests

For requests that modify (POST, PUT, PATCH), set your header to include Content-Type: application/json header. We also recommend including Accept: application/json in your header.

Resource URLs

There are two kinds of resources: an entity collection resource (list of items) and a single entity resource (single item). Every entity also has two names: a singular name and a plural name (usually obtained by adding 's').

The URL for a single entity resource is normally the child of the corresponding collection resource with an entity id appended. Additionally, if the entity has a collection field, the corresponding collection resource is the child of the entity resource, with the field name appended.

The base URL for the API is https://app.inventory-planner.com/

Here is an example:

Singular name is purchase-order , plural name is purchase-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 will optionally contain a result document with the following fields:

status - the status of the operation (success or error)
message - a human-readable message describing the operation (optional)

{
    "result": {
        "status": "success",
        "message": "Updated variant 12345"
    },
    ...

Timestamp fields in the response/request use the RFC822 format (for example, "2018-03-15T10:00:00+01:00")

GET (collection resource)

GET on a collection resource returns an entity list in JSON format. The response contains two fields:

meta is a document with information about the result set with the following fields:
- name - entity name
- total - total number of items
- count - number of items in this response
- limit - limit for this response (if paging)
<entity_plural_name> in the response is the list of entity values.
- See the description of a 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, the entity_singular_name field contains the entity fields.

{
    "variant": {
        "id": 17948565252,
        ...
    }
}

PATCH (single resource)

PATCH on a single item resource partially modifies the entity using an update contained in the body of a 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 being updated.

Only writable fields can be modified. Read-only and unknown fields in the request are ignored. See the description of the particular API endpoints in our Stock Order API article.

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 an entity using an ID provided in the URL based on the request contents. PUT is only available on some resources.

Only writable fields can be modified. Read-only and unknown fields in the request are ignored. See the description of particular API endpoints in our Stock Order API article.

POST (collection resource)

This request creates new collection items based on the request contents.

In the request, the entity_singular_name should contain the item fields.

In the response, the entity_singular_name will contain all of the new entity fields after creation.

Restricting fields

The fields parameter contains a comma-separated list of fields to return. For example, fields=id,sku,replenishment returns 3 fields.

We recommend always specifying the fields parameter to reduce bandwidth usage.

Paging

Paging is controlled by two parameters:

limit - the number of results to return (maximum 1000)
page - page number

Filtering

You can filter a field by using a parameter with same name. You can also use a field name and an operator (separated by '_').

The following operators are available:

eq (default) - equal
eqi - equal ignoring case
ne - not equal
gt , gte , lt , lte - 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 - match regular expression
in - equal on (comma-separated) values

Here are some examples:

sku=SKU1 or sku_eq=SKU1 retrieves the variant with a given SKU
replenishment_gt=0 (or replenishment_gte=1 ) retrieves variants with a non-zero replenishment number

Removed variants are not returned by default. To retrieve them, use the removed=true parameter.

Sorting

To sort your results, add the <field>_sort parameter with the possible values of asc/desc or 1/-1 .

For example, use replenishment_sort=desc or replenishment_sort=-1 to sort by the replenishment field in descending order.

Misc

You can pretty print JSON output by adding the pretty=1 parameter to the request.

Endpoints

See the specific API documentation for relevant endpoints:

Stock Orders API
- Purchase orders
- Transfers and assembly Orders
- Purchase order items
- Purchase order connections
- Purchase order stock updates

Reports API
- Variants
- Variant vendors