medusa-store/www/apps/docs/content/modules/multiwarehouse/admin/manage-stock-locations.mdx

---
description: 'Learn how to manage stock locations using the admin APIs. This includes how to list, create, update, and delete stock locations.'
addHowToData: true
---

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

# 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](../../../development/backend/install.mdx) to get started.

### Required Module

This guide assumes you have a stock location module installed. You can use Medusa’s [Stock Location module](../install-modules.md#stock-location-module) or [create your own module](../backend/create-stock-location-service.md).

### 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.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#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 Stock Locations

You can list stock locations by using the [List Stock Locations API Route](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations):

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

    ```ts
    medusa.admin.stockLocations.list()
    .then(({ stock_locations, limit, offset, count }) => {
      console.log(stock_locations.length)
    })
    ```

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

    ```tsx
    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
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/stock-locations`, {
      credentials: "include",
    })
    .then((response) => response.json())
    .then(({ stock_locations, limit, offset, count }) => {
      console.log(stock_locations.length)
    })
    ```

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

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/stock-locations' \
        -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#stock-locations_getstocklocations).

The request returns an array of stock location objects along with [pagination parameters](https://docs.medusajs.com/api/admin#pagination).

---

## Create a Stock Location

You can create a stock location using the [Create a Stock Location API Route](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations):

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

    ```ts
    medusa.admin.stockLocations.create({
      name: "Main Warehouse",
    })
    .then(({ stock_location }) => {
      console.log(stock_location.id)
    })
    ```

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

    ```tsx
    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
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/stock-locations`, {
      credentials: "include",
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "Main Warehouse",
      }),
    })
    .then((response) => response.json())
    .then(({ stock_location }) => {
      console.log(stock_location.id)
    })
    ```

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

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/stock-locations' \
        -H 'x-medusa-access-token: <API_TOKEN>' \
        -H 'Content-Type: application/json' \
        --data-raw '{
            "name": "Main Warehouse"
        }'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#stock-locations_poststocklocations).

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](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation):

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

    ```ts
    medusa.admin.stockLocations.retrieve(stockLocationId)
    .then(({ stock_location }) => {
      console.log(stock_location.id)
    })
    ```

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

    ```tsx
    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
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/stock-locations/${stockLocationId}`,
      {
        credentials: "include",
      }
    )
    .then((response) => response.json())
    .then(({ stock_location }) => {
      console.log(stock_location.id)
    })
    ```

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

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/stock-locations/<LOC_ID>' \
        -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#stock-locations_getstocklocationsstocklocation).

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](https://docs.medusajs.com/api/admin#sales-channels_postsaleschannelssaleschannelstocklocation):

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

    ```ts
    medusa.admin.salesChannels.addLocation(salesChannelId, {
      location_id,
    })
    .then(({ sales_channel }) => {
      console.log(sales_channel.id)
    })
    ```

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

    ```tsx
    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
    ```

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

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

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

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

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/sales-channels/<CHANNEL_ID>/stock-locations' \
        -H 'x-medusa-access-token: <API_TOKEN>' \
        -H 'Content-Type: application/json' \
        --data-raw '{
            "location_id": "<LOC_ID>"
        }'
    ```

  </TabItem>
</Tabs>

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.

:::note

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](https://docs.medusajs.com/api/admin#sales-channels_deletesaleschannelssaleschannelstocklocation):

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

    ```ts
    medusa.admin.salesChannels.removeLocation(salesChannelId, {
      location_id,
    })
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

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

    ```tsx
    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
    ```

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

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

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

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

    ```bash
    curl -L -X DELETE '<BACKEND_URL>/admin/sales-channels/<CHANNEL_ID>/stock-locations' \
        -H 'x-medusa-access-token: <API_TOKEN>' \
        -H 'Content-Type: application/json' \
        --data-raw '{
            "location_id": "<LOC_ID>"
        }'
    ```

  </TabItem>
</Tabs>

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 be `stock-location`.
- `deleted`: A boolean value indicating whether the association with the stock location was removed.

:::note

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](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation):

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

    ```ts
    medusa.admin.stockLocations.update(stockLocationId, {
      name: "Warehouse",
    })
    .then(({ stock_location }) => {
      console.log(stock_location.id)
    })
    ```

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

    ```tsx
    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
    ```

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

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

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

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/stock-locations/<LOC_ID>' \
        -H 'x-medusa-access-token: <API_TOKEN>' \
        -H 'Content-Type: application/json' \
        --data-raw '{
            "name": "Main Warehouse"
        }'
    ```

  </TabItem>
</Tabs>

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](https://docs.medusajs.com/api/admin#stock-locations_poststocklocationsstocklocation).

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](https://docs.medusajs.com/api/admin#stock-locations_deletestocklocationsstocklocation):

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

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

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

    ```tsx
    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
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/stock-locations/${stockLocationId}`,
      {
        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/stock-locations/<LOC_ID>' \
        -H 'x-medusa-access-token: <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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 be `stock_location`.
- `deleted`: A boolean value indicating whether the stock location was deleted successfully.

---

## See Also

- [How to manage inventory items](./manage-inventory-items.mdx)
- [How to manage item allocations in orders](./manage-item-allocations-in-orders.mdx)