> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Stock Location Module

> Learn about the Stock Location Module and how to manage warehouse locations and addresses in Medusa.

## Overview

The Stock Location Module manages physical warehouse and store locations where inventory is stocked. It provides location management capabilities essential for multi-location inventory tracking and fulfillment.

**Key Features:**

* Multiple stock location management
* Location addresses with full details
* Location metadata for customization
* Integration with inventory tracking
* Integration with fulfillment

## When to Use

Use the Stock Location Module when you need to:

* Manage multiple warehouses or stores
* Track inventory at different locations
* Support multi-location fulfillment
* Store location addresses and contact info
* Implement ship-from-store functionality
* Handle distributed inventory
* Configure location-specific settings

## Data Models

### StockLocation

Represents a physical location where inventory is stored.

<ResponseField name="id" type="string" required>
  Unique stock location identifier (prefix: `sloc_`)
</ResponseField>

<ResponseField name="name" type="string" required>
  Location name (e.g., "Main Warehouse", "NYC Store")
</ResponseField>

<ResponseField name="address_id" type="string">
  ID of the associated address
</ResponseField>

<ResponseField name="address" type="StockLocationAddress">
  Full location address
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

### StockLocationAddress

Address details for a stock location.

<ResponseField name="id" type="string" required>
  Unique address identifier
</ResponseField>

<ResponseField name="address_1" type="string" required>
  Address line 1
</ResponseField>

<ResponseField name="address_2" type="string">
  Address line 2
</ResponseField>

<ResponseField name="city" type="string">
  City
</ResponseField>

<ResponseField name="country_code" type="string" required>
  Two-letter ISO country code
</ResponseField>

<ResponseField name="province" type="string">
  State or province
</ResponseField>

<ResponseField name="postal_code" type="string">
  Postal/ZIP code
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

## Service Interface

The Stock Location Module service is available at `@medusajs/medusa/stock-location`.

### Create Stock Location

Create a new stock location.

<CodeGroup>
  ```typescript Example theme={null}
  import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
  import { IStockLocationService } from "@medusajs/framework/types"
  import { Modules } from "@medusajs/framework/utils"

  export async function POST(
    req: MedusaRequest,
    res: MedusaResponse
  ) {
    const stockLocationService: IStockLocationService = req.scope.resolve(
      Modules.STOCK_LOCATION
    )

    const stockLocation = await stockLocationService.createStockLocations({
      name: "Main Warehouse",
      address: {
        address_1: "123 Warehouse Blvd",
        city: "San Francisco",
        country_code: "us",
        province: "CA",
        postal_code: "94102",
        phone: "+1-555-0100",
      },
    })

    res.json({ stock_location: stockLocation })
  }
  ```
</CodeGroup>

<ParamField path="data" type="CreateStockLocationDTO | CreateStockLocationDTO[]" required>
  Stock location data

  <ParamField path="name" type="string" required>
    Location name
  </ParamField>

  <ParamField path="address" type="CreateStockLocationAddressDTO">
    Location address
  </ParamField>

  <ParamField path="metadata" type="object">
    Custom metadata
  </ParamField>
</ParamField>

<ResponseField name="stockLocation" type="StockLocationDTO | StockLocationDTO[]">
  The created stock location(s)
</ResponseField>

### Retrieve Stock Location

Get a stock location with its address.

<CodeGroup>
  ```typescript Example theme={null}
  const stockLocation = await stockLocationService.retrieveStockLocation(
    "sloc_warehouse",
    {
      relations: ["address"],
    }
  )

  console.log(stockLocation.name) // "Main Warehouse"
  console.log(stockLocation.address.city) // "San Francisco"
  ```
</CodeGroup>

<ParamField path="stockLocationId" type="string" required>
  The ID of the stock location to retrieve
</ParamField>

<ParamField path="config" type="FindConfig">
  Configuration for the query

  <ParamField path="relations" type="string[]">
    Relations to load (e.g., `["address"]`)
  </ParamField>
</ParamField>

