Estimated Upgrade Time: 15-30 minutes for most applications.
Updating Dependencies
Update yourcomposer.json file to require Shopper 2.5:
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 monolithicOrderStatus enum has been split into three independent enums, each tracking a different concern:
| Concern | Enum | Values |
|---|---|---|
| Order lifecycle | OrderStatus | New, Processing, Completed, Cancelled, Archived |
| Payment | PaymentStatus | Pending, Authorized, Paid, PartiallyRefunded, Refunded, Voided |
| Shipping | ShippingStatus | Unfulfilled, PartiallyShipped, Shipped, PartiallyDelivered, Delivered, PartiallyReturned, Returned |
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)
Automatic Data Migration
The migration automatically maps your existing order statuses to the new three-status system. No manual data migration is needed.Old status value | New status | New payment_status | New shipping_status |
|---|---|---|---|
pending | new | pending | unfulfilled |
registered | processing | pending | unfulfilled |
paid | processing | paid | unfulfilled |
shipped | processing | paid | shipped |
delivered | processing | paid | delivered |
completed | completed | paid | (unchanged) |
cancelled | cancelled | (unchanged) | (unchanged) |
PaymentMethod & Carrier Logo Handling
Likelihood of Impact: High Thelogo 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)
Spatie\MediaLibrary\HasMedia and use the HasMedia trait.
Payment System
Likelihood of Impact: High Shopper 2.5 introduces a complete payment driver system through the newshopper/payment package, which is included as a dependency of shopper/framework.
Key components:
PaymentProcessingService— orchestrates payment operations (initiate, authorize, capture, refund, cancel) through driversPaymentTransactionmodel — records every payment operation with driver, type, status, amount, and provider referencePaymentDrivercontract — interface for implementing payment providersPaymentManager— resolves and manages payment drivers (a manual driver is included by default)
Shopper\Payment\Enum:
| Enum | Values |
|---|---|
TransactionType | Initiate, Authorize, Capture, Refund, Cancel |
TransactionStatus | Pending, Success, Failed |
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 theShopper\Core\Models\Contracts\Order interface, you must add the following methods:
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)
OrderItem Fulfillment Tracking
Likelihood of Impact: Medium Two new columns have been added to theorder_items table:
fulfillment_status— tracks per-item fulfillment using the newFulfillmentStatusenum (Pending,ForwardedToSupplier,Processing,Shipped,Delivered,Cancelled)order_shipping_id— links each item to a specific shipment
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 inconfig/shopper/components/order.php.
Components marked New were added in v2.5. Components marked Existing were already present but have been refactored.
| Component | Alias | Type | Description |
|---|---|---|---|
Index | shopper-order-index | Existing | Order listing with filters and tabs |
Detail | shopper-order-detail | Existing | Order detail page (refactored, now uses sub-components) |
Shipments | shopper-order-shipments | New | Centralized shipment list with filters and tab navigation |
Fulfillment | shopper-order-fulfillment | New | Fulfillment progress stepper, shipping address, create shipment button |
OrderCustomer | shopper-order-customer | New | Customer info, shipping and billing addresses |
OrderItems | shopper-order-items | New | Paginated order items with fulfillment status badges |
OrderNotes | shopper-order-notes | New | Notes editor with save action |
OrderSummary | shopper-order-summary | New | Financial summary, shipping method, payment method |
ShipmentTimeline | shopper-order-shipment-timeline | New | Shipment event timeline with “Add event” action |
CreateShippingLabel | shopper-slide-overs.create-shipping-label | New | Slide-over form to create a shipment and assign unfulfilled items |
ShipmentDetail | shopper-slide-overs.shipment-detail | New | Slide-over with shipment detail, event timeline, and delivery actions |
php artisan shopper:component:publish order, update your config/shopper/components/order.php to include the new entries:
OrderShipping: Status Column & Events
Likelihood of Impact: Medium Theorder_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:
Low Impact Changes
New Events
Likelihood of Impact: Low Three new events have been added inShopper\Core\Events\Orders:
| Event | When it fires |
|---|---|
OrderArchived | An order is archived |
OrderShipmentCreated | A new shipment is created for an order |
OrderShipmentDelivered | A shipment is marked as delivered |
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 toShopper\Core\Enum:
| Enum | Values |
|---|---|
PaymentStatus | Pending, Authorized, Paid, PartiallyRefunded, Refunded, Voided |
ShippingStatus | Unfulfilled, PartiallyShipped, Shipped, PartiallyDelivered, Delivered, PartiallyReturned, Returned |
ShipmentStatus | Pending, PickedUp, InTransit, AtSortingCenter, OutForDelivery, Delivered, DeliveryFailed, Returned |
FulfillmentStatus | Pending, ForwardedToSupplier, Processing, Shipped, Delivered, Cancelled |
HasColor, HasIcon, and HasLabel.
Translation Keys
Likelihood of Impact: Low New translation keys have been added undershopper-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 newshopper/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 withPaymentStatus::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 aShipmentStatus 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
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.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.Rename `canceled_at` to `cancelled_at`
Update any code, queries, or Blade templates that reference
$order->canceled_at to use $order->cancelled_at.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.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.).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.Install Stripe addon (optional)
Run
composer require shopper/stripe if you want Stripe payment support. See the Stripe addon documentation for setup.