Inventory

Inventory Item Model

Properties

  • Name
    id
    Type
    string
    Restrictions
    Description

    The unique identifier for the inventory item.

  • Name
    product
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the product that corresponds to this inventory item.

    This is a 1-many mapping; each product variant has an inventory item, hence the number of inventory items for a given product ID is equal to the number of variants attached to said product.

  • Name
    » variant
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the product variant that corresponds to this inventory item.

    This is a 1-1 mapping; each variant has an inventory item.

  • Name
    is_tracked
    Type
    boolean
    Restrictions
    Description

    Whether the stock levels are tracked for this inventory item.

  • Name
    aggregate_levels
    Type
    [InventoryLevel](#schemainventorylevel)
    Restrictions
    Description

    The aggregate quantities of inventory across all locations for an organisation.

  • Name
    created_at
    Type
    string(date-time)
    Description

    The time at which the inventory item was created.

  • Name
    updated_at
    Type
    string(date-time)
    Description

    The time at which the inventory item was last updated.

{
  "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
  "product": {
    "id": "prod_29ZaWHhqqGk00xyZI6SFPc8iON7",
    "variant": {
      "id": "vrnt_29ZbJ5B59rFaz6e9knFDIAUQJ9l"
    }
  },
  "is_tracked": true,
  "aggregate_levels": {
    "reserved_quantity": 4,
    "available_quantity": 5,
    "on_hand_quantity": 10,
    "shipped_quantity": 0,
    "safety_quantity": 1
  },
  "created_at": "2023-02-28T20:00:42.815574Z",
  "updated_at": "2023-02-28T20:00:42.815574Z"
}

Inventory Level Model

Properties

  • Name
    location
    Type
    [InventoryLocation](#schemainventorylocation)
    Restrictions
    Description

    The location field is only present for quantities attached to a location.

    For aggregate levels, this field will not be present.

  • Name
    reserved_quantity
    Type
    integer
    Restrictions
    Description

    The quantity of goods that is reserved for orders present in the system.

  • Name
    available_quantity
    Type
    integer
    Restrictions
    Description

    The available quantity of goods at the location.

    This is calculated as:

    available_quantity = on_hand_quantity - reserved_quantity - safety_quantity

  • Name
    on_hand_quantity
    Type
    integer
    Restrictions
    Description

    The quantity of goods present at the location.

  • Name
    shipped_quantity
    Type
    integer
    Restrictions
    Description

    The quantity of goods that has been marked as shipped but has not yet been confirmed as delivered.

  • Name
    safety_quantity
    Type
    integer
    Restrictions
    Description

    A minimum quantiy of goods that one aims to have present at the location at any given time.

    This does not affect the behaviour of the system in any way - the user is warned of the low inventory level, but orders utilising the inventory will continue to process.

{
  "location": {
    "id": "loc_2LHcXCpprGKeTCgcgjtxWOUgBgB"
  },
  "reserved_quantity": 4,
  "available_quantity": 5,
  "on_hand_quantity": 10,
  "shipped_quantity": 3,
  "safety_quantity": 1
}

Inventory Event Model

Properties

  • Name
    location
    Type
    [InventoryLocation](#schemainventorylocation)
    Restrictions
    Description

    The location field is only present for quantities attached to a location.

    For aggregate levels, this field will not be present.

  • Name
    delta
    Type
    integer
    Restrictions
    Description

    The change in quantity for the inventory item.

    This integer will be positive or negative depending on whether the inventory has increased or decreased respectively.

  • Name
    description
    Type
    string
    Restrictions
    Description

    A short description for the reason the event occurred.

  • Name
    user
    Type
    object
    Restrictions
    Description
  • Name
    » id
    Type
    string
    Restrictions
    Description

    The ID of the user that changed the inventory level.

  • Name
    created_at
    Type
    string(date-time)
    Restrictions
    Description

    The time when the event was created.

  • Name
    updated_at
    Type
    string(date-time)
    Restrictions
    Description

    The time at which the event was last updated.

{
  "location": {
    "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
  },
  "delta": 6,
  "description": "Stock count 14/02/23",
  "user": {
    "id": "usr_28AJYd9g2Bguxl7cMHDToYU2hgf"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Inventory Location Model

Properties

  • Name
    Inventory Location
    Type
    object,null
    Restrictions
    Description

    The location field is only present for quantities attached to a location.

    For aggregate levels, this field will not be present.

  • Name
    id
    Type
    string
    Restrictions
    Description

    The ID for the location that this inventory level belongs to.

{
  "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
}
GET/inventory

Get Inventory Items

Retrieves inventory items associated with an organisation.

Inventory items are the representation of the physical stock that is held for a product. Inventory items are automatically created for product variants when the latter is initially created. Inventory levels are then created by the user to represent to stock held at a given location.

The results can be filtered to return items for a set of product variant IDs. This is achieved by passing one or more product variant ID(s) as query parameters, for example:

/inventory?product_variant_id=vrnt_...JQKkGW&product_variant_id=vrnt_...P10S3

As with other resources, this endpoint returns paginated results. The details of how pagination works can be found in the pagination article.

Query Parameters

  • Name
    product_variant_id
    Type
    array
    Restrictions
    Description

    One or more product variant IDs to return inventory items for.

  • Name
    next_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the next set of results.

  • Name
    previous_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the previous set of results.

  • Name
    limit
    Type
    string
    Restrictions
    Description

    The maximum number of results returned in the set.

Request

GET
/inventory
curl --request GET \
--url https://api.envoy.one/inventory \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
      "product": {
        "id": "prod_29ZaWHhqqGk00xyZI6SFPc8iON7",
        "variant": {
          "id": "vrnt_29ZbJ5B59rFaz6e9knFDIAUQJ9l"
        }
      },
      "is_tracked": true,
      "aggregate_levels": {
        "reserved_quantity": 4,
        "available_quantity": 5,
        "on_hand_quantity": 10,
        "shipped_quantity": 0,
        "safety_quantity": 1
      },
      "created_at": "2023-02-28T20:00:42.815574Z",
      "updated_at": "2023-02-28T20:00:42.815574Z"
    }
  ],
  "next_cursor": "WyIyMDIzLTAzLTIxVDAwOjM1OjU5LjczMDYyMVoiXQ==",
  "previous_cursor": "WyIyMDIzLTAzLTE5VDA0OjI4OjAxLjQ4NDg5WiJd",
  "limit": 20
}

undefined

POST/inventory

Create Inventory Item

Creates a new inventory item for a given product/variant combination.

This typically happens automatically, at the point where the product variant is created. In the event that the item needs to be manually created, the product and variant IDs will be validated, and a new item created.

Due to the need to check product information as part of the creation process, a scope that grants access to the products resource on at least a read only basis is required to use this endpoint (eg. products:read).

Request

POST
/inventory
curl --request POST \
--url https://api.envoy.one/inventory \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"product":{"id":"prod_29ZaSRuU445ChdFCEDrSWZIeczD","is_tracked":"true","variant":{"id":"vrnt_29Zb72NVZLcwDd9Y3w5qy23ZJoE"}}}'

Response

{
  "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
  "product": {
    "id": "prod_29ZaWHhqqGk00xyZI6SFPc8iON7",
    "variant": {
      "id": "vrnt_29ZbJ5B59rFaz6e9knFDIAUQJ9l"
    }
  },
  "is_tracked": true,
  "aggregate_levels": {
    "reserved_quantity": 4,
    "available_quantity": 5,
    "on_hand_quantity": 10,
    "shipped_quantity": 0,
    "safety_quantity": 1
  },
  "created_at": "2023-02-28T20:00:42.815574Z",
  "updated_at": "2023-02-28T20:00:42.815574Z"
}

undefined

POST/inventory/query

Query Inventory Items

This endpoint is used to query multiple inventory items by quantity & optionally distance from a set of specified coordinates.

The response is an array of inventory items and locations that have at least the specified quantity of the given item, and are geographically closest to the specified coordinates if specified in the request.

The order_by parameter is used to order the location results is 2 possible ways:

  • distance - Requires the coordinates parameter to be specified, in which case the location results are ordered by distance from the specified coordinates.
  • available_quantity - Orders location results where the location with the highest level of the specified inventory item is the top result.

If no order_by parameter is specified, the default is to use distance if the coordinates parameter is specified, otherwise available_quantity is used.

locations_limit defaults to 5, and indicates the maximum number of location results that will be returned for each line item in the request.

Detailed descriptions

»» confidence: A confidence score associated with the cordinates, indicating how accurately they represent the address.

For manually set coordinates, set the confidence score to 1 to indicate that the location has been manually specified/verified.

Enumerated Values

ParameterValue
» order_bydistance
» order_byavailable_quantity

Request

POST
/inventory/query
curl --request POST \
--url https://api.envoy.one/inventory/query \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"order_by":["distance"],"locations_limit":5,"coordinates":{"latitude":51.7864239,"longitude":-0.9725901,"confidence":0.9201},"line_items":[{"id":"inv_2MNP5DWpneqTA8wQ5x9Jocrt4le","quantity":3}]}'

Response

{
  "data": [
    {
      "id": "inv_2MNP5DWpneqTA8wQ5x9Jocrt4le",
      "locations": [
        {
          "location": {
            "id": "loc_2LHcXCpprGKeTCgcgjtxWOUgBgB"
          },
          "reserved_quantity": 4,
          "available_quantity": 5,
          "on_hand_quantity": 10,
          "shipped_quantity": 3,
          "safety_quantity": 1
        }
      ]
    }
  ]
}

undefined

GET/inventory/{inventory_item_id}

Get Inventory Item

Retrieve an individual inventory item by it's ID.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

Request

GET
/inventory/{inventory_item_id}
curl --request GET \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
  "product": {
    "id": "prod_29ZaWHhqqGk00xyZI6SFPc8iON7",
    "variant": {
      "id": "vrnt_29ZbJ5B59rFaz6e9knFDIAUQJ9l"
    }
  },
  "is_tracked": true,
  "aggregate_levels": {
    "reserved_quantity": 4,
    "available_quantity": 5,
    "on_hand_quantity": 10,
    "shipped_quantity": 0,
    "safety_quantity": 1
  },
  "created_at": "2023-02-28T20:00:42.815574Z",
  "updated_at": "2023-02-28T20:00:42.815574Z"
}

undefined

PATCH/inventory/{inventory_item_id}

Update Inventory Item

Update the details for an inventory item.

Currently the only field that can be updated on an inventory item is the is_tracked parameter. This parameter determines whether the item has trackable inventory (ie. a finite quantity), or if the item should not have it's inventory tracked, either due to quantity not being applicable to the item (eg. a service package), or for other business reasons.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

Request

PATCH
/inventory/{inventory_item_id}
curl --request PATCH \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"is_tracked":true}'

