Fulfillment
Complete guide to order fulfillment, multi-shipment management, and dropshipping workflows in Shopper.
Order fulfillment in Shopper is designed around the concept of shipments, physical packages sent to customers. A single order can have multiple shipments, each with its own carrier, tracking number, and set of items.
Architecture
The fulfillment system connects four models:
Order (1) ──> (many) OrderShipping (1) ──> (many) OrderItem
(shipment) │ (items in this package)
└──> (many) OrderShippingEvent
(tracking timeline)- Order has many shipments (
OrderShipping) and tracks overallshipping_status - Each shipment has its own
status(ShipmentStatus) and a timeline of events (OrderShippingEvent) - Each item tracks its own fulfillment status independently
use Shopper\Core\Models\Order;
use Shopper\Core\Models\OrderShipping;
use Shopper\Core\Models\OrderShippingEvent;
use Shopper\Core\Models\OrderItem;
use Shopper\Core\Enum\ShippingStatus;
use Shopper\Core\Enum\ShipmentStatus;
use Shopper\Core\Enum\FulfillmentStatus;Database Schema
OrderShipping Table
| Column | Type | Nullable | Description |
|---|---|---|---|
id | bigint | no | Primary key |
order_id | bigint | no | FK to order |
carrier_id | bigint | yes | FK to carrier |
status | string(32) | yes | Shipment status enum |
shipped_at | datetime | yes | When the shipment was dispatched |
received_at | datetime | yes | When the customer received it |
returned_at | datetime | yes | If the shipment was returned |
tracking_number | string | yes | Carrier tracking number |
tracking_url | string | yes | URL for customer tracking |
voucher | json | yes | Shipping label/voucher data |
created_at | timestamp | yes | Creation timestamp |
updated_at | timestamp | yes | Last update timestamp |
OrderShippingEvent Table
| Column | Type | Nullable | Description |
|---|---|---|---|
id | bigint | no | Primary key |
order_shipping_id | bigint | no | FK to shipment |
status | string(32) | no | Shipment status at this event |
description | text | yes | Event description |
location | string | yes | Location name |
latitude | decimal(11,7) | yes | GPS latitude |
longitude | decimal(10,7) | yes | GPS longitude |
occurred_at | datetime | no | When the event occurred (logEvent() sets it to now when you omit it) |
metadata | jsonb | yes | Additional event data |
created_at | timestamp | yes | Creation timestamp |
updated_at | timestamp | yes | Last update timestamp |
OrderItem Fulfillment Columns
| Column | Type | Nullable | Description |
|---|---|---|---|
order_shipping_id | bigint | yes | FK to the shipment this item belongs to |
fulfillment_status | string | yes | Current fulfillment state of this item. pending when the item is created through the OrderItem model; items created before this column existed keep null |
Fulfillment Status
The FulfillmentStatus enum defines the lifecycle of each item:
use Shopper\Core\Enum\FulfillmentStatus;
FulfillmentStatus::Pending // Awaiting processing
FulfillmentStatus::ForwardedToSupplier // Sent to external supplier (dropshipping)
FulfillmentStatus::Processing // Being prepared for shipment
FulfillmentStatus::Shipped // In transit
FulfillmentStatus::Delivered // Received by customer
FulfillmentStatus::Cancelled // Fulfillment cancelledStatus Flow
| From | Possible Transitions |
|---|---|
| Pending | Processing, ForwardedToSupplier, Shipped, Cancelled |
| ForwardedToSupplier | Processing, Shipped, Cancelled |
| Processing | Shipped, Cancelled |
| Shipped | Delivered, Cancelled |
| Delivered | Cancelled |
| Cancelled | (terminal state) |
The table lists the transitions that make sense for an item. Nothing on OrderItem enforces them: fulfillment_status accepts any case.
Shopper performs three of them, in RecordShipmentEventAction, on the items of the shipment that receives the event: Pending to Shipped when the carrier picks up the package, Shipped to Delivered on delivery, and any status to Cancelled when the package is returned. Your own code sets every other transition. Shopper never sets Processing or ForwardedToSupplier, and the pickup leaves items in these two statuses as they are, so move them to Shipped yourself, as the dropshipping workflow does. The admin's shipping label form only offers items that are in no shipment yet and whose status is Pending (or null), so an item you moved to Processing or ForwardedToSupplier cannot be added to a label there.
Shipping Status (Order Level)
The ShippingStatus enum lives on the Order model (shipping_status, Unfulfilled by default). SyncOrderShippingStatusAction computes it from the fulfillment status of all the order's items. It answers "has this order been shipped/delivered?".
use Shopper\Core\Enum\ShippingStatus;
ShippingStatus::Unfulfilled // No items shipped yet
ShippingStatus::PartiallyShipped // Some items shipped
ShippingStatus::Shipped // All items shipped
ShippingStatus::PartiallyDelivered // Some items delivered
ShippingStatus::Delivered // All items delivered
ShippingStatus::PartiallyReturned // Some items returned
ShippingStatus::Returned // All items returnedShipment Status (Package Level)
The ShipmentStatus enum lives on the OrderShipping model and tracks the delivery progress of a single package. Each shipment goes through this lifecycle independently.
use Shopper\Core\Enum\ShipmentStatus;
ShipmentStatus::Pending // Label created, waiting for pickup
ShipmentStatus::PickedUp // Carrier collected the package
ShipmentStatus::InTransit // On the way
ShipmentStatus::AtSortingCenter // At a sorting facility
ShipmentStatus::OutForDelivery // With the local delivery driver
ShipmentStatus::Delivered // Delivered to the customer
ShipmentStatus::DeliveryFailed // Delivery attempt failed
ShipmentStatus::Returned // Returned to senderShipment Transitions
The HasFulfillmentTransitions trait on OrderShipping defines the valid state transitions. transitionTo() and the actions check them; writing status with update() skips the check.
| From | Possible Transitions |
|---|---|
| Pending | PickedUp, Returned |
| PickedUp | InTransit, DeliveryFailed, Returned |
| InTransit | AtSortingCenter, OutForDelivery, DeliveryFailed, Returned |
| AtSortingCenter | InTransit, OutForDelivery, DeliveryFailed, Returned |
| OutForDelivery | Delivered, DeliveryFailed, Returned |
| Delivered | Returned |
| DeliveryFailed | InTransit, OutForDelivery, Returned |
| Returned | (terminal state) |
A shipment whose status is null (created without one) can only move to Pending.
$shipment->canTransitionTo(ShipmentStatus::InTransit); // true or false
$shipment->allowedTransitions(); // array of valid next statuses
$shipment->canBeDelivered(); // shorthand for canTransitionTo(Delivered)
OrderShipping::shipmentTransitions(); // the full table above, keyed by status valueTransitioning Shipment Status
Use transitionTo() to update the shipment status. It checks the transition and automatically logs a tracking event:
$shipment->transitionTo(ShipmentStatus::PickedUp, [
'description' => 'Package collected by carrier',
'location' => 'Paris Distribution Center',
'latitude' => 48.8566,
'longitude' => 2.3522,
]);This creates an OrderShippingEvent record with the status, timestamp, and optional location data. When the transition is not allowed, transitionTo() returns without saving anything and throws no exception. It only changes the shipment and its timeline: to also update the items and the order, use RecordShipmentEventAction.
Tracking Events
Each shipment has a timeline of events that record its journey. Adding an event does not change the shipment status:
$shipment->events; // Collection<OrderShippingEvent>
$shipment->events()->create([
'status' => ShipmentStatus::InTransit,
'description' => 'Package departed sorting facility',
'location' => 'Lyon Hub',
'occurred_at' => now(),
'metadata' => ['facility_code' => 'LYS-01'],
]);
// logEvent() writes the same record and sets occurred_at to now when omitted
$shipment->logEvent(ShipmentStatus::InTransit, [
'description' => 'Package departed sorting facility',
'location' => 'Lyon Hub',
]);Relationships
Order to Shipments
// Get all shipments for an order
$order->shippings; // Collection<OrderShipping>
// Load shipments with their carrier and items
$order->load('shippings.carrier', 'shippings.items');
// Check if every item has been delivered
$allDelivered = $order->items->every(
fn (OrderItem $item) => $item->fulfillment_status === FulfillmentStatus::Delivered
);OrderShipping to Items and Events
// Get all items in a shipment
$shipment->items; // Collection<OrderItem>
// Get the carrier for this shipment
$shipment->carrier; // Carrier model
// Get the parent order
$shipment->order; // Order model
// Get the tracking timeline
$shipment->events; // Collection<OrderShippingEvent>OrderItem to Shipment
// Get the shipment for an item
$item->shipment; // OrderShipping (nullable)
// Get tracking info for an item
$item->shipment?->tracking_number;
$item->shipment?->tracking_url;
$item->shipment?->carrier?->name;Creating Shipments
Single Shipment (All Items Together)
When all items ship in one package:
use Shopper\Core\Actions\RecordShipmentEventAction;
$order = Order::query()->find($orderId);
// Create the shipment: the label exists, the carrier has not collected the package yet
$shipment = $order->shippings()->create([
'carrier_id' => $carrier->id,
'status' => ShipmentStatus::Pending,
'tracking_number' => '1Z999AA10123456784',
'tracking_url' => 'https://ups.com/track?num=1Z999AA10123456784',
]);
// Link all items to the package
$order->items()->update(['order_shipping_id' => $shipment->id]);
// Record the carrier pickup
resolve(RecordShipmentEventAction::class)->execute($shipment, ShipmentStatus::PickedUp);Recording PickedUp sets shipped_at, moves the linked items from Pending to Shipped, moves a New order to Processing, and recomputes the order's shipping_status. Create the shipment with the Pending status: a shipment without a status can only move to Pending, so recording PickedUp on it does nothing.
Partial Shipment (Split Across Packages)
When items ship in multiple packages with different carriers:
use Shopper\Core\Actions\RecordShipmentEventAction;
$order = Order::query()
->with('items')
->find($orderId);
$recordEvent = resolve(RecordShipmentEventAction::class);
// First package: items 1 and 2 via Colissimo
$shipment1 = $order->shippings()->create([
'carrier_id' => $colissimoId,
'status' => ShipmentStatus::Pending,
'tracking_number' => 'LP123456789FR',
'tracking_url' => 'https://laposte.fr/suivi/LP123456789FR',
]);
$order->items()
->whereIn('id', [$item1->id, $item2->id])
->update(['order_shipping_id' => $shipment1->id]);
$recordEvent->execute($shipment1, ShipmentStatus::PickedUp);
// Second package: item 3 via UPS (ships later)
$shipment2 = $order->shippings()->create([
'carrier_id' => $upsId,
'status' => ShipmentStatus::Pending,
'tracking_number' => '1Z999AA10987654321',
'tracking_url' => 'https://ups.com/track?num=1Z999AA10987654321',
]);
$order->items()
->where('id', $item3->id)
->update(['order_shipping_id' => $shipment2->id]);
$recordEvent->execute($shipment2, ShipmentStatus::PickedUp);After the first pickup the order's shipping_status is PartiallyShipped. After the second it is Shipped, and OrderShipped is dispatched.
Marking as Delivered
use Shopper\Core\Actions\MarkShipmentDeliveredAction;
resolve(MarkShipmentDeliveredAction::class)->execute($shipment, [
'description' => 'Left with the building concierge',
]);The action sets received_at, moves the shipment's Shipped items to Delivered, recomputes the order's shipping_status, and moves the order from Processing to Completed once every item of the order is delivered. Delivered is only reachable from OutForDelivery: on a shipment in any other status the action does nothing, so record InTransit and OutForDelivery with RecordShipmentEventAction first.
Dropshipping Workflow
For external products sourced from suppliers, the fulfillment flow includes an additional step where the order is forwarded to the supplier who ships directly to the customer.
Dropshipping requires the Supplier feature to be enabled. External products must be linked to a supplier.
Complete Dropshipping Flow
use Shopper\Core\Actions\RecordShipmentEventAction;
$order = Order::query()
->with('items.product')
->find($orderId);
// Step 1: Forward items to their suppliers
foreach ($order->items as $item) {
if ($item->product->supplier_id) {
$item->update([
'fulfillment_status' => FulfillmentStatus::ForwardedToSupplier,
]);
}
}
// Step 2: When the supplier ships, create the shipment
$shipment = $order->shippings()->create([
'carrier_id' => $carrierId,
'status' => ShipmentStatus::Pending,
'tracking_number' => $trackingFromSupplier,
'tracking_url' => $trackingUrlFromSupplier,
]);
// Link supplier items to the shipment and mark them shipped:
// the pickup event below only moves Pending items to Shipped
$order->items()
->where('fulfillment_status', FulfillmentStatus::ForwardedToSupplier)
->update([
'order_shipping_id' => $shipment->id,
'fulfillment_status' => FulfillmentStatus::Shipped,
]);
resolve(RecordShipmentEventAction::class)->execute($shipment, ShipmentStatus::PickedUp);OrderItem::product() is polymorphic: a variant line points to a ProductVariant, which has no supplier_id and no supplier relation. For those lines, read the supplier from the parent product: $item->product->product->supplier_id.
Mixed Orders (Own Products + Supplier Products)
An order can contain both your own products and dropshipped products:
use Shopper\Core\Actions\RecordShipmentEventAction;
$order = Order::query()
->with('items.product')
->find($orderId);
$ownItems = $order->items->filter(
fn ($item) => ! $item->product->supplier_id
);
$supplierItems = $order->items->filter(
fn ($item) => $item->product->supplier_id
);
// Ship your own products immediately
if ($ownItems->isNotEmpty()) {
$shipment = $order->shippings()->create([
'carrier_id' => $yourCarrierId,
'status' => ShipmentStatus::Pending,
'tracking_number' => $yourTracking,
]);
$order->items()
->whereIn('id', $ownItems->pluck('id'))
->update(['order_shipping_id' => $shipment->id]);
resolve(RecordShipmentEventAction::class)->execute($shipment, ShipmentStatus::PickedUp);
}
// Forward supplier items
if ($supplierItems->isNotEmpty()) {
$order->items()
->whereIn('id', $supplierItems->pluck('id'))
->update([
'fulfillment_status' => FulfillmentStatus::ForwardedToSupplier,
]);
}Querying Fulfillment Data
Items by Status
use Illuminate\Database\Eloquent\Relations\MorphTo;
// Get all unfulfilled items across orders
$unfulfilledItems = OrderItem::query()
->whereNull('fulfillment_status')
->orWhere('fulfillment_status', FulfillmentStatus::Pending)
->with('order.customer')
->get();
// Get items waiting for supplier, with the supplier of product lines
// (variant lines have no supplier relation)
$awaitingSupplier = OrderItem::query()
->where('fulfillment_status', FulfillmentStatus::ForwardedToSupplier)
->with(['product' => fn (MorphTo $morphTo) => $morphTo->morphWith([
config('shopper.models.product') => ['supplier'],
])])
->get();Orders Needing Attention
// Orders with items not yet shipped
$ordersToFulfill = Order::query()
->whereHas('items', fn ($q) => $q
->where('fulfillment_status', FulfillmentStatus::Pending)
->orWhereNull('fulfillment_status')
)
->with('items', 'shippings')
->get();
// Orders partially shipped
$partiallyShipped = Order::query()
->where('shipping_status', ShippingStatus::PartiallyShipped)
->get();Shipment History
// Get all shipments for a customer
$customerShipments = OrderShipping::query()
->whereHas('order', fn ($q) => $q->where('customer_id', $customerId))
->with(['carrier', 'items', 'order'])
->latest('shipped_at')
->get();Handling Returns
use Shopper\Core\Actions\RecordShipmentEventAction;
resolve(RecordShipmentEventAction::class)->execute($shipment, ShipmentStatus::Returned, [
'description' => 'Returned to sender: recipient unknown at this address',
]);Recording Returned sets returned_at, marks every item of the shipment as Cancelled, and recomputes the order's shipping_status: Returned when every item of the order is cancelled, PartiallyReturned when the other items are shipped or delivered. Any status except Returned can move to Returned. The order status does not change.
Actions
Shopper provides dedicated action classes for fulfillment operations. These handle side effects like syncing order statuses, updating item states, and dispatching events automatically.
RecordShipmentEventAction
The recommended way to record shipment events. It checks the transition, updates the shipment status, logs the event, and handles side effects based on the new status. It returns the created OrderShippingEvent, or null without changing anything when the transition is not allowed or when occurred_at is earlier than the shipment's latest event:
use Shopper\Core\Actions\RecordShipmentEventAction;
use Shopper\Core\Enum\ShipmentStatus;
$action = resolve(RecordShipmentEventAction::class);
$action->execute($shipment, ShipmentStatus::PickedUp, [
'description' => 'Package collected by carrier',
'location' => 'Paris Distribution Center',
'occurred_at' => now(),
]);When a shipment transitions to PickedUp, the action sets shipped_at to the event date, updates the shipment's Pending items to FulfillmentStatus::Shipped (items in another status keep it), and changes the order status from New to Processing.
When a shipment transitions to Delivered, the action sets received_at, updates the shipment's Shipped items to FulfillmentStatus::Delivered, and moves the order from Processing to Completed when every item of the order is delivered. It does not dispatch OrderShipmentDelivered or OrderCompleted: use MarkShipmentDeliveredAction below when your listeners need the delivery event.
When a shipment transitions to Returned, the action sets returned_at and updates all items of the shipment to FulfillmentStatus::Cancelled.
After each of these three transitions, the action runs SyncOrderShippingStatusAction on the order. Other statuses (InTransit, AtSortingCenter, OutForDelivery, DeliveryFailed) only update the shipment and its timeline.
MarkShipmentDeliveredAction
A convenience action for marking a shipment as delivered. It records the Delivered event through RecordShipmentEventAction and dispatches the OrderShipmentDelivered event. When the shipment cannot transition to Delivered (its status is not OutForDelivery), it does nothing:
use Shopper\Core\Actions\MarkShipmentDeliveredAction;
$action = resolve(MarkShipmentDeliveredAction::class);
$action->execute($shipment, [
'description' => 'Delivered to customer',
'location' => 'Customer address',
]);SyncOrderShippingStatusAction
This action computes the order-level shipping_status from the fulfillment statuses of all its items. RecordShipmentEventAction runs it after a PickedUp, Delivered or Returned event. Call it yourself when you update item statuses directly:
use Shopper\Core\Actions\SyncOrderShippingStatusAction;
$action = resolve(SyncOrderShippingStatusAction::class);
$action->execute($order);The algorithm counts items by fulfillment status and determines the order shipping status. The first matching row wins, and an order without items is left unchanged:
| Condition | Order Shipping Status |
|---|---|
| All items cancelled | Returned |
| Some cancelled, rest shipped/delivered | PartiallyReturned |
| No items shipped or delivered | Unfulfilled |
| All items delivered | Delivered |
| Some items delivered | PartiallyDelivered |
| All items shipped or delivered | Shipped |
| Otherwise | PartiallyShipped |
When the status transitions to Shipped, the OrderShipped event is dispatched.
Events
OrderShipped and OrderShipmentDelivered are dispatched by the actions above. OrderShipmentCreated is dispatched by the admin when a staff member creates a shipping label; creating a shipment in your own code does not dispatch it, so dispatch it yourself if your listeners need it: OrderShipmentCreated::dispatch($order, $shipment).
| Event | Dispatched When | Properties |
|---|---|---|
OrderShipmentCreated | A shipping label is created from the admin | Order $order, OrderShipping $shipment |
OrderShipped | Order shipping_status transitions to Shipped (SyncOrderShippingStatusAction) | Order $order |
OrderShipmentDelivered | A shipment is marked as delivered with MarkShipmentDeliveredAction | Order $order, OrderShipping $shipment |
use Shopper\Core\Events\Orders\OrderShipmentCreated;
use Shopper\Core\Events\Orders\OrderShipped;
use Shopper\Core\Events\Orders\OrderShipmentDelivered;Storefront Example
Order Tracking Page
namespace App\Http\Controllers;
use Shopper\Core\Models\Order;
class OrderTrackingController extends Controller
{
public function show(Order $order)
{
abort_unless($order->customer_id === auth()->id(), 403);
$order->load([
'items.shipment.carrier',
'shippings.carrier',
'shippings.items',
]);
return view('orders.tracking', [
'order' => $order,
'shipments' => $order->shippings->map(fn ($shipment) => [
'carrier' => $shipment->carrier?->name,
'tracking_number' => $shipment->tracking_number,
'tracking_url' => $shipment->tracking_url,
'shipped_at' => $shipment->shipped_at,
'received_at' => $shipment->received_at,
'items' => $shipment->items->map(fn ($item) => [
'name' => $item->name,
'quantity' => $item->quantity,
'status' => $item->fulfillment_status,
]),
]),
]);
}
}Best Practices
| Practice | Description |
|---|---|
| Update statuses atomically | Record shipment events with RecordShipmentEventAction so the shipment, its items and the order shipping_status change together |
| Complete orders automatically | Let RecordShipmentEventAction complete the order on delivery; if you change item statuses yourself, check that all items are delivered and update the order status |
| Group items by carrier | Items from the same supplier or warehouse should share a shipment |
| Store tracking URLs | Always provide tracking_url so customers can track packages directly |
| Handle mixed orders | Process your own products and supplier products as separate shipments |
Last updated on
Edit on GitHub