Inventory

With the API, you can retrieve and manage a brand's inventory. This section describes how inventory is stored and outlines popular use cases.

For a full overview of inventory fields please visit the API Reference.

Inventory Fields

The inventory level is defined on the product object. There are three inventory fields on the product object.

  1. quantity: Inventory level
  2. reserved_qty: Inventory reserved by orders in the Submitted or Accepted states
  3. available_inventory: Inventory available for new orders (quantity - reserved_qty)

The inventory fields automatically update when particular order events occur on the platform. The following events impact the inventory.

Order EventInventory Effect
New order submittedThe quantity in the order is added to reserved_qty. The quantity remains here while the order is in the Submitted or Accepted state.
Submitted or Accepted order rejectedThe quantity in the order is deducted from reserved_qty.
Order fulfilledThe quantity in the order is deducted from reserved_qty and quantity.
Fulfilled or Shipped order rejectedThe quantity in the order is added back to quantity.

Set inventory

To set inventory for a new product, define the inventory level with the quantity field in your POST request to the /products/ endpoint.

/**
POST /api/v2/products/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
*/

{
    "quantity": 2000,
    ...
}

Note: The above code example is for illustrating the inventory related field only. The ... is used in place of the additional fields that would be present in a full product POST request.

Alternatively, you can update a newly created product and define either the quantity field or the available_inventory field in a PATCH request to /products/{id}/.

/**
PATCH /api/v2/products/303113/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
*/

{
    "quantity": 2000
}

Or

/**
PATCH /api/v2/products/303113/
Host: sandbox.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
*/

{
    "available_inventory": 2000
}

All three requests result in the same inventory level because there is no reserved quantity.

quantity: 2000,
reserved_qty: 0,
available_inventory: 2000

Update inventory

To update inventory for an existing product with reserved quantities, define the inventory level with either the quantity or the available_inventory field in a PATCH request to /products/{id}/.

Assume that we have open orders reserving 490 units of the product that we wish to update. The current inventory is as follows.

quantity: 2000,
reserved_qty: 490,
available_inventory: 1510

Option 1: quantity

Update the inventory level to list 2190 total units.

PATCH /api/v2/products/303113/
Host: leaflink-integrations.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
{
    "quantity": 2190
}

LeafLink will calculate the available_inventory field based on this value. The resulting inventory is as follows.

quantity: 2190,
reserved_qty: 490,
available_inventory: 1700

Option 2: available_inventory

Update the inventory level to list 1700 available units.

PATCH /api/v2/products/303113/
Host: leaflink-integrations.leaflink.com
Authorization: App 54901b614b81d25084edc7b1f2016571b96778910d7b8b0befgf8decd418d6ab
Content-Type: application/json
{
    "available_inventory": 1700
}

LeafLink will calculate the quantity field based on this value. The resulting inventory is as follows.

quantity: 2190,
reserved_qty: 490,
available_inventory: 1700

We recommend using one of the following procedures to keep inventory accurate between the external system and LeafLink:

  1. Export orders from LeafLink starting at the Fulfilled status and consider inventory reserved immediately in external system. Sync inventory using the quantity field to LeafLink.
  2. Export orders from LeafLink starting at the Submitted status and consider inventory reserved immediately in external system. Sync inventory using the available_inventory field to LeafLink.
  3. Export orders from LeafLink starting at the Submitted status and don't consider inventory reserved in external system until the Fulfilled status. Sync inventory using the quantity field to LeafLink.

Integration Tip

If a product's inventory has been adjusted in an integrated external system, update the inventory in LeafLink.

Last Updated: