From v2.5 to v2.6

Estimated Upgrade Time: 15 to 45 minutes depending on how much you customized auth models and event listeners.

Updating Dependencies

You should update the following dependencies in your application’s composer.json file: shopper/framework to ^2.6 shopper/stripe to ^2.6 (If installed) Then run:

composer update -W

After updating, run the migrations:

php artisan migrate

v2.6 ships one new package: shopper/cart. The tax system is built into shopper/core. Both are included in shopper/framework and installed automatically. Their migrations run with the standard php artisan migrate command.

High Impact Changes

Auth Models and Traits Moved from Core to Admin

Likelihood of Impact: High Affects applications that import Role, Permission, ShopperUser, or HasProfilePhoto directly. The Role and Permission models, the ShopperUser and HasProfilePhoto traits, and the spatie/laravel-permission dependency have all moved from shopper/core to shopper/admin. If you import any of these directly in your application code, update the namespaces:

Before (v2.5)	After (v2.6)
`Shopper\Core\Models\Role`	`Shopper\Models\Role`
`Shopper\Core\Models\Permission`	`Shopper\Models\Permission`
`Shopper\Core\Models\Contracts\ShopperUser`	`Shopper\Models\Contracts\ShopperUser`
`Shopper\Core\Traits\ShopperUser`	`Shopper\Traits\InteractsWithShopper`
`Shopper\Core\Models\Traits\HasProfilePhoto`	`Shopper\Traits\HasProfilePhoto`

The old namespaces are still present in shopper/core as deprecated aliases and will continue to work until v3.0, but you should migrate at your earliest convenience. The role configuration has also moved. If you referenced the admin role from config/shopper/core.php, update to config/shopper/admin.php:

Before (v2.5)

config('shopper.core.roles.admin')

After (v2.6)

config('shopper.admin.roles.admin')

Medium Impact Changes

New Migrations

v2.6 adds 15 new migrations across two packages. Run php artisan migrate after updating. Tax system (shopper/core):

Migration	Description
`2026_02_24_000001_create_tax_providers_table`	Tax provider registry
`2026_02_24_000002_create_tax_zones_table`	Geographic tax zones
`2026_02_24_000003_create_tax_rates_table`	Rates and override rules
`2026_02_25_000001_add_tax_amount_to_orders_table`	`tax_amount` column on orders
`2026_02_25_000002_add_tax_columns_to_order_items_table`	`tax_amount` and `tax_rate_id` on order items
`2026_02_25_000003_create_order_tax_lines_table`	Tax line snapshots
`2026_02_25_000004_add_allow_backorder_to_products_table`	`allow_backorder` column on products
`2026_02_25_000005_make_user_id_nullable_on_inventory_histories_table`	`user_id` becomes nullable

Cart package (shopper/cart):

Migration	Description
`2026_03_01_000001_create_carts_table`	Cart model
`2026_03_01_000002_create_cart_lines_table`	Cart line items
`2026_03_01_000003_create_cart_addresses_table`	Billing and shipping addresses
`2026_03_01_000004_create_cart_line_adjustments_table`	Discount adjustments per line
`2026_03_01_000005_create_cart_line_tax_lines_table`	Tax lines per cart line

Performance (shopper/admin):

Migration	Description
`2026_02_26_000001_add_status_indexes_to_orders_table`	Indexes on order status columns

Order and Product Event Renaming

Likelihood of Impact: Medium Affects applications with listeners registered for OrderCancel or AddNoteToOrder events. Two events have been renamed for consistency. If you registered listeners for either of these events, update your EventServiceProvider:

Before (v2.5)	After (v2.6)
`Shopper\Core\Events\Orders\OrderCancel`	`Shopper\Core\Events\Orders\OrderCancelled`
`Shopper\Core\Events\Orders\AddNoteToOrder`	`Shopper\Core\Events\Orders\OrderNoteAdded`

Before (v2.5)

use Shopper\Core\Events\Orders\OrderCancel;
use Shopper\Core\Events\Orders\AddNoteToOrder;

protected $listen = [
    OrderCancel::class => [CancelOrderHandler::class],
    AddNoteToOrder::class => [NotifyTeam::class],
];

After (v2.6)

use Shopper\Core\Events\Orders\OrderCancelled;
use Shopper\Core\Events\Orders\OrderNoteAdded;

protected $listen = [
    OrderCancelled::class => [CancelOrderHandler::class],
    OrderNoteAdded::class => [NotifyTeam::class],
];

Render Hooks: Enum Replaced by Scoped Classes

