Feature: Shipment Updates to handle COD

database/migrations/2026_07_21_000001_create_shipment_info_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('shipment_info', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('shipment_id')->constrained('shipments')->cascadeOnDelete();
+            $table->string('status');
+            $table->string('carrier_status')->nullable();
+            $table->text('message')->nullable();
+            $table->string('location')->nullable();
+            $table->timestamp('occurred_at');
+            $table->json('meta')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('shipment_info');
+    }
+};

src/Providers/ShippingServiceProvider.php

@@ -19,6 +19,7 @@ use Modules\Core\Shipping\Carriers\BoxNow\BoxNowFulfillmentService;
 use Modules\Core\Shipping\Carriers\BoxNow\BoxNowRateDriver;
 use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
 use Modules\Core\Shipping\Filament\Pages\ManageShippingRates;
+use Modules\Core\Shipping\Jobs\PollShipmentTrackingJob;
 use Modules\Core\Shipping\Models\Shipment;
 
 class ShippingServiceProvider extends ServiceProvider
@@ -73,6 +74,10 @@ class ShippingServiceProvider extends ServiceProvider
                 ->dailyAt('06:00')
                 ->when(fn () => ShippingMethod::where('driver', 'acs')->exists());
 
+            $this->app->make(ConsoleSchedule::class)
+                ->job(new PollShipmentTrackingJob)
+                ->everyThirtyMinutes();
+
             $this->overrideRatesPageLivewireComponent();
         });
     }

src/Shipping/Carriers/Acs/AcsFulfillmentService.php

@@ -2,26 +2,33 @@
 
 namespace Modules\Core\Shipping\Carriers\Acs;
 
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Collection;
 use Lunar\Models\Order;
 use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
 use Modules\Core\Shipping\Contracts\SupportsManifestBatching;
+use Modules\Core\Shipping\Contracts\SupportsTracking;
+use Modules\Core\Shipping\Carriers\Acs\Exceptions\AcsApiException;
 use Modules\Core\Shipping\DataTransferObjects\ManifestResult;
+use Modules\Core\Shipping\DataTransferObjects\ShipmentRequest;
+use Modules\Core\Shipping\DataTransferObjects\TrackingCheckpoint;
+use Modules\Core\Shipping\Enums\TrackingStatus;
 use Modules\Core\Shipping\Models\Shipment;
 
-class AcsFulfillmentService implements CarrierFulfillmentInterface, SupportsManifestBatching
+class AcsFulfillmentService implements CarrierFulfillmentInterface, SupportsManifestBatching, SupportsTracking
 {
     public function __construct(
         private readonly AcsClient $client,
         private readonly AreaResolver $areaResolver,
     ) {}
 
-    public function createShipment(Order $order, array $overrides = []): Shipment
+    public function createShipment(Order $order, ShipmentRequest $request): Shipment
     {
         $address = $order->shippingAddress;
         $destination = $this->areaResolver->resolve($address->postcode);
+        $weight = $request->weight ?? 0.5;
 
-        $response = $this->client->call('ACS_Create_Voucher', array_merge([
+        $params = [
             'Pickup_Date' => now()->toDateString(),
             'Sender' => config('acs.sender.name'),
             'Recipient_Name' => trim("{$address->first_name} {$address->last_name}"),
@@ -33,9 +40,17 @@ class AcsFulfillmentService implements CarrierFulfillmentInterface, SupportsMani
             'Acs_Station_Branch_Destination' => $destination->branchId,
             'Billing_Code' => config('acs.billing_code'),
             'Charge_Type' => 2,
-            'Item_Quantity' => 1,
+            'Item_Quantity' => $request->packageCount,
-            'Weight' => 0.5,
+            'Weight' => $weight,
-        ], $overrides))->throwIfError();
+        ];
+
+        if ($request->paymentMode === 'cod') {
+            $params['Cod_Ammount'] = $request->amountToCollect ?? $order->total->decimal;
+            $params['Cod_Payment_Way'] = 0; // cash
+            $params['Acs_Delivery_Products'] = 'COD';
+        }
+
+        $response = $this->client->call('ACS_Create_Voucher', $params)->throwIfError();
 
         $voucherNo = (string) $response->valueOutput['Voucher_No'];
 
@@ -45,12 +60,12 @@ class AcsFulfillmentService implements CarrierFulfillmentInterface, SupportsMani
             'tracking_reference' => $voucherNo,
             'meta' => [
                 'station_destination' => $destination->stationId,
-                'weight' => $overrides['Weight'] ?? 0.5,
+                'weight' => $weight,
                 'pickup_date' => now()->toDateString(),
             ],
         ]);
 
