Locations
Manage inventory locations, warehouses, and fulfillment origins for multi-location stock tracking.
Locations represent physical places where you store inventory and ship orders from: warehouses, retail stores, fulfillment centers, or even your apartment. Each location has its own address and can track stock independently, so a product can have 50 units in your Paris warehouse and 20 in your New York store.
When Shopper is first installed, the setup wizard creates a default location using your store's address. The initial quantity you enter when creating a product or variant in the admin is recorded at this location. If your business ships from multiple places, you can add more locations and assign stock to each one.
Model
The model used is Shopper\Core\Models\Inventory. It implements Shopper\Core\Models\Contracts\Inventory and is configurable via config/shopper/models.php.
Extending the Model
To add custom behavior, extend the model and update your configuration:
namespace App\Models;
use Shopper\Core\Models\Inventory as BaseInventory;
class Inventory extends BaseInventory
{
}Update config/shopper/models.php:
return [
'inventory' => \App\Models\Inventory::class,
];Database Schema
| Column | Type | Nullable | Default | Description |
|---|---|---|---|---|
id | bigint | no | auto | Primary key |
name | string | no | - | Location name |
code | string | no | - | Unique identifier code |
description | text | yes | null | Location description |
email | string | no | - | Location contact email (unique) |
street_address | string | no | - | Street address |
street_address_plus | string | yes | null | Additional address line |
postal_code | string | no | - | Postal/ZIP code |
city | string | no | - | City |
state | string | yes | null | State/province/region |
phone_number | string | yes | null | Phone number |
priority | integer | no | 0 | Allocation order at checkout, lower values first |
latitude | decimal(11,5) | yes | null | GPS latitude |
longitude | decimal(10,5) | yes | null | GPS longitude |
is_default | boolean | no | false | Default location for stock |
country_id | bigint | yes | null | FK to countries table, set to null when the country is deleted |
created_at | timestamp | yes | null | Creation timestamp |
updated_at | timestamp | yes | null | Last update timestamp |
Relationships
Country
Each location belongs to a country:
$location->country; // Country modelInventory Histories
Every stock mutation (increase, decrease, set) on any product or variant creates an InventoryHistory record tied to a specific location. This is how Shopper tracks stock per location.
$location->histories; // Collection of InventoryHistory recordsQuery Scopes
The default scope returns the location marked as the default inventory. The admin action Shopper\Actions\Store\InitialQuantityInventory uses it to record the initial quantity entered when creating a product or variant. With no default location, that initial quantity is not recorded.
use Shopper\Core\Models\Inventory;
$defaultLocation = Inventory::query()->default()->first();How Locations Connect to Stock
When you call mutateStock(), decreaseStock(), or setStock() on a product or variant, you pass an $inventoryId. This ties the stock mutation to a specific location:
$product->mutateStock(
inventoryId: $warehouse->id,
quantity: 100,
event: 'Shipment received',
);setStock() works differently: it computes its delta from the total stock across all locations, then records that delta at the given location, as described in Modifying Stock.
To get stock for a product at a specific location:
$product->stockInventory($warehouse->id);To batch-load stock for a specific location across multiple products (avoiding N+1):
use Shopper\Models\Product;
$products = Product::query()->get();
Product::loadStockForInventory($products, $warehouse->id);After this call, $product->stock returns the stock at that location, not the total.
At checkout, Shopper reserves the stock of each line that tracks inventory, as described in Stock Reservation. Three services, bound in Shopper\Core\CoreServiceProvider, decide which locations the stock comes from:
Shopper\Core\Stock\DefaultInventoryResolver(contractShopper\Core\Contracts\InventoryResolver) returns every location ordered bypriority, lowest first, then by ID. It ignoresis_default.Shopper\Core\Stock\PriorityStockAllocator(contractShopper\Core\Contracts\StockAllocator) takes the whole quantity from the first location that holds it. When no single location does, it splits the quantity across locations in the same order.Shopper\Core\Stock\LockingStockReserver(contractShopper\Core\Contracts\StockReserver) records onedecreaseStock()movement per location, with the order as reference. When the locations together hold less than the quantity, it records nothing and the order is refused withInsufficientStockException. For a product withallow_backorderenabled, it takes the whole quantity from the first location returned by the resolver, whose stock goes negative.
To change which locations an order draws from, or in which order, write your own resolver. This one tries the default location first, then the others by priority:
namespace App\Stock;
use Illuminate\Database\Eloquent\Collection;
use Shopper\Core\Contracts\InventoryResolver;
use Shopper\Core\Models\Contracts\Stockable;
use Shopper\Core\Models\Inventory;
final class DefaultFirstInventoryResolver implements InventoryResolver
{
public function resolve(Stockable $product): Collection
{
return Inventory::query()
->orderByDesc('is_default')
->orderBy('priority')
->orderBy('id')
->get();
}
}Bind it in the register method of one of your service providers. The allocator and the reserver receive the resolver from the container, so they use yours:
use App\Stock\DefaultFirstInventoryResolver;
use Shopper\Core\Contracts\InventoryResolver;
$this->app->bind(InventoryResolver::class, DefaultFirstInventoryResolver::class);Creating Locations
To create a new warehouse location:
use Shopper\Core\Models\Inventory;
use Shopper\Core\Models\Country;
$france = Country::query()->where('cca2', 'FR')->first();
$warehouse = Inventory::query()->create([
'name' => 'Paris Warehouse',
'code' => 'WH-PARIS',
'email' => 'paris@mystore.com',
'street_address' => '15 Rue du Commerce',
'city' => 'Paris',
'postal_code' => '75015',
'country_id' => $france->id,
'priority' => 1,
'latitude' => 48.8466,
'longitude' => 2.2958,
]);Retrieving Locations
To get the default location:
$default = Inventory::query()->default()->first();To get all locations ordered by priority:
$locations = Inventory::query()
->with('country')
->orderBy('priority')
->get();To find the nearest location to a customer (if latitude/longitude are set). This straight-line distance on coordinates is an approximation, enough to rank nearby locations:
$locations = Inventory::query()
->whereNotNull('latitude')
->whereNotNull('longitude')
->get()
->sortBy(function ($location) use ($customerLat, $customerLng) {
return sqrt(
pow($location->latitude - $customerLat, 2)
+ pow($location->longitude - $customerLng, 2)
);
});
$nearest = $locations->first();Default Location
The default location receives the initial quantity entered when you create a product or variant in the admin. It is not a fallback for stock operations: mutateStock(), decreaseStock() and setStock() always need an $inventoryId, and checkout allocation follows priority, not is_default.
Only one location can be the default. When you create or update a location with is_default set to true, Shopper sets is_default to false on every other location. The admin does not show a delete button on the default location.
Shopper does not take a shipping origin from your locations. When you request carrier rates, you build the from address yourself, and a location's address is the usual source, as shown in Checkout Shipping Selection.
Deleting a location removes all inventory history records tied to it. This affects stock levels for every product that had stock in that location. Proceed with caution.
Components
To customize the admin UI for location management:
php artisan shopper:component:publish settingLocation-related components in config/shopper/components/setting.php:
use Shopper\Livewire;
return [
'pages' => [
'location-index' => Livewire\Pages\Settings\Locations\Index::class,
'location-create' => Livewire\Pages\Settings\Locations\Create::class,
'location-edit' => Livewire\Pages\Settings\Locations\Edit::class,
],
'components' => [
'settings.locations.form' => Livewire\Components\Settings\Locations\InventoryForm::class,
],
];Last updated on
Edit on GitHub