Response

{
  "id": "inv_2MNiSi4jiDJMglxrFf0akgGFdj6",
  "product": {
    "id": "prod_29ZaWHhqqGk00xyZI6SFPc8iON7",
    "variant": {
      "id": "vrnt_29ZbJ5B59rFaz6e9knFDIAUQJ9l"
    }
  },
  "is_tracked": true,
  "aggregate_levels": {
    "reserved_quantity": 4,
    "available_quantity": 5,
    "on_hand_quantity": 10,
    "shipped_quantity": 0,
    "safety_quantity": 1
  },
  "created_at": "2023-02-28T20:00:42.815574Z",
  "updated_at": "2023-02-28T20:00:42.815574Z"
}

undefined

DELETE/inventory/{inventory_item_id}

Delete Inventory Item

Manually delete an inventory item.

This endpoint is restricted, as typically an inventory item is automatically deleted when a product is deleted. Manual deletion is not recommended owing to the possible loss of data around inventory levels, and subsequent unexpected behaviour resulting from products not having inventory items.

This endpoint requires both the inventory:admin scope, and also the restricted inventory:DeleteInventoryItems ability to be used.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

Request

DELETE
/inventory/{inventory_item_id}
curl --request DELETE \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined

GET/inventory/{inventory_item_id}/levels