<ResponseField name="stockLocation" type="StockLocationDTO">
  The retrieved stock location
</ResponseField>

### List Stock Locations

List all stock locations.

<CodeGroup>
  ```typescript Example theme={null}
  const stockLocations = await stockLocationService.listStockLocations(
    {},
    {
      relations: ["address"],
    }
  )

  for (const location of stockLocations) {
    console.log(`${location.name} - ${location.address?.city}`)
  }
  ```
</CodeGroup>

<ParamField path="filters" type="FilterableStockLocationProps">
  Filters to apply

  <ParamField path="id" type="string | string[]">
    Filter by stock location IDs
  </ParamField>

  <ParamField path="name" type="string | string[]">
    Filter by name
  </ParamField>
</ParamField>

<ResponseField name="stockLocations" type="StockLocationDTO[]">
  Array of stock locations
</ResponseField>

### Update Stock Location

Modify a stock location.

<CodeGroup>
  ```typescript Example theme={null}
  const stockLocation = await stockLocationService.updateStockLocations(
    "sloc_warehouse",
    {
      name: "Main Distribution Center",
      address: {
        phone: "+1-555-0200",
      },
    }
  )
  ```
</CodeGroup>

<ParamField path="stockLocationId" type="string" required>
  ID of the stock location to update
</ParamField>

<ParamField path="data" type="UpdateStockLocationDTO" required>
  Fields to update

  <ParamField path="name" type="string">
    Location name
  </ParamField>

  <ParamField path="address" type="UpdateStockLocationAddressDTO">
    Address updates
  </ParamField>

  <ParamField path="metadata" type="object">
    Metadata updates
  </ParamField>
</ParamField>

### Delete Stock Location

Remove a stock location.

<CodeGroup>
  ```typescript Example theme={null}
  await stockLocationService.deleteStockLocations(["sloc_old"])
  ```
</CodeGroup>

## Integration Examples

### With Inventory Module

Manage inventory at stock locations.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const stockLocationModule = container.resolve(Modules.STOCK_LOCATION)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Create stock locations
  const warehouse = await stockLocationModule.createStockLocations({
    name: "Main Warehouse",
    address: {
      address_1: "123 Warehouse Blvd",
      city: "San Francisco",
      country_code: "us",
      postal_code: "94102",
    },
  })

  const store = await stockLocationModule.createStockLocations({
    name: "NYC Retail Store",
    address: {
      address_1: "456 5th Avenue",
      city: "New York",
      country_code: "us",
      postal_code: "10001",
    },
  })

  // Set inventory levels at each location
  await inventoryModule.createInventoryLevels([
    {
      inventory_item_id: "iitem_123",
      location_id: warehouse.id,
      stocked_quantity: 100,
    },
    {
      inventory_item_id: "iitem_123",
      location_id: store.id,
      stocked_quantity: 20,
    },
  ])

  // Check total available across locations
  const totalAvailable = await inventoryModule.retrieveAvailableQuantity(
    "iitem_123",
    [warehouse.id, store.id]
  )
  ```
</CodeGroup>

### With Fulfillment Module

Create fulfillments from stock locations.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const stockLocationModule = container.resolve(Modules.STOCK_LOCATION)
  const fulfillmentModule = container.resolve(Modules.FULFILLMENT)

  // Get nearest stock location
  const locations = await stockLocationModule.listStockLocations()
  const nearestLocation = locations[0] // Implement distance logic

  // Create fulfillment from location
  const fulfillment = await fulfillmentModule.createFulfillment({
    location_id: nearestLocation.id,
    provider_id: "manual",
    items: [
      { line_item_id: "item_123", quantity: 1 },
    ],
  })
  ```
</CodeGroup>

### With Order Module

