How to Manage Stock Locations
In this document, you’ll learn how to manage stock locations using the admin APIs.
Overview
Using the stock locations admin REST APIs, you can manage stock locations in your store, including creating, updating, and deleting locations.
Scenario
You want to add or use the following admin functionalities:
- List stock locations.
- Create a stock location.
- Retrieve a stock location.
- Associate a stock location with a sales channel, and remove the association.
- Update a stock location.
- Delete a stock location.
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 a stock location module installed. You can use Medusa’s Stock Location module or create your own module.
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 Stock Locations
You can list stock locations by using the List Stock Locations API Route:
import { useAdminStockLocations } from "medusa-react"
function StockLocations() {
const {
stock_locations,
isLoading
} = useAdminStockLocations()
return (
<div>
{isLoading && <span>Loading...</span>}
{stock_locations && !stock_locations.length && (
<span>No Locations</span>
)}
{stock_locations && stock_locations.length > 0 && (
<ul>
{stock_locations.map(
(location) => (
<li key={location.id}>{location.name}</li>
)
)}
</ul>
)}
</div>
)
}
export default StockLocations
This API Route doesn't require any path or query parameters. You can, however, pass it query parameters to search or filter the list of stock locations. For example, you can pass the q
query parameter to search through the locations by name. You can learn about available query parameters in the API reference.
The request returns an array of stock location objects along with pagination parameters.
Create a Stock Location
You can create a stock location using the Create a Stock Location API Route:
import { useAdminCreateStockLocation } from "medusa-react"
const CreateStockLocation = () => {
const createStockLocation = useAdminCreateStockLocation()
// ...
const handleCreate = (name: string) => {
createStockLocation.mutate({
name,
}, {
onSuccess: ({ stock_location }) => {
console.log(stock_location.id)
}
})
}
// ...
}
export default CreateStockLocation
This API Route requires in its body parameters the name
field, which is the name of the stock location. You can also pass in the request body parameters other fields related to the address or metadata. You can learn more in the API reference.
This request returns the created stock location as an object.
Retrieve a Stock Location
You can retrieve a stock location by sending a request to the Get Stock Location API Route:
import { useAdminStockLocation } from "medusa-react"
type Props = {
stockLocationId: string
}
const StockLocation = ({ stockLocationId }: Props) => {
const {
stock_location,
isLoading
} = useAdminStockLocation(stockLocationId)
return (
<div>
{isLoading && <span>Loading...</span>}
{stock_location && (
<span>{stock_location.name}</span>
)}
</div>
)
}
export default StockLocation
This API Route requires the stock location ID to be passed as a path parameter. It also accepts query parameters related to expanding and selecting fields. You can learn more in the API reference.
It returns the stock location as an object.
Associate a Stock Location with a Sales Channel
You can associate a stock location with a sales channel by sending a request to the Associate Stock Channel API Route:
import {
useAdminAddLocationToSalesChannel
} from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const addLocation = useAdminAddLocationToSalesChannel()
// ...
const handleAddLocation = (locationId: string) => {
addLocation.mutate({
sales_channel_id: salesChannelId,
location_id: locationId
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.locations)
}
})
}
// ...
}
export default SalesChannel
fetch(`<BACKEND_URL>/admin/sales-channels/${salesChannelId}/stock-locations`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
location_id,
}),
})
.then((response) => response.json())
.then(({ sales_channel }) => {
console.log(sales_channel.id)
})
This API Route requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re associating the sales channel with.
This request returns the sales channel object.
You can associate a location with more than one sales channel, and you can associate a sales channel with more than one location.
Remove Association Between Stock Location and Sales Channel
You can remove the association between a stock location and a sales channel by sending a request to the Remove Stock Location Association API Route:
import {
useAdminRemoveLocationFromSalesChannel
} from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const removeLocation = useAdminRemoveLocationFromSalesChannel()
// ...
const handleRemoveLocation = (locationId: string) => {
removeLocation.mutate({
sales_channel_id: salesChannelId,
location_id: locationId
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.locations)
}
})
}
// ...
}
export default SalesChannel
fetch(`<BACKEND_URL>/admin/sales-channels/${salesChannelId}/stock-locations`, {
credentials: "include",
method: "DELETE",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
location_id,
}),
})
.then((response) => response.json())
.then(({ id, object, deleted }) => {
console.log(id)
})
This API Route requires the ID of the sales channel as a path parameter. In its body parameters, it requires the ID of the stock location you’re removing the association of the sales channel with.
The request returns the following fields:
id
: The ID of the location.object
: The type of object that was removed. In this case, the value will bestock-location
.deleted
: A boolean value indicating whether the association with the stock location was removed.
This request does not delete the stock location. It only removes the association between it and the specified sales channel.
Update a Stock Location
You can update a stock location by sending a request to the Update Stock Location API Route:
import { useAdminUpdateStockLocation } from "medusa-react"
type Props = {
stockLocationId: string
}
const StockLocation = ({ stockLocationId }: Props) => {
const updateLocation = useAdminUpdateStockLocation(
stockLocationId
)
// ...
const handleUpdate = (
name: string
) => {
updateLocation.mutate({
name
}, {
onSuccess: ({ stock_location }) => {
console.log(stock_location.name)
}
})
}
}
export default StockLocation
fetch(`<BACKEND_URL>/admin/stock-locations/${stockLocationId}`,
{
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Warehouse",
}),
}
)
.then((response) => response.json())
.then(({ stock_location }) => {
console.log(stock_location.id)
})
This API Route requires the ID of a stock location as a path parameter. In its body parameters, you can pass any of the location’s attributes to update, such as the name or address. You can learn more in the API reference.
This request returns the updated stock location as an object.
Delete a Stock Location
You can delete a stock location by sending a request to the Delete Stock Location API Route:
import { useAdminDeleteStockLocation } from "medusa-react"
type Props = {
stockLocationId: string
}
const StockLocation = ({ stockLocationId }: Props) => {
const deleteLocation = useAdminDeleteStockLocation(
stockLocationId
)
// ...
const handleDelete = () => {
deleteLocation.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
}
export default StockLocation
This API Route requires the ID of the stock location as a path parameter.
It returns the following fields in the response:
id
: The ID of the location.object
: The type of object that was deleted. In this case, the value will bestock_location
.deleted
: A boolean value indicating whether the stock location was deleted successfully.