Skip to main content
Estimated Upgrade Time: 15-30 minutes for most applications.

Updating Dependencies

Update your composer.json file to require Shopper 2.5:
Then run:
After updating Composer dependencies, run the migrations:
The shopper/payment package is now a dependency of shopper/framework and is installed automatically. It provides the payment driver system, transaction tracking, and the PaymentProcessingService.For Stripe support, install the driver addon separately: composer require shopper/stripe. See the Stripe addon documentation for setup instructions.

High Impact Changes

Three-Status Order System

Likelihood of Impact: High The monolithic OrderStatus enum has been split into three independent enums, each tracking a different concern: The old OrderStatus values Pending, Registered, Paid, Shipped, Delivered, and Returned have been removed. You must update any code that references these values.

Before (v2.4)

After (v2.5)

The Order model now provides convenience methods for common status checks: isNew(), isProcessing(), isCompleted(), isArchived(), isPaid(), isPaymentAuthorized(), isRefunded(), isShipped(), isShippingPending().

Automatic Data Migration

The migration automatically maps your existing order statuses to the new three-status system. No manual data migration is needed.
If you have custom order status values beyond the ones listed above, they will not be migrated automatically. You must handle them manually before or after running php artisan migrate.

PaymentMethod & Carrier Logo Handling

Likelihood of Impact: High The logo column has been removed from both the payment_methods and carriers tables. Logos are now managed through Spatie Media Library. A new driver column has been added to both tables.

Before (v2.4)

After (v2.5)

Both models now implement Spatie\MediaLibrary\HasMedia and use the HasMedia trait.
If you stored logos using the old logo column, you need to manually re-upload them through the admin panel or migrate the files to the media library programmatically. The old column data is removed by the migration.

Payment System

Likelihood of Impact: High Shopper 2.5 introduces a complete payment driver system through the new shopper/payment package, which is included as a dependency of shopper/framework. Key components:
  • PaymentProcessingService. Orchestrates payment operations (initiate, authorize, capture, refund, cancel) through drivers
  • PaymentTransaction model. Records every payment operation with driver, type, status, amount, and provider reference
  • PaymentDriver contract. Interface for implementing payment providers
  • PaymentManager. Resolves and manages payment drivers (a manual driver is included by default)
New enums in Shopper\Payment\Enum: The admin panel now includes a Capture payment button on the order detail page for orders with PaymentStatus::Authorized. For Stripe payments, install the addon: composer require shopper/stripe. See the Payments documentation for the full API reference.

Medium Impact Changes

Order Contract Interface

Likelihood of Impact: Medium If you implement a custom Order model through the Shopper\Core\Models\Contracts\Order interface, you must add the following methods:
Use Shopper\Core\Models\Order as a reference implementation. The model sets default statuses automatically via setDefaultOrderStatus() in its booted() method.

Column Renamed: canceled_at to cancelled_at

Likelihood of Impact: Medium The canceled_at column on the orders table has been renamed to cancelled_at (double-L British spelling) for consistency.

Before (v2.4)

After (v2.5)

Update any code, queries, or Blade templates that reference the old column name.

OrderItem Fulfillment Tracking

Likelihood of Impact: Medium Two new columns have been added to the order_items table:
  • fulfillment_status. Tracks per-item fulfillment using the new FulfillmentStatus enum (Pending, ForwardedToSupplier, Processing, Shipped, Delivered, Cancelled)
  • order_shipping_id. Links each item to a specific shipment
This enables partial fulfillment: different items in the same order can be at different fulfillment stages and shipped in different packages. If you query or manipulate order items directly, be aware of these new columns. No action is required unless you have custom logic that conflicts.

Order Detail Page Decomposed into Components

Likelihood of Impact: Medium The order detail page has been restructured from a single monolithic page into independent, overridable Livewire components. Each section of the page is now its own component, registered in config/shopper/components/order.php. Components marked New were added in v2.5. Components marked Existing were already present but have been refactored. If you have published order components via php artisan shopper:component:publish order, update your config/shopper/components/order.php to include the new entries:
You can override any component by pointing the config key to your own class. For example, to customize how order items are displayed, create your own component extending Shopper\Livewire\Components\Orders\OrderItems and update the config entry.

OrderShipping: Status Column & Events

Likelihood of Impact: Medium The order_shipping table has a new status column (using the ShipmentStatus enum with 8 values) and the shipped_at column is now nullable. A new order_shipping_events table tracks the complete delivery timeline for each shipment. The OrderShipping model now uses the HasFulfillmentTransitions trait, which provides a state machine for valid status transitions:
See the Fulfillment documentation for the full transition map.

Low Impact Changes

New Events

Likelihood of Impact: Low Three new events have been added in Shopper\Core\Events\Orders: The SyncOrderShippingStatusListener automatically listens to OrderShipmentCreated and syncs the order’s shipping_status based on all items’ fulfillment states.

New Enums

Likelihood of Impact: Low Four new enums have been added to Shopper\Core\Enum: All follow the same pattern as existing enums: backed string enums implementing HasColor, HasIcon, and HasLabel.

Translation Keys

Likelihood of Impact: Low New translation keys have been added under shopper-core::status.* for the new enums. If you have published and customized the Shopper core translations, add the new keys from the packages/core/resources/lang/en/status.php file. The old OrderStatus translation keys for removed values (pending, registered, paid, shipped, delivered, returned) are no longer used.

New Features

Payment Driver System

The new shopper/payment package provides a driver-based payment architecture. Drivers handle payment operations while Shopper manages the order’s payment_status automatically. A manual driver is included for offline payments, and Stripe is available as an addon.

Capture Payment in Admin

Orders with PaymentStatus::Authorized now display a Capture payment button on the order detail page. Clicking it calls the payment driver’s capturePayment() method, records a transaction, and updates the payment status to Paid.

Shipment Tracking

Each shipment now tracks its delivery progress through a ShipmentStatus state machine with automatic event logging. The OrderShippingEvent model records status changes with timestamps, location data, and optional GPS coordinates.

Shipments Management

A new Shipments page in the admin panel provides a centralized view of all shipments with filtering by status, order, and carrier.

Migration Checklist

1

Update dependencies

Update shopper/framework to ^2.5 in composer.json, then run composer update -W.
2

Run migrations

Run php artisan migrate to apply all new migrations, including the three-status order system and the media library columns for payment methods and carriers.
3

Replace removed OrderStatus values

Replace all references to the removed OrderStatus values (Pending, Registered, Paid, Shipped, Delivered, Returned) with the equivalent PaymentStatus and ShippingStatus values.
4

Rename `canceled_at` to `cancelled_at`

Update any code, queries, or Blade templates that reference $order->canceled_at to use $order->cancelled_at.
5

Replace logo property with `logoUrl()`

Replace $paymentMethod->logo and $carrier->logo with $paymentMethod->logoUrl() and $carrier->logoUrl(). Re-upload existing logos through the admin panel if needed.
6

Update custom Order model

If you use a custom Order model implementing Shopper\Core\Models\Contracts\Order, add the new contract methods (isNew(), isPaid(), isShipped(), etc.).
7

Update published order components

If you have published config/shopper/components/order.php, add the new page and component entries for shipments, fulfillment, customer, items, notes, summary, and the two new slide-overs.
8

Install Stripe addon (optional)

Run composer require shopper/stripe if you want Stripe payment support. See the Stripe addon documentation for setup.
9

Clear caches

Run php artisan optimize:clear.