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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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

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

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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

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"
    }'

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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

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

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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>"
    }'

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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>"
    }'

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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"
    }'

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:

Medusa JS Client
Medusa React
Fetch API
cURL

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

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

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

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

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.

Overview​

Scenario​

Prerequisites​

Medusa Components​

Required Module​

JS Client​

Medusa React​

Authenticated Admin User​

List Stock Locations​

Create a Stock Location​

Retrieve a Stock Location​

Associate a Stock Location with a Sales Channel​

Remove Association Between Stock Location and Sales Channel​

Update a Stock Location​

Delete a Stock Location​

See Also​