-        if (($overrides['Item_Quantity'] ?? 1) > 1) {
+        if ($request->packageCount > 1) {
             $this->persistMultipartVouchers($shipment);
         }
 
@@ -114,6 +129,60 @@ class AcsFulfillmentService implements CarrierFulfillmentInterface, SupportsMani
         return ManifestResult::success($pickupListNo, $shipments);
     }
 
+    public function trackShipment(Shipment $shipment): Collection
+    {
+        $response = $this->client->call('ACS_TrackingDetails', [
+            'Voucher_No' => $shipment->tracking_reference,
+        ])->throwIfError();
+
+        $rows = $response->tableOutput['Table_Data'] ?? [];
+
+        // ACS's per-checkpoint data (checkpoint_action) is free text with no
+        // status code, so the final checkpoint's status is corroborated
+        // against the structured summary call rather than guessed from text.
+        $isDelivered = $this->isDelivered($shipment);
+
+        return collect($rows)->values()->map(function (array $row, int $index) use ($rows, $isDelivered) {
+            $isLast = $index === count($rows) - 1;
+
+            return new TrackingCheckpoint(
+                status: $isLast && $isDelivered
+                    ? TrackingStatus::Delivered
+                    : $this->guessStatusFromAction($row['checkpoint_action'] ?? ''),
+                carrierStatus: $row['checkpoint_action'] ?? null,
+                message: $row['checkpoint_action'] ?? null,
+                location: $row['checkpoint_location'] ?? null,
+                occurredAt: Carbon::parse($row['checkpoint_date_time']),
+                meta: $row,
+            );
+        });
+    }
+
+    private function isDelivered(Shipment $shipment): bool
+    {
+        try {
+            $response = $this->client->call('ACS_Trackingsummary', [
+                'Voucher_No' => $shipment->tracking_reference,
+            ])->throwIfError();
+        } catch (AcsApiException) {
+            return false;
+        }
+
+        return (int) ($response->valueOutput['shipment_status'] ?? 0) === 4;
+    }
+
+    private function guessStatusFromAction(string $action): TrackingStatus
+    {
+        $action = strtolower($action);
+
+        return match (true) {
+            str_contains($action, 'delivery to consignee') => TrackingStatus::Delivered,
+            str_contains($action, 'on delivery') => TrackingStatus::OutForDelivery,
+            str_contains($action, 'arrival') || str_contains($action, 'departure') => TrackingStatus::InTransit,
+            default => TrackingStatus::Pending,
+        };
+    }
+
     private function persistMultipartVouchers(Shipment $mainShipment): void
     {
         $response = $this->client->call('ACS_Get_Multipart_Vouchers', [

src/Shipping/Carriers/BoxNow/BoxNowFulfillmentService.php

@@ -2,9 +2,15 @@
 
 namespace Modules\Core\Shipping\Carriers\BoxNow;
 
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Collection;
 use Lunar\Models\Order;
 use Modules\Core\Shipping\Carriers\BoxNow\Exceptions\BoxNowApiException;
 use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
+use Modules\Core\Shipping\Contracts\SupportsTracking;
+use Modules\Core\Shipping\DataTransferObjects\ShipmentRequest;
+use Modules\Core\Shipping\DataTransferObjects\TrackingCheckpoint;
+use Modules\Core\Shipping\Enums\TrackingStatus;
 use Modules\Core\Shipping\Models\Shipment;
 
 /**
@@ -13,28 +19,32 @@ use Modules\Core\Shipping\Models\Shipment;
  * CarrierFulfillmentInterface (not SupportsManifestBatching).
  *
  * Box Now delivers to lockers, not addresses. The storefront locker-picker
- * is out of scope for this pass — createShipment() expects the chosen
+ * is out of scope for this pass — createShipment() requires the chosen
- * locker's Box Now locationId via $overrides['locationId'] (e.g. set
+ * locker's Box Now locationId via ShipmentRequest::$destinationLocationId
- * manually by admin staff until checkout UI exists).
+ * (e.g. set manually by admin staff until checkout UI exists).
  */
-class BoxNowFulfillmentService implements CarrierFulfillmentInterface
+class BoxNowFulfillmentService implements CarrierFulfillmentInterface, SupportsTracking
 {
     public function __construct(private readonly BoxNowClient $client) {}
 
-    public function createShipment(Order $order, array $overrides = []): Shipment
+    public function createShipment(Order $order, ShipmentRequest $request): Shipment
     {
         $address = $order->shippingAddress;
-        $destinationLocationId = $overrides['locationId'] ?? null;
+        $destinationLocationId = $request->destinationLocationId;
 
         if (! $destinationLocationId) {
             throw new BoxNowApiException('No Box Now locker (locationId) was provided for this shipment.');
         }
 
+        $isCod = $request->paymentMode === 'cod';
+
         $response = $this->client->request('post', '/delivery-requests', [
             'orderNumber' => $order->reference.'-'.$order->id,
             'invoiceValue' => number_format($order->total->decimal, 2, '.', ''),
-            'paymentMode' => 'prepaid',
+            'paymentMode' => $isCod ? 'cod' : 'prepaid',
-            'amountToBeCollected' => '0.00',
+            'amountToBeCollected' => $isCod
+                ? number_format($request->amountToCollect ?? $order->total->decimal, 2, '.', '')
+                : '0.00',
             'origin' => [
                 'contactNumber' => config('boxnow.sender.phone'),
                 'contactEmail' => config('boxnow.sender.email'),
@@ -52,8 +62,8 @@ class BoxNowFulfillmentService implements CarrierFulfillmentInterface
                     'id' => (string) $order->id,
                     'name' => 'Order '.$order->reference,
                     'value' => '0.00',
-                    'compartmentSize' => $overrides['compartmentSize'] ?? 1,
+                    'compartmentSize' => 1,
-                    'weight' => $overrides['weight'] ?? 0,
+                    'weight' => $request->weight ?? 0,
                 ],
             ],
         ]);
@@ -89,4 +99,52 @@ class BoxNowFulfillmentService implements CarrierFulfillmentInterface
 
         $shipment->update(['cancelled_at' => now()]);
     }
+
+    public function trackShipment(Shipment $shipment): Collection
+    {
+        $response = $this->client->request('get', '/parcels', [
+            'parcelId' => $shipment->tracking_reference,
+        ]);
+
+        $parcel = $response['data'][0] ?? null;
+
+        if (! $parcel) {
+            return collect();
+        }
+
+        $events = $parcel['events'] ?? [];
+
+        // Fall back to a single checkpoint from the parcel's current state
+        // if Box Now didn't return a detailed events history.
+        if (empty($events)) {
+            $events = [[
+                'type' => $parcel['state'] ?? 'new',
+                'locationDisplayName' => null,
+                'createTime' => $parcel['updateTime'] ?? $parcel['createTime'] ?? now()->toIso8601String(),
+            ]];
+        }
+
+        return collect($events)->map(fn (array $event) => new TrackingCheckpoint(
+            status: $this->mapState($event['type'] ?? $parcel['state'] ?? 'new'),
+            carrierStatus: $event['type'] ?? $parcel['state'] ?? null,
+            message: null,
+            location: $event['locationDisplayName'] ?? null,
+            occurredAt: Carbon::parse($event['createTime']),
+            meta: $event,
+        ));
+    }
+
+    private function mapState(string $state): TrackingStatus
+    {
+        return match ($state) {
+            'new' => TrackingStatus::Pending,
+            'in-transit', 'in-depot' => TrackingStatus::InTransit,
+            'in-final-destination', 'wait-for-load' => TrackingStatus::OutForDelivery,
+            'delivered' => TrackingStatus::Delivered,
+            'returned', 'accepted-for-return' => TrackingStatus::Returned,
+            'cancelled' => TrackingStatus::Cancelled,
+            'expired-return', 'missing' => TrackingStatus::Failed,
+            default => TrackingStatus::Unknown,
+        };
+    }
 }

src/Shipping/Contracts/CarrierFulfillmentInterface.php

@@ -3,6 +3,7 @@
 namespace Modules\Core\Shipping\Contracts;
 
 use Lunar\Models\Order;
+use Modules\Core\Shipping\DataTransferObjects\ShipmentRequest;
 use Modules\Core\Shipping\Models\Shipment;
 
 interface CarrierFulfillmentInterface
@@ -10,7 +11,7 @@ interface CarrierFulfillmentInterface
     /**
      * Create a shipment with the carrier for the given order.
      */
-    public function createShipment(Order $order, array $overrides = []): Shipment;
+    public function createShipment(Order $order, ShipmentRequest $request): Shipment;
 
     /**
      * Fetch the printable label for a shipment (raw file bytes).

src/Shipping/Contracts/SupportsTracking.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Modules\Core\Shipping\Contracts;
+
+use Illuminate\Support\Collection;
+use Modules\Core\Shipping\DataTransferObjects\TrackingCheckpoint;
+use Modules\Core\Shipping\Models\Shipment;
+
+/**
+ * Optional capability for carriers that expose shipment tracking. Carriers
+ * without a tracking API simply don't implement it.
+ */
+interface SupportsTracking
+{
+    /**
+     * Return the shipment's known checkpoints from the carrier — as many
+     * as the carrier's API returns in one call, not just the latest one.
+     * Deduplication against what's already stored happens elsewhere.
+     *
+     * @return Collection<int, TrackingCheckpoint>
+     */
+    public function trackShipment(Shipment $shipment): Collection;
+}

src/Shipping/DataTransferObjects/ShipmentRequest.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Shipping\DataTransferObjects;
+
+/**
+ * Carrier-agnostic input for CarrierFulfillmentInterface::createShipment().
+ * Every field is optional — a carrier reads only what it needs and ignores
+ * the rest (e.g. destinationLocationId only matters to locker-delivery
+ * carriers like Box Now; ACS has no use for it).
+ */
+class ShipmentRequest
+{
+    public function __construct(
+        public readonly ?float $weight = null,
+        public readonly int $packageCount = 1,
+        public readonly ?string $destinationLocationId = null,
+        public readonly ?string $paymentMode = null,
+        public readonly ?float $amountToCollect = null,
+    ) {}
+}

src/Shipping/DataTransferObjects/TrackingCheckpoint.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Modules\Core\Shipping\DataTransferObjects;
+
+use Carbon\CarbonInterface;
+use Modules\Core\Shipping\Enums\TrackingStatus;
+
+/**
+ * One normalized checkpoint in a shipment's carrier-reported history.
+ * Returned (potentially several at once) by SupportsTracking::trackShipment().
+ */
+class TrackingCheckpoint
+{
+    public function __construct(
+        public readonly TrackingStatus $status,
+        public readonly ?string $carrierStatus,
+        public readonly ?string $message,
+        public readonly ?string $location,
+        public readonly CarbonInterface $occurredAt,
+        public readonly array $meta = [],
+    ) {}
+}

src/Shipping/Enums/TrackingStatus.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Core\Shipping\Enums;
+
+/**
+ * Normalized shipment status, mapped from each carrier's own status codes
+ * (e.g. ACS's shipment_status/non_delivery_reason_code, Box Now's parcel
+ * state) so the rest of the system never needs to know carrier-specific
+ * vocabulary.
+ */
+enum TrackingStatus: string
+{
+    case Pending = 'pending';
+    case InTransit = 'in_transit';
+    case OutForDelivery = 'out_for_delivery';
+    case Delivered = 'delivered';
+    case Failed = 'failed';
+    case Returned = 'returned';
+    case Cancelled = 'cancelled';
+    case Unknown = 'unknown';
+
+    public function isTerminal(): bool
+    {
+        return match ($this) {
+            self::Delivered, self::Returned, self::Cancelled => true,
+            default => false,
+        };
+    }
+}

src/Shipping/Events/ShipmentStatusUpdatedByCarrier.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Modules\Core\Shipping\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Modules\Core\Shipping\Models\ShipmentInfo;
+
+/**
+ * Fired once per newly-recorded ShipmentInfo checkpoint. Listeners (e.g.
+ * customer notifications, order status sync) are added separately.
+ */
+class ShipmentStatusUpdatedByCarrier
+{
+    use Dispatchable;
+
+    public function __construct(public readonly ShipmentInfo $shipmentInfo) {}
+}

src/Shipping/Extensions/OrderViewExtension.php

@@ -9,6 +9,7 @@ use Lunar\Admin\Support\Extending\ViewPageExtension;
 use Lunar\Models\Order;
 use Lunar\Shipping\Models\ShippingMethod;
 use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
+use Modules\Core\Shipping\DataTransferObjects\ShipmentRequest;
 
 class OrderViewExtension extends ViewPageExtension
 {
@@ -26,6 +27,15 @@ class OrderViewExtension extends ViewPageExtension
             ->icon('heroicon-o-truck')
             ->modalSubmitActionLabel('Create Shipment')
             ->form([
+                Forms\Components\TextInput::make('weight')
+                    ->label('Package weight (kg)')
+                    ->numeric()
+                    ->minValue(0)
+                    ->helperText('Leave blank to use the carrier\'s default.'),
+                Forms\Components\TextInput::make('destination_location_id')
+                    ->label('Box Now locker ID')
+                    ->helperText('Only required for Box Now shipments.')
+                    ->default(fn (Order $record) => $record->shippingAddress?->meta['box_now_locker']['locationId'] ?? null),
                 Forms\Components\Toggle::make('confirm')
                     ->label('Confirm')
                     ->helperText('This will create a real shipment with the carrier.')
@@ -39,7 +49,7 @@ class OrderViewExtension extends ViewPageExtension
                         },
                     ]),
             ])