Likelihood of Impact: Medium Affects applications that registered render hooks using the RenderHook enum in v2.5. The RenderHook enum (Shopper\Enum\RenderHook) from v2.5 had 6 layout-level hooks. It has been replaced by seven scoped classes organized by business domain. If you used any of these hooks, update to LayoutRenderHook:

Before (v2.5)	After (v2.6)
`RenderHook::HeadStart`	`LayoutRenderHook::HEAD_START`
`RenderHook::HeadEnd`	`LayoutRenderHook::HEAD_END`
`RenderHook::BodyStart`	`LayoutRenderHook::BODY_START`
`RenderHook::BodyEnd`	`LayoutRenderHook::BODY_END`
`RenderHook::ContentStart`	`LayoutRenderHook::CONTENT_START`
`RenderHook::ContentEnd`	`LayoutRenderHook::CONTENT_END`

The new classes are in the Shopper\View namespace. See the Render Hooks documentation for the complete list of available hooks across all 7 scoped classes.

Before (v2.5)

use Shopper\Enum\RenderHook;

Shopper::renderHook(RenderHook::HeadEnd, fn () => '...');

After (v2.6)

use Shopper\View\LayoutRenderHook;

Shopper::renderHook(LayoutRenderHook::HEAD_END, fn () => '...');

Low Impact Changes

`allow_backorder` Column Added to Products

A new boolean column allow_backorder has been added to the products table. It defaults to false. No action is required, the migration handles it automatically. When allow_backorder is true on a product or variant, the cart’s add() and update() methods skip the stock availability check entirely, allowing the item to be added regardless of inventory level.

`user_id` Nullable on Inventory Histories

The user_id foreign key on the inventory_histories table is now nullable. This accommodates stock changes triggered by automated processes rather than an admin action. No action is required.

System Permissions Cleanup

Three system permissions have been removed from the seeder and are no longer created on fresh installations:

Removed permission	Reason
`manage_mail`	No longer used by any component
`impersonate`	No longer used by any component
`setting_analytics`	No longer used by any component

For existing installations these permissions remain in your database but have no effect. You can delete them manually if you want to keep your permissions table clean:

use Shopper\Models\Permission;

Permission::query()->whereIn('name', ['manage_mail', 'impersonate', 'setting_analytics'])->delete();

Server-Side Authorization Enforced Across Admin Components

Likelihood of Impact: Medium Affects applications with custom roles beyond the default administrator role. All admin Livewire pages and slide-overs now enforce permissions server-side via $this->authorize(). Previously, many components relied only on sidebar visibility to restrict access, so a direct URL or Livewire call was enough to bypass the check. The following table lists every area that is now protected and the permission required:

Area	Permission
Settings pages (General, Carriers, Payment Methods, Taxes, Tax Zones, Legal)	`access_setting`
Tax rate overrides slide-over	`access_setting`
Shipping zone and rate slide-overs	`access_setting`
Team management pages and slide-overs	`view_users`
Product attributes slide-over	`edit_attributes`
Product pricing slide-over	`edit_products`
Choose product attributes slide-over	`edit_products`
Related products slide-over	`edit_products`
Generate variants slide-over	`edit_product_variants`
Update variant slide-over	`edit_product_variants`
Collection products and rules slide-overs	`edit_collections`
Re-order categories slide-over	`edit_categories`
Create shipping label slide-over	`edit_orders`
Reviews index page and detail slide-over	`browse_reviews`
Tags index page	`browse_tags`

The administrator role is not affected as it holds all permissions by default. For custom roles, assign the relevant permissions before upgrading:

use Spatie\Permission\Models\Role;

$role = Role::findByName('manager');

$role->givePermissionTo([
    'access_setting',
    'view_users',
    'edit_attributes',
    'edit_products',
    'edit_product_variants',
    'edit_collections',
    'edit_categories',
    'edit_orders',
    'browse_reviews',
    'browse_tags',
]);

Review all custom roles in your installation and assign the permissions appropriate to their scope before upgrading. Users with insufficient permissions will receive a 403 response.

Shopper Enums Now Implement `Shopper\Core\Contracts`

Shopper’s internal enums (OrderStatus, ProductType, etc.) now implement HasLabel, HasIcon, HasColor, and HasDescription from Shopper\Core\Contracts instead of Filament\Support\Contracts. This removes the Filament dependency from shopper/core and keeps the core package framework-agnostic. This has no impact on your application. Since Shopper runs on top of Filament, your own custom enums can continue to implement either Filament\Support\Contracts or Shopper\Core\Contracts. The method signatures are identical.

New Features

Cart Package

shopper/cart is now bundled with Shopper. It provides a full cart management system with pipeline-based calculation, discount validation, tax integration, and order conversion. See the Cart documentation for setup and usage.

Tax System

