medusa-store/www/docs/content/modules/multiwarehouse/admin/manage-inventory-items.mdx

---
description: 'Learn how to manage inventory items using the admin APIs. This includes how to manage inventory items and inventory levels.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# How to Manage Inventory Items

In this document, you’ll learn how to manage inventory items using the admin APIs.

## Overview

Using the inventory items admin REST APIs, you can manage inventory items and inventory levels in your store.

### Scenario

You want to add or use the following admin functionalities:

- Manage inventory items. This includes listing, creating, updating, and deleting items.
- Manage inventory levels. This includes creating, updating, and deleting inventory levels.

---

## Prerequisites

### Medusa Components

It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.

### Required Module

This guide assumes you have the Inventory module installed on your Medusa backend. If not, you can learn how to install it using [this guide](../install-modules.md#inventory-module).

Furthermore, inventory levels are tied to a location ID. So, it’s recommended to use the [Stock Location module](../install-modules.md#stock-location-module) if you don’t have any location logic implemented in place.

### JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration).

### Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).

### Authenticated Admin User

You must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).

---

## List Inventory Items

You can list inventory items by sending a request to the [List Inventory Items endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.list()
.then(({ inventory_items }) => {
  console.log(inventory_items.length)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminInventoryItems } from "medusa-react"

function InventoryItems() {
  const { 
    inventory_items,
    isLoading } = useAdminInventoryItems()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {inventory_items && !inventory_items.length && (
        <span>No Items</span>
      )}
      {inventory_items && inventory_items.length > 0 && (
        <ul>
          {inventory_items.map(
            (item) => (
              <li key={item.id}>{item.id}</li>
            )
          )}
        </ul>
      )}
    </div>
  )
}

export default InventoryItems
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/admin/inventory-items`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ inventory_items }) => {
  console.log(inventory_items.length)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X GET '<BACKEND_URL>/admin/inventory-items' \
		 -H 'Authorization: Bearer <API_TOKEN>'
```

</TabItem>
</Tabs>

This endpoint does not require any path or query parameters. You can, however, pass path parameters to search or filter inventory items. For example, you can get inventory items in a specific location by passing the `location_id` query parameter. You can learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitems).

This request returns an array of inventory item objects.

---

## Create an Inventory Item

:::tip

Inventory items are automatically created when a variant is created with `manage_inventory` set to `true` or updated to enable the `manage_inventory` attribute. So, in general cases, you don’t need to create an inventory item manually.

:::

You can create an inventory item by sending a request to the [Create Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.create({
  variant_id,
})
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminCreateInventoryItem } from "medusa-react"

const CreateInventoryItem = () => {
  const createInventoryItem = useAdminCreateInventoryItem()
  // ...

  const handleCreate = () => {
    createInventoryItem.mutate({
      variant_id,
    })
  }

  // ...
}

export default CreateInventoryItem
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/admin/inventory-items`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    variant_id,
  }),
})
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X POST '<BACKEND_URL>/admin/inventory-items' \
		 -H 'Authorization: Bearer <API_TOKEN>' \
		 -H 'Content-Type: application/json' \
		 --data-raw '{
           "variant_id": "variant_123"
     }'
```

</TabItem>
</Tabs>

This endpoint requires in the body parameter the `variant_id` parameter, which is the ID of the variant to create this inventory item for. You can also pass other inventory-related parameters, such as `sku`. You can learn more about other available parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitems).

This request returns the created inventory item as an object.

---

## Retrieve Inventory Item

You can retrieve an inventory item by sending a request to the [Get Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitem):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.retrieve(inventoryItemId)
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminInventoryItem } from "medusa-react"

function InventoryItem() {
  const { 
    inventory_item,
    isLoading } = useAdminInventoryItem(inventoryItemId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {inventory_item && (
        <span>{inventory_item.sku}</span>
      )}
    </div>
  )
}

export default InventoryItem
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}`, 
  {
    credentials: "include",
  }
)
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
		 -H 'Authorization: Bearer <API_TOKEN>'
```

</TabItem>
</Tabs>

