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:
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
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
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:
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
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:
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
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:
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)
})
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:
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
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:
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)
})
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:
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)
})
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:
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
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:
import { useAdminDeleteInventoryItem } from "medusa-react"
type Props = {
inventoryItemId: string
}
const InventoryItem = ({ inventoryItemId }: Props) => {
const deleteInventoryItem = useAdminDeleteInventoryItem(
inventoryItemId
)
// ...
const handleDelete = () => {
deleteInventoryItem.mutate()
}
// ...
}
export default InventoryItem
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 beinventory_item
.deleted
: A boolean value indicating whether the inventory item was deleted successfully.