Creating Inventory Counts (Stocktakes)

Workflow

NOTE: An inventory count is simply a specific type (\"type\": \"STOCKTAKE\") of a consignment.

Creating a new inventory count requires a few steps which need to be performed in a specific order.

1. Create a new inventory count

This can be done in one of 2 ways:

A new consignment is created with status = STOCKTAKE_SCHEDULED, will create a so-called scheduled inventory count. At this stage, no items are being added to the count yet. Before product count items are added the consignment's status needs to be updated to STOCKTAKE_IN_PROGRESS.
A count created with status = STOCKTAKE_IN_PROGRESS. This will launch a background task which will add inventory items based on filters. If no filters are delivered all products in the store will be used.

NOTE: Once a count is started (STOCKTAKE_IN_PROGRESS) filters cannot be modified.

WARNING: If an inventory count created without any filters and completed without any modifications to count items will reset the count values to 0 for all product in the store.

2. Count products

Make a request for every product that gets counted to updates its quantity. See Counting products.

3. Check the status

Make sure that the status of the consignment is definitely STOCKTAKE_IN_PROGRESS_PROCESSED. See Getting the inventory count.

4. Complete the count

This is done by updating the consignment with status = STOCKTAKE_COMPLETE. See Updating the inventory count.

NOTE: The count can be only completed (STOCKTAKE_COMPLETE) if the current status is STOCKTAKE_IN_PROGRESS_PROCESSED.

Filters

Filters can be used to create a partial count (i.e. count only some products in the store).
Available filter types are: product_type, brand, supplier, tag, product.
The value of the filter is simply an ID of an object of the respective type.
Every count can contain up to 25 filters.

Creating a new inventory count:

A new inventory count can be created with a POST request to the /api/2.0/consignments endpoint, with the following payload:

{
	"outlet_id": "b8ca3a65-011c-11e4-fbb5-5ff2e7434951",
	"due_at": "2017-03-28T23:00:00.000Z",
	"show_inactive": true,
	"name": "Main Outlet - 29 Mar 2017 12:00 PM",
	"status": "STOCKTAKE_IN_PROGRESS",
	"filters": [{
		"type": "product",
		"value": "060f02b1-c810-11e6-fcd2-732ffb8bfc9f"
	}, {
		"type": "tag",
		"value": "060f02b1-c810-11e6-fcd2-c1a9d3b4c0aa"
	}],
	"type": "STOCKTAKE"
}

Getting the inventory count

A GET to the /api/2.0/consignments/:id endpoint will return the current status of the inventory count. e.g.

{
    "data": {
        "id": "7dbe52cd-0ae4-11e4-a0f5-b8ca3a64f8f4",
        "outlet_id": "b1e04bd8-f019-11e3-a0f5-b8ca3a64f8f4",
        "name": "Order - Mon 14 Jul 2014",
        "due_at": null,
        "type": "SUPPLIER",
        "status": "RECEIVED",
        "supplier_id": null,
        "source_outlet_id": null,
        "consignment_date": "2014-07-13T23:22:00+00:00",
        "received_at": "2015-07-30T02:59:51+00:00",
        "show_inactive": true,
        "supplier_invoice": "",
        "reference": null,
        "total_count_gain": null,
        "total_cost_gain": null,
        "total_count_loss": null,
        "total_cost_loss": null,
        "created_at": "2014-07-13T23:22:00+00:00",
        "updated_at": "2015-07-30T02:59:51+00:00",
        "deleted_at": null,
        "version": 827406,
        "filters": []
    }
}

Getting products for the inventory count

A GET to the /api/2.0/consignments/:id/products endpoint will return a collection of products associated with the specified inventory count. e.g.

{
    "data": [
      {
        "product_id": "fa16cdf8-063c-11e4-a0f5-b8ca3a64f8f4",
        "product_sku": null,
        "count": "10.00000",
        "received": "10.00000",
        "cost": "0.00000",
        "is_included": false,
        "status": "RECEIVE_SUCCESS",
        "created_at": "2015-02-23T18:46:12+00:00",
        "updated_at": "2015-07-30T02:59:51+00:00",
        "deleted_at": null,
        "version": 3542970
      }
    ]
}

Updating the inventory count

The inventory count can be updated by sending a PUT request to the /api/2.0/consignments/:id endpoint with the consignment object in the payload.

NOTE: Changing filters is done by overwriting, not patching. The endpoint expects a full consignment object.

Counting products

The product count for all items is updated by sending one or more POST requests for every product to the /api/2.0/consignments/:id/products endpoint with the following payload:

{
	"product_id": "060f02b1-c810-11e6-fcd2-732ffb8bfc9f",
	"received": "2.00000"
}

NOTE: Multiple requests will add the count value, not replace it. This enables counting the same product by multiple client apps/devices.

Deleting the inventory count

It is possible to delete an inventory count by making a DELETE request to the /api/2.0/consignments/:id endpoint.

Cancelling the inventory count

It is possible to abandon (cancel) an inventory count. It can be done by sending a PUT to the /api/2.0/consignments/:id endpoint with a payload including "status": "CANCELLED".

Removing an item from the count

It is possible to delete products from the count by sending a DELETE to the /api/2.0/api/2.0/consignments/:id/products/:product_id endpoint.