-            ->action(function (Order $record, Actions\Action $action) {
+            ->action(function (Order $record, array $data, Actions\Action $action) {
                 $service = $this->resolveFulfillmentService($record);
 
                 if (! $service) {
@@ -53,8 +63,13 @@ class OrderViewExtension extends ViewPageExtension
                     return;
                 }
 
+                $request = new ShipmentRequest(
+                    weight: filled($data['weight'] ?? null) ? (float) $data['weight'] : null,
+                    destinationLocationId: $data['destination_location_id'] ?? null,
+                );
+
                 try {
-                    $service->createShipment($record);
+                    $service->createShipment($record, $request);
                 } catch (\Throwable $e) {
                     report($e);
 

src/Shipping/Jobs/PollShipmentTrackingJob.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Modules\Core\Shipping\Jobs;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Lunar\Shipping\Facades\Shipping;
+use Modules\Core\Shipping\Contracts\CarrierFulfillmentInterface;
+use Modules\Core\Shipping\Contracts\SupportsTracking;
+use Modules\Core\Shipping\Enums\TrackingStatus;
+use Modules\Core\Shipping\Events\ShipmentStatusUpdatedByCarrier;
+use Modules\Core\Shipping\Models\Shipment;
+use Modules\Core\Shipping\Models\ShipmentInfo;
+
+/**
+ * Carrier-agnostic: polls every Shipment not yet in a terminal state,
+ * skipping carriers whose fulfillment service doesn't implement
+ * SupportsTracking. New checkpoints are recorded in shipment_info and
+ * dispatch ShipmentStatusUpdatedByCarrier — one event per new checkpoint.
+ */
+class PollShipmentTrackingJob implements ShouldQueue
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+    use SerializesModels;
+
+    public int $tries = 3;
+
+    public int $backoff = 60;
+
+    public function handle(): void
+    {
+        $trackableCarriers = collect(Shipping::getSupportedDrivers())->keys()->filter(
+            fn (string $carrier) => $this->fulfillmentService($carrier) instanceof SupportsTracking
+        );
+
+        if ($trackableCarriers->isEmpty()) {
+            return;
+        }
+
+        Shipment::query()
+            ->whereIn('carrier', $trackableCarriers)
+            ->whereNull('cancelled_at')
+            ->whereDoesntHave('shipmentInfo', function ($query) {
+                $query->whereIn('status', [
+                    TrackingStatus::Delivered->value,
+                    TrackingStatus::Returned->value,
+                    TrackingStatus::Cancelled->value,
+                ]);
+            })
+            ->chunkById(50, function ($shipments) {
+                $shipments->groupBy('carrier')->each(
+                    fn ($group, $carrier) => $this->pollCarrierShipments($carrier, $group)
+                );
+            });
+    }
+
+    private function pollCarrierShipments(string $carrier, $shipments): void
+    {
+        $service = $this->fulfillmentService($carrier);
+
+        if (! $service instanceof SupportsTracking) {
+            return;
+        }
+
+        foreach ($shipments as $shipment) {
+            $this->recordNewCheckpoints($shipment, $service->trackShipment($shipment));
+        }
+    }
+
+    private function recordNewCheckpoints(Shipment $shipment, $checkpoints): void
+    {
+        $existing = $shipment->shipmentInfo()
+            ->get(['status', 'occurred_at'])
+            ->map(fn ($info) => $info->status->value.'|'.$info->occurred_at->toIso8601String())
+            ->flip();
+
+        foreach ($checkpoints as $checkpoint) {
+            $fingerprint = $checkpoint->status->value.'|'.$checkpoint->occurredAt->toIso8601String();
+
+            if ($existing->has($fingerprint)) {
+                continue;
+            }
+
+            $info = ShipmentInfo::create([
+                'shipment_id' => $shipment->id,
+                'status' => $checkpoint->status,
+                'carrier_status' => $checkpoint->carrierStatus,
+                'message' => $checkpoint->message,
+                'location' => $checkpoint->location,
+                'occurred_at' => $checkpoint->occurredAt,
+                'meta' => $checkpoint->meta,
+            ]);
+
+            ShipmentStatusUpdatedByCarrier::dispatch($info);
+        }
+    }
+
+    private function fulfillmentService(string $carrier): ?CarrierFulfillmentInterface
+    {
+        return app(CarrierFulfillmentInterface::class, ['carrier' => $carrier]);
+    }
+}

src/Shipping/Models/Shipment.php

@@ -5,6 +5,7 @@ namespace Modules\Core\Shipping\Models;
 use Illuminate\Database\Eloquent\Casts\AsArrayObject;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Lunar\Models\Order;
 
 class Shipment extends Model
@@ -21,4 +22,14 @@ class Shipment extends Model
     {
         return $this->belongsTo(Order::class);
     }
+
+    public function shipmentInfo(): HasMany
+    {
+        return $this->hasMany(ShipmentInfo::class);
+    }
+
+    public function latestShipmentInfo(): ?ShipmentInfo
+    {
+        return $this->shipmentInfo()->latest('occurred_at')->first();
+    }
 }

src/Shipping/Models/ShipmentInfo.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Modules\Core\Shipping\Models;
+
+use Illuminate\Database\Eloquent\Casts\AsArrayObject;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Modules\Core\Shipping\Enums\TrackingStatus;
+
+/**
+ * One recorded checkpoint in a Shipment's carrier-reported tracking
+ * history. Append-only — never updated in place, so the full history is
+ * preserved rather than overwriting the last-known status.
+ */
+class ShipmentInfo extends Model
+{
+    protected $table = 'shipment_info';
+
+    protected $guarded = [];
+
+    protected $casts = [
+        'status' => TrackingStatus::class,
+        'occurred_at' => 'datetime',
+        'meta' => AsArrayObject::class,
+    ];
+
+    public function shipment(): BelongsTo
+    {
+        return $this->belongsTo(Shipment::class);
+    }
+}