Skip to content

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

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Location name
codestringno-Unique identifier code
descriptiontextyesnullLocation description
emailstringno-Location contact email (unique)
street_addressstringno-Street address
street_address_plusstringyesnullAdditional address line
postal_codestringno-Postal/ZIP code
citystringno-City
statestringyesnullState/province/region
phone_numberstringyesnullPhone number
priorityintegerno0Allocation order at checkout, lower values first
latitudedecimal(11,5)yesnullGPS latitude
longitudedecimal(10,5)yesnullGPS longitude
is_defaultbooleannofalseDefault location for stock
country_idbigintyesnullFK to countries table, set to null when the country is deleted
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

Relationships

Country

Each location belongs to a country:

$location->country; // Country model

Inventory 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 records

Query 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 (contract Shopper\Core\Contracts\InventoryResolver) returns every location ordered by priority, lowest first, then by ID. It ignores is_default.
  • Shopper\Core\Stock\PriorityStockAllocator (contract Shopper\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 (contract Shopper\Core\Contracts\StockReserver) records one decreaseStock() 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 with InsufficientStockException. For a product with allow_backorder enabled, 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 setting

Location-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