Get Inventory Item Levels

Retrieve the aggregate levels for a given inventory item.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

Query Parameters

  • Name
    next_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the next set of results.

  • Name
    previous_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the previous set of results.

  • Name
    limit
    Type
    string
    Restrictions
    Description

    The maximum number of results returned in the set.

Request

GET
/inventory/{inventory_item_id}/levels
curl --request GET \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6/levels \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "location": {
        "id": "loc_2NDVMYM9Q5itESKOIAfJvx2FH8r"
      },
      "reserved_quantity": 0,
      "available_quantity": 38,
      "on_hand_quantity": 41,
      "shipped_quantity": 0,
      "safety_quantity": 3
    },
    {
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "reserved_quantity": 0,
      "available_quantity": 29,
      "on_hand_quantity": 32,
      "shipped_quantity": 0,
      "safety_quantity": 3
    }
  ],
  "next_cursor": "WyIyMDIzLTAzLTIxVDAwOjM1OjU5LjczMDYyMVoiXQ==",
  "previous_cursor": "WyIyMDIzLTAzLTE5VDA0OjI4OjAxLjQ4NDg5WiJd",
  "limit": 20
}

undefined

GET/inventory/{inventory_item_id}/locations/{location_id}/events

Get Inventory Item Events

Retrieve the inventory update events for a given inventory item at a given location.