This endpoint accepts the ID of the inventory item as a path parameter. You can also path query parameters such as [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields).

The request returns the inventory item as an object.

---

## Update Inventory Item

You can update an inventory item by sending a request to the [Update Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.update(inventoryItemId, {
  origin_country: "US",
})
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminUpdateInventoryItem } from "medusa-react"

const UpdateInventoryItem = () => {
  const updateInventoryItem = useAdminUpdateInventoryItem(
    inventoryItemId
  )
  // ...

  const handleUpdate = () => {
    updateInventoryItem.mutate({
      origin_country: "US",
    })
  }

  // ...
}

export default UpdateInventoryItem
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}`,
  {
    credentials: "include",
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      origin_country: "US",
    }),
  }
)
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
		 -H 'Authorization: Bearer <API_TOKEN>' \
		 -H 'Content-Type: application/json' \
		 --data-raw '{
           "origin_country": "US"
     }'
```

</TabItem>
</Tabs>

This endpoint requires the inventory item’s ID as a path parameter. You can pass any of the inventory item’s attributes that you want to update in its body parameter. The example above updates the value of the `origin_country` attribute. You can learn more about available body parameters in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitem).

The request returns the updated inventory item as an object.

---

## Manage Inventory levels

This section shows you the different ways you can manage inventory levels. Each location level is associated with an inventory item.

### List inventory levels

You can list inventory levels of an inventory item by sending a request to the [List inventory levels endpoint](https://docs.medusajs.com/api/admin#inventory-items_getinventoryitemsinventoryitemlocationlevels):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.listLocationLevels(inventoryItemId)
.then(({ inventory_item }) => {
  console.log(inventory_item.location_levels)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { 
  useAdminInventoryItemLocationLevels,
} from "medusa-react"

function InventoryItem() {
  const { 
    inventory_item,
    isLoading, 
  } = useAdminInventoryItemLocationLevels(inventoryItemId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {inventory_item && (
        <ul>
          {inventory_item.location_levels.map((level) => (
            <span key={level.id}>{level.stocked_quantity}</span>
          ))}
        </ul>
      )}
    </div>
  )
}

export default InventoryItem
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

<!-- eslint-disable max-len -->

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}/location-levels`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.location_levels)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels' \
		 -H 'Authorization: Bearer <API_TOKEN>'
```

</TabItem>
</Tabs>

This endpoint requires the ID of the inventory item as a path parameter. You can also pass [expand](https://docs.medusajs.com/api/admin#expanding-fields) and [fields](https://docs.medusajs.com/api/admin#selecting-fields) query parameters.

The request returns the inventory item as an object. In that object, the list of inventory levels are available under the property `location_levels`.

### Create Inventory Level

You can create a location level by sending a request to the [Create Inventory Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevels):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.createLocationLevel(
  inventoryItemId, 
  {
    location_id,
    stocked_quantity: 10,
  }
)
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminCreateLocationLevel } from "medusa-react"

const CreateLocationLevel = () => {
  const createLocationLevel = useAdminCreateLocationLevel(
    inventoryItemId
  )
  // ...

  const handleCreate = () => {
    createLocationLevel.mutate({
      location_id,
      stocked_quantity: 10,
    })
  }

  // ...
}

export default CreateLocationLevel
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

<!-- eslint-disable max-len -->

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}/location-levels`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    location_id,
    stocked_quantity: 10,
  }),
})
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels' \
		 -H 'Authorization: Bearer <API_TOKEN>' \
		 -H 'Content-Type: application/json' \
		 --data-raw '{
           "location_id": "<LOCATION_ID>",
           "stocked_quantity": 10
     }'
```

</TabItem>
</Tabs>

This endpoint requires the inventory item ID as a path parameter. In the request body, it requires the following parameters:

- `location_id`: The ID of the location associated with this location level. This ID is typically available through using the stock location module.
- `stocked_quantity`: A number indicating the item’s quantity in stock.

You can also pass other optional request body parameters, as explained in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevels).

This request returns the inventory item associated with the created location level.

