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 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.

Furthermore, inventory levels are tied to a location ID. So, it’s recommended to use the 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 installed and have created an instance of the client.

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 and have used MedusaProvider higher in your component tree.

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.

---

List Inventory Items

You can list inventory items by sending a request to the List Inventory Items API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X GET '<BACKEND_URL>/admin/inventory-items' \
    -H 'x-medusa-access-token: <API_TOKEN>'

This API Route doesn't 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminCreateInventoryItem } from "medusa-react"

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

  const handleCreate = (variantId: string) => {
    createInventoryItem.mutate({
      variant_id: variantId,
    }, {
      onSuccess: ({ inventory_item }) => {
        console.log(inventory_item.id)
      }
    })
  }

  // ...
}

export default CreateInventoryItem

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)
})

curl -L -X POST '<BACKEND_URL>/admin/inventory-items' \
    -H 'x-medusa-access-token: <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
          "variant_id": "variant_123"
    }'

This API Route 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminInventoryItem } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const { 
    inventory_item,
    isLoading
  } = useAdminInventoryItem(inventoryItemId)

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

export default InventoryItem

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

curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
    -H 'x-medusa-access-token: <API_TOKEN>'

This API Route accepts the ID of the inventory item as a path parameter. You can also path query parameters such as expand and 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminUpdateInventoryItem } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const updateInventoryItem = useAdminUpdateInventoryItem(
    inventoryItemId
  )
  // ...

  const handleUpdate = (origin_country: string) => {
    updateInventoryItem.mutate({
      origin_country,
    }, {
      onSuccess: ({ inventory_item }) => {
        console.log(inventory_item.origin_country)
      }
    })
  }

  // ...
}

export default InventoryItem

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)
})

curl -L -X POST '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
    -H 'x-medusa-access-token: <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
          "origin_country": "US"
    }'

This API Route 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { 
  useAdminInventoryItemLocationLevels,
} from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  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

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

curl -L -X GET '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels' \
    -H 'x-medusa-access-token: <API_TOKEN>'

This API Route requires the ID of the inventory item as a path parameter. You can also pass expand and 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminCreateLocationLevel } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const createLocationLevel = useAdminCreateLocationLevel(
    inventoryItemId
  )
  // ...

  const handleCreateLocationLevel = (
    locationId: string,
    stockedQuantity: number
  ) => {
    createLocationLevel.mutate({
      location_id: locationId,
      stocked_quantity: stockedQuantity,
    }, {
      onSuccess: ({ inventory_item }) => {
        console.log(inventory_item.id)
      }
    })
  }

  // ...
}

export default InventoryItem

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)
})

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

This API Route 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.

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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminUpdateLocationLevel } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const updateLocationLevel = useAdminUpdateLocationLevel(
    inventoryItemId
  )
  // ...

  const handleUpdate = (
    stockLocationId: string,
    stockedQuantity: number
  ) => {
    updateLocationLevel.mutate({
      stockLocationId,
      stocked_quantity: stockedQuantity,
    }, {
      onSuccess: ({ inventory_item }) => {
        console.log(inventory_item.id)
      }
    })
  }

  // ...
}

export default InventoryItem

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)
})

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

This API Route 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminDeleteLocationLevel } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const deleteLocationLevel = useAdminDeleteLocationLevel(
    inventoryItemId
  )
  // ...

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

  // ...
}

export default InventoryItem

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)
})

curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>/location-levels/<LOC_ID>' \
    -H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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 API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

import { useAdminDeleteInventoryItem } from "medusa-react"

type Props = {
  inventoryItemId: string
}

const InventoryItem = ({ inventoryItemId }: Props) => {
  const deleteInventoryItem = useAdminDeleteInventoryItem(
    inventoryItemId
  )
  // ...

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

  // ...
}

export default InventoryItem

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

curl -L -X DELETE '<BACKEND_URL>/admin/inventory-items/<ITEM_ID>' \
    -H 'x-medusa-access-token: <API_TOKEN>'

This API Route 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
• How to manage item allocations in orders