A built-in tax system is now available. Configure tax zones per country (or country + province), assign rates, and define override rules for specific products, product types, or categories. Taxes are calculated automatically in the cart pipeline. See the Taxes documentation for full details.

Dashboard Analytics

The dashboard now includes five new Livewire components: a 12-month revenue bar chart, stat cards with month-over-month trends, a recent orders table, a top-selling products table, and an interactive setup guide. All data is cached with stale-while-revalidate semantics. See the Dashboard documentation.

Abandoned Carts

A new admin page at Orders → Abandoned Carts lists carts that have been inactive for longer than the configured threshold (default: 60 minutes). The threshold is configurable in config/shopper/cart.php:

'abandoned_after_minutes' => 60,

Addon System

Shopper now has a first-class addon API for packaging extensions. An addon can register routes, Livewire components, sidebar entries, views, settings items, and permissions as a single unit. See the Addons documentation.

Render Hooks

62 named render hooks are now available across all admin pages. Use them to inject content into specific positions without modifying any Shopper views. See the Render Hooks documentation.

Migration Checklist

Update dependencies

Run composer update -W after updating shopper/framework to ^2.6.

Run migrations

Run php artisan migrate to apply all 15 new migrations.

Update auth model namespaces

Replace Shopper\Core\Models\Role → Shopper\Models\Role and Shopper\Core\Models\Permission → Shopper\Models\Permission wherever you import them.

Update auth trait namespaces

Replace Shopper\Core\Traits\ShopperUser → Shopper\Traits\InteractsWithShopper and Shopper\Core\Models\Traits\HasProfilePhoto → Shopper\Traits\HasProfilePhoto.

Update renamed events

Replace OrderCancel → OrderCancelled and AddNoteToOrder → OrderNoteAdded in your event listeners.

Update render hooks

Replace the old RenderHook enum constants with the new scoped class constants if you used render hooks in v2.5.

Update role config key

Replace config('shopper.core.users.admin_role') with config('shopper.admin.roles.admin') if you referenced it directly.

Review custom role permissions

Assign access_setting, view_users, edit_attributes, edit_products, edit_product_variants, edit_collections, edit_categories, edit_orders, browse_reviews, and browse_tags to any custom role that should access the corresponding areas. Optionally delete the unused manage_mail, impersonate, and setting_analytics permissions from your database.

Prologue

Getting Started

Catalog

Sales

Store Setup

System

Storefront

Releases

Updating Dependencies

High Impact Changes

Auth Models and Traits Moved from Core to Admin

Before (v2.5)

After (v2.6)

Medium Impact Changes

New Migrations

Order and Product Event Renaming

Before (v2.5)

After (v2.6)

Render Hooks: Enum Replaced by Scoped Classes

Before (v2.5)

After (v2.6)

Low Impact Changes

`allow_backorder` Column Added to Products

`user_id` Nullable on Inventory Histories

System Permissions Cleanup

Server-Side Authorization Enforced Across Admin Components

Shopper Enums Now Implement `Shopper\Core\Contracts`

New Features

Cart Package

Tax System

Dashboard Analytics

Abandoned Carts

Addon System

Render Hooks

Migration Checklist

​Updating Dependencies

​High Impact Changes

​Auth Models and Traits Moved from Core to Admin

​Before (v2.5)

​After (v2.6)

​Medium Impact Changes

​New Migrations

​Order and Product Event Renaming

​Before (v2.5)

​After (v2.6)

​Render Hooks: Enum Replaced by Scoped Classes

​Before (v2.5)

​After (v2.6)

​Low Impact Changes

​allow_backorder Column Added to Products

​user_id Nullable on Inventory Histories

​System Permissions Cleanup

​Server-Side Authorization Enforced Across Admin Components

​Shopper Enums Now Implement Shopper\Core\Contracts

​New Features

​Cart Package

​Tax System

​Dashboard Analytics

​Abandoned Carts

​Addon System

​Render Hooks

​Migration Checklist

Updating Dependencies

High Impact Changes

Auth Models and Traits Moved from Core to Admin

Before (v2.5)

After (v2.6)

Medium Impact Changes

New Migrations

Order and Product Event Renaming

Before (v2.5)

After (v2.6)

Render Hooks: Enum Replaced by Scoped Classes

Before (v2.5)

After (v2.6)

Low Impact Changes

`allow_backorder` Column Added to Products

`user_id` Nullable on Inventory Histories

System Permissions Cleanup

Server-Side Authorization Enforced Across Admin Components

Shopper Enums Now Implement `Shopper\Core\Contracts`

New Features

Cart Package

Tax System

Dashboard Analytics

Abandoned Carts

Addon System

Render Hooks

Migration Checklist