### Update Location Level

You can update a location level by sending a request to the [Update Location Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevelslocationlevel):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.updateLocationLevel(
  inventoryItemId, 
  locationId,
  {
    stocked_quantity: 15,
  }
)
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminUpdateLocationLevel } from "medusa-react"

const UpdateLocationLevel = () => {
  const updateLocationLevel = useAdminUpdateLocationLevel(
    inventoryItemId
  )
  // ...

  const handleUpdate = () => {
    updateLocationLevel.mutate({
      stockLocationId,
      stocked_quantity: 10,
    })
  }

  // ...
}

export default UpdateLocationLevel
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

<!-- eslint-disable max-len -->

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}/location-levels/${locationId}`, {
  credentials: "include",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    stocked_quantity: 10,
  }),
})
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels/<LOCATION_ID>' \
		 -H 'Authorization: Bearer <API_TOKEN>' \
		 -H 'Content-Type: application/json' \
		 --data-raw '{
           "stocked_quantity": 10
     }'
```

</TabItem>
</Tabs>

This endpoint requires two path parameters: the first one being the ID of the inventory item, and the second one being the ID of the location.

In the body, you can optionally pass any of the location level’s attributes to update. In the example above, you update the `stocked_quantity` attribute of the location level.

The request returns the inventory item associated with the location level as an object.

### Delete Location Level

You can delete a location level of an inventory item by sending a request to the [Delete Location Level endpoint](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitelocationlevelslocation):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.deleteLocationLevel(
  inventoryItemId, 
  locationId
)
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminDeleteLocationLevel } from "medusa-react"

const DeleteLocationLevel = () => {
  const deleteLocationLevel = useAdminDeleteLocationLevel(
    inventoryItemId
  )
  // ...

  const handleDelete = () => {
    deleteLocationLevel.mutate(locationId)
  }

  // ...
}

export default DeleteLocationLevel
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

<!-- eslint-disable max-len -->

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}/location-levels/${locationId}`, {
  credentials: "include",
  method: "DELETE",
})
.then((response) => response.json())
.then(({ inventory_item }) => {
  console.log(inventory_item.id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels/<LOC_ID>' \
		 -H 'Authorization: Bearer <API_TOKEN>'
```

</TabItem>
</Tabs>

This endpoint requires two path parameters: the first one being the inventory item’s ID and the second one being the location level’s ID.

The request returns the inventory item as an object.

---

## Delete Inventory Item

You can delete an inventory item by sending a request to the [Delete Inventory Item endpoint](https://docs.medusajs.com/api/admin#inventory-items_deleteinventoryitemsinventoryitem):

<Tabs groupId="request-type" isCodeTabs={true}>
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.admin.inventoryItems.delete(inventoryItemId)
.then(({ id, object, deleted }) => {
  console.log(id)
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useAdminDeleteInventoryItem } from "medusa-react"

const DeleteInventoryItem = () => {
  const deleteInventoryItem = useAdminDeleteInventoryItem(
    inventoryItemId
  )
  // ...

  const handleDelete = () => {
    deleteInventoryItem.mutate()
  }

  // ...
}

export default DeleteInventoryItem
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/admin/inventory-items/${inventoryItemId}`,
  {
    credentials: "include",
    method: "DELETE",
  }
)
.then((response) => response.json())
.then(({ id, object, deleted }) => {
  console.log(id)
})
```

</TabItem>
<TabItem value="curl" label="cURL">

```bash
curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
		 -H 'Authorization: Bearer <API_TOKEN>'
```

</TabItem>
</Tabs>

This endpoint requires the inventory item’s ID be passed as a path parameter.

It returns the following fields in the response:

- `id`: The ID of the inventory item.
- `object`: The type of object that was deleted. In this case, the value will be `inventory_item`.
- `deleted`: A boolean value indicating whether the inventory item was deleted successfully.

---

## See Also

- [How to manage stock locations](./manage-stock-locations.mdx)
- [How to manage item allocations in orders](./manage-item-allocations-in-orders.mdx)