Fulfill orders from specific locations.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const orderModule = container.resolve(Modules.ORDER)
  const stockLocationModule = container.resolve(Modules.STOCK_LOCATION)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Get order
  const order = await orderModule.retrieveOrder("order_123", {
    relations: ["items", "shipping_address"],
  })

  // Find locations with inventory
  const locations = await stockLocationModule.listStockLocations()

  for (const location of locations) {
    // Check if location has inventory for order items
    const hasInventory = await inventoryModule.confirmInventory(
      order.items[0].inventory_item_id,
      [location.id],
      order.items[0].quantity
    )
    
    if (hasInventory) {
      // Use this location for fulfillment
      console.log(`Fulfill from ${location.name}`)
      break
    }
  }
  ```
</CodeGroup>

## Common Scenarios

### Multi-Warehouse Setup

<CodeGroup>
  ```typescript Example theme={null}
  // West Coast Warehouse
  const westWarehouse = await stockLocationService.createStockLocations({
    name: "West Coast DC",
    address: {
      address_1: "100 Logistics Way",
      city: "Los Angeles",
      country_code: "us",
      province: "CA",
      postal_code: "90001",
    },
    metadata: {
      region: "west",
      capacity: 10000,
    },
  })

  // East Coast Warehouse
  const eastWarehouse = await stockLocationService.createStockLocations({
    name: "East Coast DC",
    address: {
      address_1: "200 Distribution Ave",
      city: "Atlanta",
      country_code: "us",
      province: "GA",
      postal_code: "30301",
    },
    metadata: {
      region: "east",
      capacity: 8000,
    },
  })
  ```
</CodeGroup>

### Retail Store Locations

<CodeGroup>
  ```typescript Example theme={null}
  // Flagship Store
  const flagship = await stockLocationService.createStockLocations({
    name: "Flagship Store - NYC",
    address: {
      address_1: "123 5th Avenue",
      city: "New York",
      country_code: "us",
      province: "NY",
      postal_code: "10001",
      phone: "+1-212-555-0100",
    },
    metadata: {
      type: "retail",
      store_hours: "9AM-9PM",
      ship_from_store: true,
    },
  })

  // Outlet Store
  const outlet = await stockLocationService.createStockLocations({
    name: "Outlet Store - Jersey",
    address: {
      address_1: "456 Mall Drive",
      city: "Jersey City",
      country_code: "us",
      province: "NJ",
      postal_code: "07302",
    },
    metadata: {
      type: "outlet",
      ship_from_store: false,
    },
  })
  ```
</CodeGroup>

### Drop Ship Locations

<CodeGroup>
  ```typescript Example theme={null}
  // Supplier location for drop shipping
  const supplier = await stockLocationService.createStockLocations({
    name: "Supplier A - Drop Ship",
    address: {
      address_1: "789 Supplier Road",
      city: "Chicago",
      country_code: "us",
      province: "IL",
      postal_code: "60601",
    },
    metadata: {
      type: "dropship",
      supplier_id: "SUP-001",
      lead_time_days: 7,
    },
  })
  ```
</CodeGroup>

## Best Practices

1. **Location Naming**: Use clear, descriptive names that include:
   * Location type (warehouse, store, supplier)
   * Geographic identifier (city, region)
   * Purpose if applicable (returns center, outlet)

2. **Complete Addresses**: Always provide complete address information including:
   * Full street address
   * City and province/state
   * Country code (two-letter ISO)
   * Postal code
   * Contact phone number

3. **Metadata Usage**: Store location-specific settings in metadata:
   * Operating hours
   * Capacity limits
   * Location type
   * Special handling instructions
   * Ship-from-store capability
   * Regional identifiers

4. **Location Strategy**: Plan your location structure based on:
   * Fulfillment speed requirements
   * Shipping cost optimization
   * Inventory distribution
   * Returns handling

5. **Integration**: Link stock locations with:
   * Inventory levels (required)
   * Fulfillment providers
   * Service zones
   * Return locations

6. **Soft Deletes**: Consider using metadata flags to "deactivate" locations instead of deleting them to preserve historical data.

## Related Modules

* [Inventory Module](/modules/inventory) - Track inventory at locations
* [Fulfillment Module](/modules/fulfillment) - Fulfill from locations
* [Order Module](/modules/order) - Location-based fulfillment