Events are a read-only audit log of inventory level changes for a given location. Events do not currently track level changes due to fulfilments - they track activity outside of the normal fulfilment process, such as restocking or corrections during inventory checks.

A description can be provided at the point the inventory is updated if desired, which will be returned alongside the corresponding event.

Where an inventory level change has been carried out manually by a user, the user ID responsible for the change is also logged.

The most recent events are returned first.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Query Parameters

  • Name
    next_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the next set of results.

  • Name
    previous_cursor
    Type
    string
    Restrictions
    Description

    A pagination pointer supplied in a previous request for the previous set of results.

  • Name
    limit
    Type
    string
    Restrictions
    Description

    The maximum number of results returned in the set.

Request

GET
/inventory/{inventory_item_id}/locations/{location_id}/events
curl --request GET \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma/events \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "data": [
    {
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "delta": 3,
      "description": "added old stock from storage 14/03/23",
      "user": {
        "id": "usr_28AJYd9g2Bguxl7cMHDToYU2hgf"
      },
      "created_at": "2023-03-21T00:35:59.730621Z",
      "updated_at": "2023-03-21T00:35:59.730621Z"
    },
    {
      "location": {
        "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
      },
      "delta": 32,
      "description": "added new stock",
      "user": {
        "id": "usr_28AJYd9g2Bguxl7cMHDToYU2hgf"
      },
      "created_at": "2023-03-19T04:28:01.48489Z",
      "updated_at": "2023-03-19T04:28:01.48489Z"
    }
  ],
  "next_cursor": "WyJsb2NfMk5EVk1ZTTlRNWl0RVNLT0lBZkp2eDJGSDhyIiwiMjAyMy0wMy0xOVQwNDowMzoxMS44NzYxMjFaIl0=",
  "previous_cursor": "WyJsb2NfMk44bk1qZTZHT3RqYzdjZTlBamtRSG1rR0owIiwiMjAyMy0wMy0xN1QxMjowMjoxMC4zNDk4M1oiXQ==",
  "limit": 20
}

undefined

GET/inventory/{inventory_item_id}/locations/{location_id}/levels

Get Item Levels for Location

Retrieve the levels for a given item at the specified location.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

GET
/inventory/{inventory_item_id}/locations/{location_id}/levels
curl --request GET \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma/levels \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

Response

{
  "location": {
    "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
  },
  "reserved_quantity": 0,
  "available_quantity": 32,
  "on_hand_quantity": 35,
  "shipped_quantity": 0,
  "safety_quantity": 3
}

undefined

PATCH/inventory/{inventory_item_id}/locations/{location_id}/levels

Manage Item Level for Location

Modify the item inventory level at a given location.

The quantities supplies are absolute, and overwrite the previous value.

Any actions carried out via this endpoint are logged as an event. The user can optionally provide a description for the change in level, which may be useful to provide context at a later date in case the event log is reviewed to identify the source of a discrepancy.

Requests that result the inventory levels remaining the same will not store an event.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

PATCH
/inventory/{inventory_item_id}/locations/{location_id}/levels
curl --request PATCH \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma/levels \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data '{"on_hand_quantity":20,"safety_quantity":2,"description":"stock take 14/03/23"}'

Response

{
  "location": {
    "id": "loc_2N8nMje6GOtjc7ce9AjkQHmkGJ0"
  },
  "reserved_quantity": 0,
  "available_quantity": 32,
  "on_hand_quantity": 35,
  "shipped_quantity": 0,
  "safety_quantity": 3
}

undefined

DELETE/inventory/{inventory_item_id}/locations/{location_id}/levels

Delete Item Level for Location

Deletes any inventory levels associated with a given item at the specified location.

Path Parameters

  • Name
    inventory_item_id
    Type
    string
    Restrictions
    Description

    The ID for an inventory item.

  • Name
    location_id
    Type
    string
    Restrictions
    Description

    The unique ID for a location.

Request

DELETE
/inventory/{inventory_item_id}/locations/{location_id}/levels
curl --request DELETE \
--url https://api.envoy.one/inventory/inv_2MNiSi4jiDJMglxrFf0akgGFdj6/locations/loc_2KmdpbdotbekAsGL50uAfSxe4Ma/levels \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {access-token}'

undefined