Skip to content

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 overall shipping_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

ColumnTypeNullableDescription
idbigintnoPrimary key
order_idbigintnoFK to order
carrier_idbigintyesFK to carrier
statusstring(32)yesShipment status enum
shipped_atdatetimeyesWhen the shipment was dispatched
received_atdatetimeyesWhen the customer received it
returned_atdatetimeyesIf the shipment was returned
tracking_numberstringyesCarrier tracking number
tracking_urlstringyesURL for customer tracking
voucherjsonyesShipping label/voucher data
created_attimestampyesCreation timestamp
updated_attimestampyesLast update timestamp

OrderShippingEvent Table

ColumnTypeNullableDescription
idbigintnoPrimary key
order_shipping_idbigintnoFK to shipment
statusstring(32)noShipment status at this event
descriptiontextyesEvent description
locationstringyesLocation name
latitudedecimal(11,7)yesGPS latitude
longitudedecimal(10,7)yesGPS longitude
occurred_atdatetimenoWhen the event occurred (logEvent() sets it to now when you omit it)
metadatajsonbyesAdditional event data
created_attimestampyesCreation timestamp
updated_attimestampyesLast update timestamp

OrderItem Fulfillment Columns

ColumnTypeNullableDescription
order_shipping_idbigintyesFK to the shipment this item belongs to
fulfillment_statusstringyesCurrent 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 cancelled

Status Flow

FromPossible Transitions
PendingProcessing, ForwardedToSupplier, Shipped, Cancelled
ForwardedToSupplierProcessing, Shipped, Cancelled
ProcessingShipped, Cancelled
ShippedDelivered, Cancelled
DeliveredCancelled
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 returned

Shipment 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 sender

Shipment Transitions

The HasFulfillmentTransitions trait on OrderShipping defines the valid state transitions. transitionTo() and the actions check them; writing status with update() skips the check.

FromPossible Transitions
PendingPickedUp, Returned
PickedUpInTransit, DeliveryFailed, Returned
InTransitAtSortingCenter, OutForDelivery, DeliveryFailed, Returned
AtSortingCenterInTransit, OutForDelivery, DeliveryFailed, Returned
OutForDeliveryDelivered, DeliveryFailed, Returned
DeliveredReturned
DeliveryFailedInTransit, 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 value

Transitioning 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:

ConditionOrder Shipping Status
All items cancelledReturned
Some cancelled, rest shipped/deliveredPartiallyReturned
No items shipped or deliveredUnfulfilled
All items deliveredDelivered
Some items deliveredPartiallyDelivered
All items shipped or deliveredShipped
OtherwisePartiallyShipped

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).

EventDispatched WhenProperties
OrderShipmentCreatedA shipping label is created from the adminOrder $order, OrderShipping $shipment
OrderShippedOrder shipping_status transitions to Shipped (SyncOrderShippingStatusAction)Order $order
OrderShipmentDeliveredA shipment is marked as delivered with MarkShipmentDeliveredActionOrder $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

PracticeDescription
Update statuses atomicallyRecord shipment events with RecordShipmentEventAction so the shipment, its items and the order shipping_status change together
Complete orders automaticallyLet 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 carrierItems from the same supplier or warehouse should share a shipment
Store tracking URLsAlways provide tracking_url so customers can track packages directly
Handle mixed ordersProcess your own products and supplier products as separate shipments

Last updated on

Edit on GitHub