From ea48962eb2be4f61def4075160fdb1e570d4bebf Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 16:00:05 +0800
Subject: [PATCH 1/8] fix: rebuild storefront push notifications on a single
 push channel

Android pushes never worked with store-level FCM credentials and some iOS
devices were rejected, because of several stacked defects:

- configureFcm put the service account JSON into credentials.private_key,
  so no valid Firebase client was ever built from a store channel
- FcmChannel required the platform-wide Firebase project to be configured
- credentials were always resolved from the store, never the network app
- one APNs environment per channel rejected sandbox/dev build tokens
- registerDevice never reassigned a token to the latest customer and did
  not normalize platform casing
- mail/database errors ran before push and stopped it; failures and dead
  tokens were never handled or logged

Introduce Push\StorefrontPushChannel with isolated Firebase/APNs clients,
network-first credential resolution with wrong-app and wrong-environment
retries, dead token pruning, and high priority payloads. Order
notifications share a StorefrontOrderNotification base class. Add a
customers/unregister-device endpoint and an admin test push action.
---
 .../modals/create-notification-channel.hbs    |  14 +
 .../modals/test-notification-channel.hbs      |  33 ++
 .../networks/index/network/index.js           |  10 +
 addon/controllers/settings/notifications.js   |  39 ++
 .../networks/index/network/index.hbs          |   1 +
 addon/templates/settings/notifications.hbs    |   1 +
 addon/utils/get-notification-schemas.js       |   5 +-
 .../modals/test-notification-channel.js       |   1 +
 server/config/storefront.php                  |  13 +
 .../NotificationChannelController.php         |  62 +++
 .../Controllers/v1/CustomerController.php     |  98 +++-
 server/src/Listeners/HandleOrderCompleted.php |   5 +-
 .../Listeners/HandleOrderDriverAssigned.php   |   5 +-
 server/src/Listeners/HandleOrderStarted.php   |   5 +-
 .../PromotionalPushNotification.php           | 131 +----
 .../Notifications/StorefrontOrderAccepted.php | 144 +----
 .../Notifications/StorefrontOrderCanceled.php | 137 +----
 .../StorefrontOrderCompleted.php              | 144 +----
 .../StorefrontOrderDriverAssigned.php         | 146 +----
 .../Notifications/StorefrontOrderEnroute.php  | 144 +----
 .../Notifications/StorefrontOrderNearby.php   | 154 +----
 .../StorefrontOrderNotification.php           | 151 +++++
 .../StorefrontOrderPreparing.php              | 144 +----
 .../StorefrontOrderReadyForPickup.php         | 144 +----
 server/src/Push/ApnClientFactory.php          |  87 +++
 .../Push/Contracts/SendsPushNotification.php  |  28 +
 server/src/Push/FirebaseMessagingFactory.php  |  87 +++
 .../src/Push/PushConfigurationException.php   |   7 +
 server/src/Push/PushCredentialResolver.php    |  82 +++
 server/src/Push/PushMessage.php               | 193 +++++++
 server/src/Push/PushOutcome.php               |  58 ++
 server/src/Push/StorefrontPushChannel.php     | 236 ++++++++
 server/src/Push/Transports/ApnTransport.php   |  68 +++
 server/src/Push/Transports/FcmTransport.php   |  76 +++
 server/src/Support/PushNotification.php       | 152 -----
 server/src/Support/Storefront.php             |   3 +-
 server/src/routes.php                         |   8 +-
 .../CustomerDeviceRegistrationTest.php        | 175 ++++++
 .../NotificationChannelTestPushTest.php       | 121 ++++
 .../NotificationContractsTest.php             | 509 ++---------------
 server/tests/Unit/Push/PushLayerTest.php      | 526 ++++++++++++++++++
 translations/en-us.yaml                       |  13 +
 42 files changed, 2299 insertions(+), 1861 deletions(-)
 create mode 100644 addon/components/modals/test-notification-channel.hbs
 create mode 100644 app/components/modals/test-notification-channel.js
 create mode 100644 server/src/Notifications/StorefrontOrderNotification.php
 create mode 100644 server/src/Push/ApnClientFactory.php
 create mode 100644 server/src/Push/Contracts/SendsPushNotification.php
 create mode 100644 server/src/Push/FirebaseMessagingFactory.php
 create mode 100644 server/src/Push/PushConfigurationException.php
 create mode 100644 server/src/Push/PushCredentialResolver.php
 create mode 100644 server/src/Push/PushMessage.php
 create mode 100644 server/src/Push/PushOutcome.php
 create mode 100644 server/src/Push/StorefrontPushChannel.php
 create mode 100644 server/src/Push/Transports/ApnTransport.php
 create mode 100644 server/src/Push/Transports/FcmTransport.php
 delete mode 100644 server/src/Support/PushNotification.php
 create mode 100644 server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
 create mode 100644 server/tests/Unit/Http/Controllers/NotificationChannelTestPushTest.php
 create mode 100644 server/tests/Unit/Push/PushLayerTest.php

diff --git a/addon/components/modals/create-notification-channel.hbs b/addon/components/modals/create-notification-channel.hbs
index be48cf72..59e63251 100644
--- a/addon/components/modals/create-notification-channel.hbs
+++ b/addon/components/modals/create-notification-channel.hbs
@@ -34,6 +34,20 @@
                         <div class="input-group">
                             <Checkbox @value={{value}} @label={{humanize key}} @onToggle={{fn @options.setConfigKey key}} />
                         </div>
+                    {{else if (eq key "environment")}}
+                        <InputGroup @name={{humanize key}} @helpText={{t "storefront.component.modals.create-notification-channel.environment-help-text"}}>
+                            <Select
+                                class="w-full"
+                                @options={{array "auto" "production" "sandbox"}}
+                                @value={{value}}
+                                @onSelect={{fn @options.setConfigKey key}}
+                                @humanize={{true}}
+                            />
+                        </InputGroup>
+                    {{else if (eq key "android_channel_id")}}
+                        <InputGroup @name={{humanize key}} @helpText={{t "storefront.component.modals.create-notification-channel.android-channel-id-help-text"}}>
+                            <Input class="form-input w-full" placeholder={{humanize key}} @value={{value}} {{on "blur" (fn @options.setConfigKey key)}} />
+                        </InputGroup>
                     {{else if (or (eq key "private_key_content") (eq key "firebase_credentials_json"))}}
                         <InputGroup @name={{humanize key}}>
                             <Textarea class="form-input w-full" rows="6" placeholder={{humanize key}} @value={{value}} {{on "blur" (fn @options.setConfigKey key)}} />
diff --git a/addon/components/modals/test-notification-channel.hbs b/addon/components/modals/test-notification-channel.hbs
new file mode 100644
index 00000000..bf2ae53f
--- /dev/null
+++ b/addon/components/modals/test-notification-channel.hbs
@@ -0,0 +1,33 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container">
+        <InputGroup @name={{t "storefront.component.modals.test-notification-channel.token"}} @helpText={{t "storefront.component.modals.test-notification-channel.token-text"}}>
+            <Textarea class="form-input w-full" rows="3" @value={{@options.token}} {{on "blur" @options.setToken}} />
+        </InputGroup>
+
+        {{#if (eq @options.channel.scheme "apn")}}
+            <InputGroup @name={{t "storefront.component.modals.test-notification-channel.environment"}} @helpText={{t "storefront.component.modals.test-notification-channel.environment-text"}}>
+                <Select
+                    class="w-full"
+                    @options={{array "production" "sandbox"}}
+                    @value={{@options.environment}}
+                    @placeholder={{t "storefront.component.modals.test-notification-channel.environment"}}
+                    @onSelect={{@options.setEnvironment}}
+                    @humanize={{true}}
+                />
+            </InputGroup>
+        {{/if}}
+
+        {{#if @options.results}}
+            <div class="p-2 rounded-md my-2 border border-gray-200 dark:border-gray-800">
+                <h4 class="mb-2 font-semibold text-sm dark:text-white">{{t "storefront.component.modals.test-notification-channel.result"}}</h4>
+                {{#each @options.results as |result|}}
+                    <div class="text-xs font-mono dark:text-gray-200 mb-1">
+                        {{#if result.environment}}[{{result.environment}}]{{/if}}
+                        {{result.status}}
+                        {{#if result.reason}}- {{result.reason}}{{/if}}
+                    </div>
+                {{/each}}
+            </div>
+        {{/if}}
+    </div>
+</Modal::Default>
diff --git a/addon/controllers/networks/index/network/index.js b/addon/controllers/networks/index/network/index.js
index d954305f..5902ddd9 100644
--- a/addon/controllers/networks/index/network/index.js
+++ b/addon/controllers/networks/index/network/index.js
@@ -269,6 +269,16 @@ export default class NetworksIndexNetworkIndexController extends Controller {
         return this.notificationsController.deleteChannel(...arguments);
     }
 
+    /**
+     * Send a test push notification through a notification channel.
+     *
+     * @method testChannel
+     * @public
+     */
+    @action testChannel() {
+        return this.notificationsController.testChannel(...arguments);
+    }
+
     /**
      * Make an alertable action.
      *
diff --git a/addon/controllers/settings/notifications.js b/addon/controllers/settings/notifications.js
index 6579face..927119eb 100644
--- a/addon/controllers/settings/notifications.js
+++ b/addon/controllers/settings/notifications.js
@@ -14,6 +14,7 @@ export default class SettingsNotificationsController extends Controller {
     @service crud;
     @service storefront;
     @service hostRouter;
+    @service fetch;
     @alias('storefront.activeStore') activeStore;
     queryParams = ['query'];
 
@@ -88,6 +89,44 @@ export default class SettingsNotificationsController extends Controller {
         });
     }
 
+    @action testChannel(channel) {
+        this.modalsManager.show('modals/test-notification-channel', {
+            title: this.intl.t('storefront.settings.notification.send-test-push'),
+            acceptButtonText: this.intl.t('storefront.settings.notification.send-test-push-button'),
+            acceptButtonIcon: 'paper-plane',
+            channel,
+            token: '',
+            environment: null,
+            results: null,
+            setToken: (event) => {
+                this.modalsManager.setOption('token', event.target.value);
+            },
+            setEnvironment: (environment) => {
+                this.modalsManager.setOption('environment', environment);
+            },
+            keepOpen: true,
+            confirm: async (modal) => {
+                const { token, environment } = this.modalsManager.getOptions(['token', 'environment']);
+                modal.startLoading();
+
+                try {
+                    const response = await this.fetch.post(`notification-channels/${channel.id}/test`, { token, environment }, { namespace: 'storefront/int/v1' });
+                    this.modalsManager.setOption('results', response.results);
+
+                    if (response.status === 'OK') {
+                        this.notifications.success(this.intl.t('storefront.settings.notification.test-push-sent'));
+                    } else {
+                        this.notifications.warning(this.intl.t('storefront.settings.notification.test-push-failed'));
+                    }
+                } catch (error) {
+                    this.notifications.serverError(error);
+                } finally {
+                    modal.stopLoading();
+                }
+            },
+        });
+    }
+
     @action deleteChannel(channel) {
         this.modalsManager.confirm({
             title: this.intl.t('storefront.settings.notification.remove-this-notification-channel'),
diff --git a/addon/templates/networks/index/network/index.hbs b/addon/templates/networks/index/network/index.hbs
index 28991534..b5997801 100644
--- a/addon/templates/networks/index/network/index.hbs
+++ b/addon/templates/networks/index/network/index.hbs
@@ -419,6 +419,7 @@
                             <span class="dark:text-gray-50">{{notificationChannel.name}}</span>
                         </div>
                         <div class="flex items-center">
+                            <Button @size="xs" @type="default" @text={{t "storefront.settings.notification.send-test"}} @wrapperClass="mr-2" @onClick={{fn this.testChannel notificationChannel}} />
                             <Button @size="xs" @type="default" @text={{t "storefront.common.edit"}} @wrapperClass="mr-2" @onClick={{fn this.editChannel notificationChannel}} />
                             <Button @size="xs" @type="danger" @text={{t "storefront.common.delete"}} @onClick={{fn this.deleteChannel notificationChannel}} />
                         </div>
diff --git a/addon/templates/settings/notifications.hbs b/addon/templates/settings/notifications.hbs
index b70f0556..4925e7d9 100644
--- a/addon/templates/settings/notifications.hbs
+++ b/addon/templates/settings/notifications.hbs
@@ -22,6 +22,7 @@
                             <span class="dark:text-gray-50">{{notificationChannel.name}}</span>
                         </div>
                         <div class="flex items-center">
+                            <Button @size="xs" @type="default" @text={{t "storefront.settings.notification.send-test"}} @wrapperClass="mr-2" @onClick={{fn this.testChannel notificationChannel}} />
                             <Button @size="xs" @type="default" @text={{t "storefront.common.edit"}} @wrapperClass="mr-2" @onClick={{fn this.editChannel notificationChannel}} />
                             <Button @size="xs" @type="danger" @text={{t "storefront.common.delete"}} @onClick={{fn this.deleteChannel notificationChannel}} />
                         </div>
diff --git a/addon/utils/get-notification-schemas.js b/addon/utils/get-notification-schemas.js
index fd486de0..c6b94c22 100644
--- a/addon/utils/get-notification-schemas.js
+++ b/addon/utils/get-notification-schemas.js
@@ -5,12 +5,11 @@ export default function getNotificationSchemas() {
             team_id: '',
             app_bundle_id: '',
             private_key_content: '',
-            production: true,
+            environment: 'auto',
         },
         fcm: {
             firebase_credentials_json: '',
-            firebase_database_url: '',
-            firebase_project_name: '',
+            android_channel_id: '',
         },
     };
 
diff --git a/app/components/modals/test-notification-channel.js b/app/components/modals/test-notification-channel.js
new file mode 100644
index 00000000..40993d59
--- /dev/null
+++ b/app/components/modals/test-notification-channel.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/test-notification-channel';
diff --git a/server/config/storefront.php b/server/config/storefront.php
index 7161a4c8..3f6b48f1 100644
--- a/server/config/storefront.php
+++ b/server/config/storefront.php
@@ -45,6 +45,19 @@
         ))),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Push Notifications
+    |--------------------------------------------------------------------------
+    |
+    | android_channel_id: the Android notification channel storefront pushes are
+    | posted to. Leave empty to use the app's default FCM channel. A notification
+    | channel's own `android_channel_id` setting takes precedence.
+    */
+    'push' => [
+        'android_channel_id' => env('STOREFRONT_PUSH_ANDROID_CHANNEL_ID'),
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Database Connection
diff --git a/server/src/Http/Controllers/NotificationChannelController.php b/server/src/Http/Controllers/NotificationChannelController.php
index cdcbcf40..27922880 100644
--- a/server/src/Http/Controllers/NotificationChannelController.php
+++ b/server/src/Http/Controllers/NotificationChannelController.php
@@ -2,6 +2,13 @@
 
 namespace Fleetbase\Storefront\Http\Controllers;
 
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Push\ApnClientFactory;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\Transports\ApnTransport;
+use Fleetbase\Storefront\Push\Transports\FcmTransport;
+use Illuminate\Http\Request;
+
 class NotificationChannelController extends StorefrontController
 {
     /**
@@ -10,4 +17,59 @@ class NotificationChannelController extends StorefrontController
      * @var string
      */
     public $resource = 'notification_channel';
+
+    /**
+     * Send a test push to a single device token through a notification channel and report
+     * the provider's raw outcome, so credential or token problems can be diagnosed.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function testPush(string $id, Request $request, FcmTransport $fcm, ApnTransport $apn)
+    {
+        $token = trim((string) $request->input('token'));
+        if ($token === '') {
+            return response()->error('A device token is required.');
+        }
+
+        $channel = NotificationChannel::where(function ($query) use ($id) {
+            $query->where('uuid', $id)->orWhere('app_key', $id);
+        })->where('company_uuid', session('company'))->first();
+
+        if (!$channel) {
+            return response()->error('Notification channel not found.', 404);
+        }
+
+        $message = PushMessage::create(
+            $request->input('title', 'Test notification'),
+            $request->input('body', 'Push notifications from ' . ($channel->name ?? 'your storefront') . ' are working.'),
+            ['type' => 'test']
+        );
+
+        $results = [];
+        try {
+            if ($channel->scheme === 'fcm') {
+                $outcome   = $fcm->send($channel, $message, [$token])[$token] ?? null;
+                $results[] = ['environment' => null, 'status' => $outcome?->status ?? 'error', 'reason' => $outcome?->reason];
+            } else {
+                $environments = $request->filled('environment') ? [$request->input('environment')] : ApnClientFactory::environments($channel);
+                foreach ($environments as $environment) {
+                    $outcome   = $apn->send($channel, $environment, $message, [$token])[$token] ?? null;
+                    $results[] = ['environment' => $environment, 'status' => $outcome?->status ?? 'error', 'reason' => $outcome?->reason];
+                    if ($outcome?->status === 'sent') {
+                        break;
+                    }
+                }
+            }
+        } catch (\Throwable $e) {
+            $results[] = ['environment' => null, 'status' => 'error', 'reason' => $e->getMessage()];
+        }
+
+        $sent = collect($results)->contains('status', 'sent');
+
+        return response()->json([
+            'status'  => $sent ? 'OK' : 'FAILED',
+            'scheme'  => $channel->scheme,
+            'results' => $results,
+        ]);
+    }
 }
diff --git a/server/src/Http/Controllers/v1/CustomerController.php b/server/src/Http/Controllers/v1/CustomerController.php
index e7d742d6..9bc5b79a 100644
--- a/server/src/Http/Controllers/v1/CustomerController.php
+++ b/server/src/Http/Controllers/v1/CustomerController.php
@@ -20,6 +20,7 @@
 use Fleetbase\Storefront\Http\Requests\CreateCustomerRequest;
 use Fleetbase\Storefront\Http\Requests\VerifyCreateCustomerRequest;
 use Fleetbase\Storefront\Http\Resources\Customer;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
 use Fleetbase\Storefront\Support\Storefront;
 use Fleetbase\Support\Utils;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
@@ -48,18 +49,51 @@ public function registerDevice(Request $request)
             return response()->apiError('Not authorized to register device for cutomer');
         }
 
-        $device = UserDevice::firstOrCreate(
-            [
-                'token'    => $request->input('token'),
-                'platform' => $request->or(['platform', 'os']),
-            ],
-            [
-                'user_uuid' => $customer->user_uuid,
-                'platform'  => $request->or(['platform', 'os']),
-                'token'     => $request->input('token'),
-                'status'    => 'active',
-            ]
-        );
+        $token    = trim((string) $request->input('token'));
+        $platform = StorefrontPushChannel::normalizePlatform($request->or(['platform', 'os']));
+
+        if ($token === '') {
+            return response()->apiError('A device token is required.');
+        }
+
+        if (!$platform) {
+            return response()->apiError('Device platform must be either ios or android.');
+        }
+
+        if (!$customer->user_uuid) {
+            return response()->apiError('Unable to register device for customer without a user account.');
+        }
+
+        // A token identifies one app install, so it always belongs to the customer who
+        // registered it most recently (e.g. after logging out and in as someone else).
+        $devices = UserDevice::withTrashed()->where('token', $token)->orderByDesc('updated_at')->get();
+        $device  = $devices->shift() ?? new UserDevice();
+        $devices->each(fn (UserDevice $duplicate) => $duplicate->forceDelete());
+
+        if ($device->exists && $device->trashed()) {
+            $device->restore();
+        }
+
+        $device->fill([
+            'user_uuid' => $customer->user_uuid,
+            'platform'  => $platform,
+            'token'     => $token,
+            'status'    => 'active',
+        ]);
+
+        $optionalAttributes = [
+            'environment'    => in_array($request->input('environment'), ['production', 'sandbox'], true) ? $request->input('environment') : null,
+            'app_identifier' => session('storefront_store') ?? session('storefront_network'),
+            'last_seen_at'   => now(),
+        ];
+        $columns = static::userDeviceColumns();
+        foreach ($optionalAttributes as $column => $value) {
+            if (in_array($column, $columns, true)) {
+                $device->forceFill([$column => $value]);
+            }
+        }
+
+        $device->save();
 
         return response()->json([
             'status' => 'OK',
@@ -67,6 +101,46 @@ public function registerDevice(Request $request)
         ]);
     }
 
+    /**
+     * Unregister a device token for the authenticated customer, e.g. on logout.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function unregisterDevice(Request $request)
+    {
+        $customer = Storefront::getCustomerFromToken();
+
+        if (!$customer) {
+            return response()->apiError('Not authorized to unregister device for customer');
+        }
+
+        $token = trim((string) $request->input('token'));
+        if ($token === '') {
+            return response()->apiError('A device token is required.');
+        }
+
+        $deleted = UserDevice::where('token', $token)->where('user_uuid', $customer->user_uuid)->get()->each(fn (UserDevice $device) => $device->delete())->count();
+
+        return response()->json([
+            'status'  => 'OK',
+            'deleted' => $deleted,
+        ]);
+    }
+
+    /**
+     * Newer core-api versions add push metadata columns to user_devices.
+     *
+     * @return string[]
+     */
+    protected static function userDeviceColumns(): array
+    {
+        try {
+            return (new UserDevice())->getConnection()->getSchemaBuilder()->getColumnListing('user_devices');
+        } catch (\Throwable $e) {
+            return [];
+        }
+    }
+
     /**
      * Query for Storefront Customer orders.
      *
diff --git a/server/src/Listeners/HandleOrderCompleted.php b/server/src/Listeners/HandleOrderCompleted.php
index 6b55c662..43113c3b 100644
--- a/server/src/Listeners/HandleOrderCompleted.php
+++ b/server/src/Listeners/HandleOrderCompleted.php
@@ -26,7 +26,10 @@ public function handle(OrderCompleted $event)
         // if storefront order notify customer driver has been addigned
         if ($order->hasMeta('storefront_id')) {
             $order->load(['customer']);
-            $order->customer->notify(new StorefrontOrderCompleted($order));
+
+            if ($order->customer) {
+                $order->customer->notify(new StorefrontOrderCompleted($order));
+            }
         }
     }
 }
diff --git a/server/src/Listeners/HandleOrderDriverAssigned.php b/server/src/Listeners/HandleOrderDriverAssigned.php
index 225f6971..6585e0f7 100644
--- a/server/src/Listeners/HandleOrderDriverAssigned.php
+++ b/server/src/Listeners/HandleOrderDriverAssigned.php
@@ -32,7 +32,10 @@ public function handle(OrderDriverAssigned $event)
         // if storefront order notify customer driver has been addigned
         if ($order->hasMeta('storefront_id')) {
             $order->load(['customer']);
-            $order->customer->notify(new StorefrontOrderDriverAssigned($order));
+
+            if ($order->customer) {
+                $order->customer->notify(new StorefrontOrderDriverAssigned($order));
+            }
         }
     }
 }
diff --git a/server/src/Listeners/HandleOrderStarted.php b/server/src/Listeners/HandleOrderStarted.php
index c8893edd..d7000b34 100644
--- a/server/src/Listeners/HandleOrderStarted.php
+++ b/server/src/Listeners/HandleOrderStarted.php
@@ -22,7 +22,10 @@ public function handle(OrderStarted $event)
         // if storefront order / notify customer driver has started and is en-route
         if ($order->hasMeta('storefront_id')) {
             $order->load(['customer']);
-            $order->customer->notify(new StorefrontOrderEnroute($order));
+
+            if ($order->customer) {
+                $order->customer->notify(new StorefrontOrderEnroute($order));
+            }
         }
     }
 }
diff --git a/server/src/Notifications/PromotionalPushNotification.php b/server/src/Notifications/PromotionalPushNotification.php
index 127a6365..d0a4c898 100644
--- a/server/src/Notifications/PromotionalPushNotification.php
+++ b/server/src/Notifications/PromotionalPushNotification.php
@@ -3,13 +3,13 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
+use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
 use Illuminate\Bus\Queueable;
 use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class PromotionalPushNotification extends Notification
+class PromotionalPushNotification extends Notification implements SendsPushNotification
 {
     use Queueable;
 
@@ -57,120 +57,37 @@ public function __construct(string $title, string $body, Store $store)
      */
     public function via($notifiable): array
     {
-        $channels = [];
-
-        // Check if store has APN notification channel configured
-        $apnChannel = PushNotification::getNotificationChannel('apn', $this->store);
-        if ($apnChannel) {
-            $channels[] = ApnChannel::class;
-        }
-
-        // Check if store has FCM notification channel configured
-        $fcmChannel = PushNotification::getNotificationChannel('fcm', $this->store);
-        if ($fcmChannel) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
+        return [StorefrontPushChannel::class, 'database'];
     }
 
     /**
-     * Get the APN representation of the notification.
+     * Get the push notification representation of the notification.
      */
-    public function toApn($notifiable)
+    public function toPush($notifiable): ?PushMessage
     {
-        $client = $this->getApnClient();
-        if (!$client) {
-            return null;
-        }
-
-        return \NotificationChannels\Apn\ApnMessage::create()
-            ->badge(1)
-            ->title($this->title)
-            ->body($this->body)
-            ->custom('type', 'promotional')
-            ->custom('store', $this->store->uuid)
-            ->custom('store_id', $this->store->public_id)
-            ->via($client);
+        return PushMessage::create($this->title, $this->body, [
+            'type'     => 'promotional',
+            'store'    => $this->store->uuid,
+            'store_id' => $this->store->public_id,
+        ])->analyticsLabel('promotional');
     }
 
     /**
-     * Get the FCM representation of the notification.
+     * The store's own app first, then the apps of networks the store belongs to.
      */
-    public function toFcm($notifiable)
+    public function pushStorefronts(): array
     {
-        $notificationChannel = $this->getFcmNotificationChannel();
-        if (!$notificationChannel) {
-            return null;
+        $storefronts = [$this->store];
+
+        try {
+            foreach ($this->store->networks as $network) {
+                $storefronts[] = $network;
+            }
+        } catch (\Throwable $e) {
+            // Network membership is optional for promotional delivery.
         }
 
-        // Configure FCM
-        PushNotification::configureFcm($notificationChannel);
-
-        // Get FCM Client
-        $client = $this->getFcmClient($notificationChannel);
-
-        // Create Notification
-        $notification = new \NotificationChannels\Fcm\Resources\Notification(
-            title: $this->title,
-            body: $this->body
-        );
-
-        return (new \NotificationChannels\Fcm\FcmMessage(notification: $notification))
-            ->data([
-                'type'     => 'promotional',
-                'store'    => $this->store->uuid,
-                'store_id' => $this->store->public_id,
-            ])
-            ->custom([
-                'android' => [
-                    'notification' => [
-                        'color' => '#4391EA',
-                        'sound' => 'default',
-                    ],
-                    'fcm_options' => [
-                        'analytics_label' => 'promotional',
-                    ],
-                ],
-                'apns' => [
-                    'payload' => [
-                        'aps' => [
-                            'sound' => 'default',
-                        ],
-                    ],
-                    'fcm_options' => [
-                        'analytics_label' => 'promotional',
-                    ],
-                ],
-            ])
-            ->usingClient($client);
-    }
-
-    /**
-     * Resolve the APN client configured for the notification store.
-     */
-    protected function getApnClient(): ?\Pushok\Client
-    {
-        return PushNotification::getApnClient($this->store);
-    }
-
-    /**
-     * Resolve the FCM channel configured for the notification store.
-     */
-    protected function getFcmNotificationChannel(): ?\Fleetbase\Storefront\Models\NotificationChannel
-    {
-        return PushNotification::getNotificationChannel('fcm', $this->store);
-    }
-
-    /**
-     * Resolve the Firebase messaging client for the selected channel.
-     */
-    protected function getFcmClient(\Fleetbase\Storefront\Models\NotificationChannel $notificationChannel)
-    {
-        $container      = \Illuminate\Container\Container::getInstance();
-        $projectManager = new \Kreait\Laravel\Firebase\FirebaseProjectManager($container);
-
-        return $projectManager->project($notificationChannel->app_key)->messaging();
+        return $storefronts;
     }
 
     /**
@@ -181,6 +98,8 @@ public function toArray($notifiable): array
         return [
             'title'           => $this->title,
             'body'            => $this->body,
+            'subject'         => $this->title,
+            'message'         => $this->body,
             'store'           => $this->store->uuid,
             'store_id'        => $this->store->public_id,
             'type'            => 'promotional',
diff --git a/server/src/Notifications/StorefrontOrderAccepted.php b/server/src/Notifications/StorefrontOrderAccepted.php
index e68d8eb2..487311c5 100644
--- a/server/src/Notifications/StorefrontOrderAccepted.php
+++ b/server/src/Notifications/StorefrontOrderAccepted.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderAccepted extends Notification
+class StorefrontOrderAccepted extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,104 +13,10 @@ class StorefrontOrderAccepted extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' has been accepted.';
         $this->body    = 'Your order was accepted.';
         $this->status  = 'order_accepted';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Notifications/StorefrontOrderCanceled.php b/server/src/Notifications/StorefrontOrderCanceled.php
index d447a8f8..d1049296 100644
--- a/server/src/Notifications/StorefrontOrderCanceled.php
+++ b/server/src/Notifications/StorefrontOrderCanceled.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderCanceled extends Notification
+class StorefrontOrderCanceled extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,103 +13,20 @@ class StorefrontOrderCanceled extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' was canceled';
         $this->body    = 'Your order from ' . $this->storefront->name . ' has been canceled, if your card has been charged you will be refunded.';
         $this->status  = 'order_canceled';
     }
 
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
     /**
      * Get the mail representation of the notification.
      *
-     * @return MailMessage
+     * @return \Illuminate\Notifications\Messages\MailMessage
      */
     public function toMail($notifiable)
     {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body)
-            ->line('No further action is necessary.');
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->body,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
+        return parent::toMail($notifiable)->line('No further action is necessary.');
     }
 }
diff --git a/server/src/Notifications/StorefrontOrderCompleted.php b/server/src/Notifications/StorefrontOrderCompleted.php
index f8e973d6..12a7a86e 100644
--- a/server/src/Notifications/StorefrontOrderCompleted.php
+++ b/server/src/Notifications/StorefrontOrderCompleted.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderCompleted extends Notification
+class StorefrontOrderCompleted extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,104 +13,10 @@ class StorefrontOrderCompleted extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' has been delivered';
         $this->body    = 'Your order from ' . $this->storefront->name . ' has been delivered, enjoy!';
         $this->status  = 'order_completed';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Notifications/StorefrontOrderDriverAssigned.php b/server/src/Notifications/StorefrontOrderDriverAssigned.php
index 6f9bc12c..9f89deed 100644
--- a/server/src/Notifications/StorefrontOrderDriverAssigned.php
+++ b/server/src/Notifications/StorefrontOrderDriverAssigned.php
@@ -4,60 +4,14 @@
 
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderDriverAssigned extends Notification
+class StorefrontOrderDriverAssigned extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
     /**
      * The driver assigned to the order.
      */
     public Driver $driver;
 
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -65,105 +19,11 @@ class StorefrontOrderDriverAssigned extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->driver         = $order->driverAssigned;
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
+        $this->driver  = $order->driverAssigned;
         $this->subject = 'Your driver is ' . $this->driver->name;
         $this->body    = 'A driver has been assigned to your order from ' . $this->storefront->name . ', they are currently en-route for pickup';
         $this->status  = 'order_driver_assigned';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Notifications/StorefrontOrderEnroute.php b/server/src/Notifications/StorefrontOrderEnroute.php
index fa14b2f4..23893981 100644
--- a/server/src/Notifications/StorefrontOrderEnroute.php
+++ b/server/src/Notifications/StorefrontOrderEnroute.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderEnroute extends Notification
+class StorefrontOrderEnroute extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,104 +13,10 @@ class StorefrontOrderEnroute extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' is on the way!';
         $this->body    = 'Your order from ' . $this->storefront->name . ' has been picked up, we will update you when your order is nearby';
         $this->status  = 'order_enroute';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Notifications/StorefrontOrderNearby.php b/server/src/Notifications/StorefrontOrderNearby.php
index 455e67c2..8a56e801 100644
--- a/server/src/Notifications/StorefrontOrderNearby.php
+++ b/server/src/Notifications/StorefrontOrderNearby.php
@@ -3,41 +3,10 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
 use Fleetbase\Support\Utils;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderNearby extends Notification
+class StorefrontOrderNearby extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
     /**
      * The distance the driver is from the customer.
      */
@@ -48,21 +17,6 @@ class StorefrontOrderNearby extends Notification
      */
     public int $time = 0;
 
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -70,106 +24,12 @@ class StorefrontOrderNearby extends Notification
      */
     public function __construct(Order $order, int $distance = 0, int $time = 0)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->distance       = $distance;
-        $this->time           = $time;
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
-
-        $this->subject = 'Your order is nearby!';
-        $this->body    = 'Your order from ' . $this->storefront->name . ' is reaching in ' . Utils::formatSeconds($time);
-        $this->status  = 'order_nearby';
-    }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
+        parent::__construct($order);
 
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
+        $this->distance = $distance;
+        $this->time     = $time;
+        $this->subject  = 'Your order is nearby!';
+        $this->body     = 'Your order from ' . $this->storefront->name . ' is reaching in ' . Utils::formatSeconds($time);
+        $this->status   = 'order_nearby';
     }
 }
diff --git a/server/src/Notifications/StorefrontOrderNotification.php b/server/src/Notifications/StorefrontOrderNotification.php
new file mode 100644
index 00000000..690a8265
--- /dev/null
+++ b/server/src/Notifications/StorefrontOrderNotification.php
@@ -0,0 +1,151 @@
+<?php
+
+namespace Fleetbase\Storefront\Notifications;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
+use Fleetbase\Storefront\Push\PushCredentialResolver;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Support\Storefront;
+use Illuminate\Bus\Queueable;
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Notifications\Notification;
+
+/**
+ * Base class for order lifecycle notifications sent to storefront customers.
+ */
+abstract class StorefrontOrderNotification extends Notification implements SendsPushNotification
+{
+    use Queueable;
+
+    /**
+     * The order instance this notification is for.
+     */
+    public Order $order;
+
+    /**
+     * The storefront the order was placed with.
+     */
+    public Store|Network $storefront;
+
+    /**
+     * The time the notification was sent.
+     */
+    public string $sentAt;
+
+    /**
+     * The ID of the notification.
+     */
+    public string $notificationId;
+
+    /**
+     * The notification subject.
+     */
+    public string $subject;
+
+    /**
+     * The notification body.
+     */
+    public string $body;
+
+    /**
+     * The notification order status.
+     */
+    public string $status;
+
+    /**
+     * Create a new notification instance.
+     */
+    public function __construct(Order $order)
+    {
+        $this->order          = $order;
+        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
+        $this->sentAt         = now()->toDateTimeString();
+        $this->notificationId = uniqid('notification_');
+    }
+
+    /**
+     * Get the notification's delivery channels.
+     *
+     * Push is sent first and never throws, so mail or database failures cannot stop it.
+     */
+    public function via($notifiable): array
+    {
+        return [StorefrontPushChannel::class, 'database', 'mail'];
+    }
+
+    /**
+     * Get the mail representation of the notification.
+     *
+     * @return MailMessage
+     */
+    public function toMail($notifiable)
+    {
+        return (new MailMessage())
+            ->subject($this->subject)
+            ->line($this->body);
+    }
+
+    /**
+     * Get the push notification representation of the notification.
+     */
+    public function toPush($notifiable): ?PushMessage
+    {
+        return PushMessage::create($this->subject, $this->body, [
+            'type'       => $this->status,
+            'order'      => $this->order->uuid,
+            'id'         => $this->order->public_id,
+            'store_id'   => $this->order->getMeta('storefront_id'),
+            'network_id' => $this->order->getMeta('storefront_network_id'),
+        ])->analyticsLabel('storefront_order');
+    }
+
+    /**
+     * The storefronts whose push credentials may deliver this notification.
+     */
+    public function pushStorefronts(): array
+    {
+        $storefronts = PushCredentialResolver::storefrontsForOrder($this->order);
+
+        if (empty($storefronts) && isset($this->storefront)) {
+            $storefronts[] = $this->storefront;
+        }
+
+        return $storefronts;
+    }
+
+    /**
+     * Get the array representation of the notification.
+     */
+    public function toArray($notifiable): array
+    {
+        $this->order->loadMissing(['customer', 'company']);
+        $customer = $this->order->customer;
+        $company  = $this->order->company;
+
+        return [
+            'notifiable'      => data_get($notifiable, 'public_id'),
+            'notification_id' => $this->notificationId,
+            'sent_at'         => $this->sentAt,
+            'type'            => $this->status,
+            'title'           => $this->subject,
+            'body'            => $this->body,
+            'subject'         => $this->subject,
+            'message'         => $this->body,
+            'order'           => $this->order->uuid,
+            'order_id'        => $this->order->public_id,
+            'storefront'      => $this->storefront->name,
+            'storefront_id'   => $this->storefront->public_id,
+            'store_id'        => $this->order->getMeta('storefront_id'),
+            'network_id'      => $this->order->getMeta('storefront_network_id'),
+            'id'              => data_get($customer, 'public_id'),
+            'email'           => data_get($customer, 'email'),
+            'phone'           => data_get($customer, 'phone'),
+            'companyId'       => data_get($company, 'public_id'),
+            'company'         => data_get($company, 'name'),
+        ];
+    }
+}
diff --git a/server/src/Notifications/StorefrontOrderPreparing.php b/server/src/Notifications/StorefrontOrderPreparing.php
index 29f82173..1b298aa5 100644
--- a/server/src/Notifications/StorefrontOrderPreparing.php
+++ b/server/src/Notifications/StorefrontOrderPreparing.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderPreparing extends Notification
+class StorefrontOrderPreparing extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,104 +13,10 @@ class StorefrontOrderPreparing extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' is being prepared!';
         $this->body    = 'Your order is getting started.';
         $this->status  = 'order_preparing';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Notifications/StorefrontOrderReadyForPickup.php b/server/src/Notifications/StorefrontOrderReadyForPickup.php
index 00e06543..7cd61c1c 100644
--- a/server/src/Notifications/StorefrontOrderReadyForPickup.php
+++ b/server/src/Notifications/StorefrontOrderReadyForPickup.php
@@ -3,55 +3,9 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Storefront\Support\PushNotification;
-use Fleetbase\Storefront\Support\Storefront;
-use Illuminate\Bus\Queueable;
-use Illuminate\Notifications\Messages\MailMessage;
-use Illuminate\Notifications\Notification;
-use NotificationChannels\Apn\ApnChannel;
-use NotificationChannels\Fcm\FcmChannel;
 
-class StorefrontOrderReadyForPickup extends Notification
+class StorefrontOrderReadyForPickup extends StorefrontOrderNotification
 {
-    use Queueable;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Order $order;
-
-    /**
-     * The order instance this notification is for.
-     */
-    public Store|Network $storefront;
-
-    /**
-     * The time the notification was sent.
-     */
-    public string $sentAt;
-
-    /**
-     * The ID of the notification.
-     */
-    public string $notificationId;
-
-    /**
-     * The notification subject.
-     */
-    public string $subject;
-
-    /**
-     * The notification body.
-     */
-    public string $body;
-
-    /**
-     * The notification order status.
-     */
-    public string $status;
-
     /**
      * Create a new notification instance.
      *
@@ -59,104 +13,10 @@ class StorefrontOrderReadyForPickup extends Notification
      */
     public function __construct(Order $order)
     {
-        $this->order          = $order;
-        $this->storefront     = Storefront::findAbout($order->getMeta('storefront_id'));
-        $this->sentAt         = now()->toDateTimeString();
-        $this->notificationId = uniqid('notification_');
+        parent::__construct($order);
 
         $this->subject = 'Your order from ' . $this->storefront->name . ' is ready for pickup!';
         $this->body    = 'You can proceed to pickup your order.';
         $this->status  = 'order_ready';
     }
-
-    /**
-     * Get the notification's delivery channels.
-     */
-    public function via($notifiable): array
-    {
-        $channels = ['mail', 'database'];
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'apn')) {
-            $channels[] = ApnChannel::class;
-        }
-
-        if (Storefront::hasNotificationChannelConfigured($this->storefront, 'fcm')) {
-            $channels[] = FcmChannel::class;
-        }
-
-        return $channels;
-    }
-
-    /**
-     * Get the mail representation of the notification.
-     *
-     * @return MailMessage
-     */
-    public function toMail($notifiable)
-    {
-        $message = (new MailMessage())
-            ->subject($this->subject)
-            ->line($this->body);
-
-        // $message->action('View Details', Utils::consoleUrl('', ['shift' => 'fleet-ops/orders/view/' . $this->order->public_id]));
-
-        return $message;
-    }
-
-    /**
-     * Get the firebase cloud message representation of the notification.
-     *
-     * @return \NotificationChannels\Fcm\FcmMessage
-     */
-    public function toFcm($notifiable)
-    {
-        return PushNotification::createFcmMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the apns message representation of the notification.
-     *
-     * @return \NotificationChannels\Apn\ApnMessage
-     */
-    public function toApn($notifiable)
-    {
-        return PushNotification::createApnMessage(
-            $this->order,
-            $this->subject,
-            $this->body,
-            $this->status,
-            $notifiable
-        );
-    }
-
-    /**
-     * Get the array representation of the notification.
-     */
-    public function toArray($notifiable): array
-    {
-        $this->order->loadMissing(['customer', 'company']);
-        $customer = $this->order->customer;
-        $company  = $this->order->company;
-
-        return [
-            'notifiable'      => $notifiable->public_id,
-            'notification_id' => $this->notificationId,
-            'sent_at'         => $this->sentAt,
-            'subject'         => $this->subject,
-            'message'         => $this->status,
-            'storefront'      => $this->storefront->name,
-            'storefront_id'   => $this->storefront->public_id,
-            'id'              => $customer->public_id,
-            'email'           => $customer->email,
-            'phone'           => $customer->phone,
-            'companyId'       => $company->public_id,
-            'company'         => $company->name,
-        ];
-    }
 }
diff --git a/server/src/Push/ApnClientFactory.php b/server/src/Push/ApnClientFactory.php
new file mode 100644
index 00000000..a1b1b5f2
--- /dev/null
+++ b/server/src/Push/ApnClientFactory.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Pushok\AuthProvider\Token;
+use Pushok\Client;
+
+/**
+ * Builds APNs (pushok) clients for a storefront APN channel.
+ */
+class ApnClientFactory
+{
+    public const PRODUCTION = 'production';
+    public const SANDBOX    = 'sandbox';
+
+    public function make(NotificationChannel $channel, string $environment): Client
+    {
+        $config = static::credentialsFromChannel($channel);
+
+        return new Client(Token::create($config), $environment === self::PRODUCTION);
+    }
+
+    /**
+     * The APNs environments to try, in order, for a channel.
+     *
+     * An explicit `environment` of production or sandbox is strict. Otherwise the legacy
+     * `production` flag only decides which environment is tried first: a token rejected
+     * with BadDeviceToken is retried against the other environment, so development and
+     * TestFlight/App Store builds of the same app can share one channel.
+     *
+     * @return string[]
+     */
+    public static function environments(NotificationChannel $channel, ?string $deviceEnvironment = null): array
+    {
+        if (in_array($deviceEnvironment, [self::PRODUCTION, self::SANDBOX], true)) {
+            return [$deviceEnvironment];
+        }
+
+        $config      = (array) $channel->config;
+        $environment = $config['environment'] ?? null;
+
+        if ($environment === self::PRODUCTION || $environment === self::SANDBOX) {
+            return [$environment];
+        }
+
+        if ($environment === null && array_key_exists('production', $config)) {
+            $production = filter_var($config['production'], FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+            if ($production === false) {
+                return [self::SANDBOX, self::PRODUCTION];
+            }
+        }
+
+        return [self::PRODUCTION, self::SANDBOX];
+    }
+
+    /**
+     * @throws PushConfigurationException
+     */
+    public static function credentialsFromChannel(NotificationChannel $channel): array
+    {
+        $config = (array) $channel->config;
+
+        foreach (['key_id', 'team_id', 'app_bundle_id'] as $required) {
+            if (empty($config[$required])) {
+                throw new PushConfigurationException('APN channel "' . $channel->name . '" is missing "' . $required . '".');
+            }
+        }
+
+        if (empty($config['private_key_content']) && empty($config['private_key_path'])) {
+            throw new PushConfigurationException('APN channel "' . $channel->name . '" is missing its .p8 private key.');
+        }
+
+        if (!empty($config['private_key_content'])) {
+            $config['private_key_content'] = str_replace('\\n', "\n", trim($config['private_key_content']));
+        }
+
+        return [
+            'key_id'              => trim($config['key_id']),
+            'team_id'             => trim($config['team_id']),
+            'app_bundle_id'       => trim($config['app_bundle_id']),
+            'private_key_content' => $config['private_key_content'] ?? null,
+            'private_key_path'    => $config['private_key_path'] ?? null,
+            'private_key_secret'  => $config['private_key_secret'] ?? null,
+        ];
+    }
+}
diff --git a/server/src/Push/Contracts/SendsPushNotification.php b/server/src/Push/Contracts/SendsPushNotification.php
new file mode 100644
index 00000000..432a8297
--- /dev/null
+++ b/server/src/Push/Contracts/SendsPushNotification.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace Fleetbase\Storefront\Push\Contracts;
+
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Push\PushMessage;
+
+/**
+ * Implemented by notifications delivered through the StorefrontPushChannel.
+ */
+interface SendsPushNotification
+{
+    /**
+     * Build the push payload for the notifiable, or null to skip push delivery.
+     */
+    public function toPush($notifiable): ?PushMessage;
+
+    /**
+     * The storefronts whose push credentials may be used, most preferred first.
+     *
+     * For a marketplace order this is the network (whose app the customer uses) followed
+     * by the store, so network apps and standalone store apps both resolve correctly.
+     *
+     * @return array<Store|Network>
+     */
+    public function pushStorefronts(): array;
+}
diff --git a/server/src/Push/FirebaseMessagingFactory.php b/server/src/Push/FirebaseMessagingFactory.php
new file mode 100644
index 00000000..99bcf42a
--- /dev/null
+++ b/server/src/Push/FirebaseMessagingFactory.php
@@ -0,0 +1,87 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Kreait\Firebase\Contract\Messaging;
+use Kreait\Firebase\Factory;
+
+/**
+ * Builds an isolated Firebase Messaging client for a storefront FCM channel.
+ *
+ * The channel's service account JSON is passed straight to the Firebase SDK. The
+ * application-wide `firebase.projects.*` config is never read or mutated, so a
+ * storefront channel works whether or not the instance has its own Firebase project.
+ */
+class FirebaseMessagingFactory
+{
+    /**
+     * @var array<string, Messaging>
+     */
+    protected static array $clients = [];
+
+    public function make(NotificationChannel $channel): Messaging
+    {
+        $serviceAccount = static::serviceAccountFromChannel($channel);
+        $cacheKey       = ($channel->uuid ?? $channel->app_key) . ':' . md5(json_encode($serviceAccount));
+
+        if (isset(static::$clients[$cacheKey])) {
+            return static::$clients[$cacheKey];
+        }
+
+        return static::$clients[$cacheKey] = $this->createMessaging($serviceAccount);
+    }
+
+    protected function createMessaging(array $serviceAccount): Messaging
+    {
+        return (new Factory())
+            ->withServiceAccount($serviceAccount)
+            ->createMessaging();
+    }
+
+    /**
+     * Decode and normalize the service account stored on the channel.
+     *
+     * Accepts the JSON string pasted in the console, an already decoded array/object, and
+     * repairs private keys whose newlines were escaped (`\\n`) during copy/paste.
+     *
+     * @throws PushConfigurationException
+     */
+    public static function serviceAccountFromChannel(NotificationChannel $channel): array
+    {
+        $config      = (array) $channel->config;
+        $credentials = $config['firebase_credentials_json'] ?? $config['credentials'] ?? null;
+
+        if (is_object($credentials)) {
+            $credentials = json_decode(json_encode($credentials), true);
+        }
+
+        if (is_string($credentials)) {
+            $decoded = json_decode(trim($credentials), true);
+            if (!is_array($decoded)) {
+                throw new PushConfigurationException('FCM channel "' . $channel->name . '" has invalid Firebase service account JSON.');
+            }
+            $credentials = $decoded;
+        }
+
+        if (!is_array($credentials)) {
+            throw new PushConfigurationException('FCM channel "' . $channel->name . '" is missing its Firebase service account JSON.');
+        }
+
+        foreach (['project_id', 'client_email', 'private_key'] as $required) {
+            if (empty($credentials[$required])) {
+                throw new PushConfigurationException('FCM channel "' . $channel->name . '" service account is missing "' . $required . '".');
+            }
+        }
+
+        $credentials['private_key'] = str_replace('\\n', "\n", $credentials['private_key']);
+        $credentials['type'] ??= 'service_account';
+
+        return $credentials;
+    }
+
+    public static function flush(): void
+    {
+        static::$clients = [];
+    }
+}
diff --git a/server/src/Push/PushConfigurationException.php b/server/src/Push/PushConfigurationException.php
new file mode 100644
index 00000000..690febf2
--- /dev/null
+++ b/server/src/Push/PushConfigurationException.php
@@ -0,0 +1,7 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+class PushConfigurationException extends \RuntimeException
+{
+}
diff --git a/server/src/Push/PushCredentialResolver.php b/server/src/Push/PushCredentialResolver.php
new file mode 100644
index 00000000..4bacd4e0
--- /dev/null
+++ b/server/src/Push/PushCredentialResolver.php
@@ -0,0 +1,82 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Support\Storefront;
+use Illuminate\Support\Collection;
+
+/**
+ * Resolves which storefront notification channels (push credentials) to use.
+ */
+class PushCredentialResolver
+{
+    /**
+     * Storefronts an order's push notifications may be sent through, most preferred first.
+     *
+     * Network (marketplace) orders are placed from the network's app, so the network's
+     * channels are preferred over the individual store's.
+     *
+     * @return array<Store|Network>
+     */
+    public static function storefrontsForOrder(Order $order): array
+    {
+        $storefronts = [];
+
+        foreach (['storefront_network_id', 'storefront_id'] as $metaKey) {
+            $id = $order->getMeta($metaKey);
+            if (!$id) {
+                continue;
+            }
+
+            $storefront = Storefront::findAbout($id);
+            if ($storefront && !collect($storefronts)->contains(fn ($existing) => $existing->uuid === $storefront->uuid)) {
+                $storefronts[] = $storefront;
+            }
+        }
+
+        return $storefronts;
+    }
+
+    /**
+     * Candidate channels for a scheme, in the order they should be tried.
+     *
+     * Channels owned by the storefront app the device registered from come first, then
+     * channels owned by each storefront in preference order (oldest first within a
+     * storefront, matching the historical behavior of using the first configured channel).
+     *
+     * @param array<Store|Network> $storefronts
+     *
+     * @return Collection<int, NotificationChannel>
+     */
+    public function channels(string $scheme, array $storefronts, ?string $appIdentifier = null): Collection
+    {
+        $ownerUuids = collect($storefronts)->pluck('uuid')->filter()->values();
+        if ($ownerUuids->isEmpty()) {
+            return collect();
+        }
+
+        $channels = NotificationChannel::query()
+            ->where('scheme', $scheme)
+            ->where(function ($query) use ($ownerUuids, $appIdentifier) {
+                $query->whereIn('owner_uuid', $ownerUuids->all());
+                if ($appIdentifier) {
+                    $query->orWhere('owner_uuid', $appIdentifier);
+                }
+            })
+            ->orderBy('created_at')
+            ->get();
+
+        return $channels
+            ->sortBy(function (NotificationChannel $channel) use ($ownerUuids, $appIdentifier) {
+                $appRank   = $appIdentifier && $channel->owner_uuid === $appIdentifier ? 0 : 1;
+                $ownerRank = $ownerUuids->search($channel->owner_uuid);
+
+                return sprintf('%d-%03d', $appRank, $ownerRank === false ? 999 : $ownerRank);
+            })
+            ->values();
+    }
+}
diff --git a/server/src/Push/PushMessage.php b/server/src/Push/PushMessage.php
new file mode 100644
index 00000000..5853cc5b
--- /dev/null
+++ b/server/src/Push/PushMessage.php
@@ -0,0 +1,193 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+/**
+ * Provider-agnostic push notification payload.
+ *
+ * Notifications build a PushMessage and the StorefrontPushChannel renders it
+ * into the FCM (Android) or APNs (iOS) wire format for each device.
+ */
+class PushMessage
+{
+    public string $title;
+    public string $body;
+    public array $data             = [];
+    public ?int $badge             = 1;
+    public ?string $sound          = 'default';
+    public ?string $image          = null;
+    public ?string $category       = null;
+    public ?string $collapseKey    = null;
+    public ?string $analyticsLabel = null;
+
+    public function __construct(string $title, string $body, array $data = [])
+    {
+        $this->title = $title;
+        $this->body  = $body;
+        $this->data  = $data;
+    }
+
+    public static function create(string $title, string $body, array $data = []): self
+    {
+        return new static($title, $body, $data);
+    }
+
+    public function data(array $data): self
+    {
+        $this->data = array_merge($this->data, $data);
+
+        return $this;
+    }
+
+    public function badge(?int $badge): self
+    {
+        $this->badge = $badge;
+
+        return $this;
+    }
+
+    public function sound(?string $sound): self
+    {
+        $this->sound = $sound;
+
+        return $this;
+    }
+
+    public function image(?string $image): self
+    {
+        $this->image = $image;
+
+        return $this;
+    }
+
+    public function category(?string $category): self
+    {
+        $this->category = $category;
+
+        return $this;
+    }
+
+    public function collapseKey(?string $collapseKey): self
+    {
+        $this->collapseKey = $collapseKey;
+
+        return $this;
+    }
+
+    public function analyticsLabel(?string $analyticsLabel): self
+    {
+        $this->analyticsLabel = $analyticsLabel;
+
+        return $this;
+    }
+
+    /**
+     * FCM requires every data value to be a string.
+     */
+    public function stringData(): array
+    {
+        $data = [];
+        foreach ($this->data as $key => $value) {
+            if ($value === null) {
+                continue;
+            }
+
+            $data[(string) $key] = is_scalar($value) ? (is_bool($value) ? ($value ? 'true' : 'false') : (string) $value) : json_encode($value);
+        }
+
+        return $data;
+    }
+
+    /**
+     * Render the FCM HTTP v1 message body (without a target).
+     */
+    public function toFcmArray(array $options = []): array
+    {
+        $androidChannelId = $options['android_channel_id'] ?? null;
+        $color            = $options['android_color'] ?? '#4391EA';
+
+        $notification = array_filter([
+            'title' => $this->title,
+            'body'  => $this->body,
+            'image' => $this->image,
+        ], fn ($value) => $value !== null);
+
+        $androidNotification = array_filter([
+            'channel_id'   => $androidChannelId,
+            'sound'        => $this->sound,
+            'color'        => $color,
+            'click_action' => $this->category,
+            'tag'          => $this->collapseKey,
+        ], fn ($value) => $value !== null && $value !== '');
+
+        $aps = array_filter([
+            'sound'    => $this->sound,
+            'badge'    => $this->badge,
+            'category' => $this->category,
+        ], fn ($value) => $value !== null);
+
+        $message = [
+            'notification' => $notification,
+            'data'         => $this->stringData(),
+            'android'      => array_filter([
+                'priority'     => 'high',
+                'collapse_key' => $this->collapseKey,
+                'notification' => $androidNotification,
+            ], fn ($value) => $value !== null && $value !== []),
+            'apns' => [
+                'headers' => ['apns-priority' => '10', 'apns-push-type' => 'alert'],
+                'payload' => ['aps' => $aps],
+            ],
+        ];
+
+        if ($this->analyticsLabel) {
+            $message['fcm_options'] = ['analytics_label' => $this->analyticsLabel];
+        }
+
+        if (empty($message['data'])) {
+            unset($message['data']);
+        }
+
+        return $message;
+    }
+
+    /**
+     * Render the APNs payload for pushok.
+     */
+    public function toApnPayload(): \Pushok\Payload
+    {
+        $alert = \Pushok\Payload\Alert::create()
+            ->setTitle($this->title)
+            ->setBody($this->body);
+
+        $payload = \Pushok\Payload::create()
+            ->setAlert($alert)
+            ->setPushType('alert');
+
+        if ($this->sound !== null) {
+            $payload->setSound($this->sound);
+        }
+
+        if ($this->badge !== null) {
+            $payload->setBadge($this->badge);
+        }
+
+        if ($this->category !== null) {
+            $payload->setCategory($this->category);
+        }
+
+        if ($this->image !== null) {
+            $payload->setMutableContent(true);
+        }
+
+        foreach ($this->data as $key => $value) {
+            if ($value === null || $key === 'aps') {
+                continue;
+            }
+
+            $payload->setCustomValue((string) $key, $value);
+        }
+
+        return $payload;
+    }
+}
diff --git a/server/src/Push/PushOutcome.php b/server/src/Push/PushOutcome.php
new file mode 100644
index 00000000..b61a0023
--- /dev/null
+++ b/server/src/Push/PushOutcome.php
@@ -0,0 +1,58 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+/**
+ * Normalized per-token delivery outcome shared by the FCM and APNs transports.
+ */
+final class PushOutcome
+{
+    /** Accepted by the provider. */
+    public const SENT = 'sent';
+
+    /** Token is no longer valid (app uninstalled, token rotated, garbage token): prune it. */
+    public const DEAD = 'dead';
+
+    /** Token belongs to a different app/project than the channel (SenderId mismatch, DeviceTokenNotForTopic): try another channel. */
+    public const WRONG_APP = 'wrong_app';
+
+    /** APNs token was issued for the other environment (BadDeviceToken): try the other environment. */
+    public const WRONG_ENVIRONMENT = 'wrong_environment';
+
+    /** Anything else (credentials, quota, provider outage): logged, token kept. */
+    public const ERROR = 'error';
+
+    public function __construct(public string $status, public ?string $reason = null)
+    {
+    }
+
+    public static function sent(): self
+    {
+        return new self(self::SENT);
+    }
+
+    public static function dead(?string $reason = null): self
+    {
+        return new self(self::DEAD, $reason);
+    }
+
+    public static function wrongApp(?string $reason = null): self
+    {
+        return new self(self::WRONG_APP, $reason);
+    }
+
+    public static function wrongEnvironment(?string $reason = null): self
+    {
+        return new self(self::WRONG_ENVIRONMENT, $reason);
+    }
+
+    public static function error(?string $reason = null): self
+    {
+        return new self(self::ERROR, $reason);
+    }
+
+    public function is(string $status): bool
+    {
+        return $this->status === $status;
+    }
+}
diff --git a/server/src/Push/StorefrontPushChannel.php b/server/src/Push/StorefrontPushChannel.php
new file mode 100644
index 00000000..cf0d2a72
--- /dev/null
+++ b/server/src/Push/StorefrontPushChannel.php
@@ -0,0 +1,236 @@
+<?php
+
+namespace Fleetbase\Storefront\Push;
+
+use Fleetbase\Models\UserDevice;
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
+use Fleetbase\Storefront\Push\Transports\ApnTransport;
+use Fleetbase\Storefront\Push\Transports\FcmTransport;
+use Illuminate\Notifications\Notification;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Delivers storefront notifications to a notifiable's registered iOS and Android devices.
+ *
+ * For each platform the channel walks the candidate storefront channels (the app the device
+ * registered from, then network, then store) and, for iOS, the candidate APNs environments. Tokens that the
+ * provider reports as belonging to another app or environment are retried against the next
+ * candidate, dead tokens are pruned, and every failure is logged. Errors never propagate, so
+ * a push failure cannot block the notification's other channels.
+ */
+class StorefrontPushChannel
+{
+    public function __construct(
+        protected PushCredentialResolver $resolver,
+        protected FcmTransport $fcm,
+        protected ApnTransport $apn,
+    ) {
+    }
+
+    /**
+     * @return array<string, PushOutcome> final outcome keyed by device token
+     */
+    public function send($notifiable, Notification $notification): array
+    {
+        if (!$notification instanceof SendsPushNotification) {
+            return [];
+        }
+
+        try {
+            $message = $notification->toPush($notifiable);
+            $devices = static::devicesFor($notifiable);
+            if (!$message || $devices->isEmpty()) {
+                return [];
+            }
+
+            $storefronts = $notification->pushStorefronts();
+        } catch (\Throwable $e) {
+            static::log('error', 'Unable to prepare push notification.', ['notification' => get_class($notification), 'error' => $e->getMessage()]);
+
+            return [];
+        }
+
+        $outcomes = [];
+        foreach ($devices->groupBy(fn ($device) => static::normalizePlatform($device->platform)) as $platform => $platformDevices) {
+            foreach ($platformDevices->groupBy(fn ($device) => $device->getAttribute('app_identifier') ?? '') as $appIdentifier => $group) {
+                $outcomes += match ($platform) {
+                    'android' => $this->sendToAndroid($group, $message, $storefronts, $appIdentifier ?: null),
+                    'ios'     => $this->sendToIos($group, $message, $storefronts, $appIdentifier ?: null),
+                    default   => [],
+                };
+            }
+        }
+
+        return $outcomes;
+    }
+
+    protected function sendToAndroid(Collection $devices, PushMessage $message, array $storefronts, ?string $appIdentifier): array
+    {
+        $channels = $this->resolver->channels('fcm', $storefronts, $appIdentifier);
+
+        return $this->deliver($devices, $channels, [null], function (NotificationChannel $channel, ?string $environment, array $tokens) use ($message) {
+            return $this->fcm->send($channel, $message, $tokens);
+        });
+    }
+
+    protected function sendToIos(Collection $devices, PushMessage $message, array $storefronts, ?string $appIdentifier): array
+    {
+        $channels = $this->resolver->channels('apn', $storefronts, $appIdentifier);
+        $outcomes = [];
+
+        // Devices that registered their APNs environment are sent to that environment only.
+        foreach ($devices->groupBy(fn ($device) => $device->getAttribute('environment') ?? '') as $deviceEnvironment => $group) {
+            $outcomes += $this->deliver(
+                $group,
+                $channels,
+                fn (NotificationChannel $channel)                                      => ApnClientFactory::environments($channel, $deviceEnvironment ?: null),
+                fn (NotificationChannel $channel, ?string $environment, array $tokens) => $this->apn->send($channel, $environment, $message, $tokens)
+            );
+        }
+
+        return $outcomes;
+    }
+
+    /**
+     * @param array|callable $environments list of environments, or a resolver taking the channel
+     */
+    protected function deliver(Collection $devices, Collection $channels, array|callable $environments, callable $send): array
+    {
+        $devicesByToken = $devices->keyBy('token');
+        $pending        = $devicesByToken->keys()->all();
+        $outcomes       = [];
+
+        if ($channels->isEmpty()) {
+            static::log('warning', 'No push notification channel is configured for the storefront; skipping devices.', ['devices' => count($pending)]);
+
+            return [];
+        }
+
+        foreach ($channels as $channel) {
+            $channelEnvironments = is_callable($environments) ? $environments($channel) : $environments;
+            $retryOtherApp       = [];
+
+            foreach ($channelEnvironments as $environment) {
+                if (empty($pending)) {
+                    break;
+                }
+
+                try {
+                    $results = $send($channel, $environment, $pending);
+                } catch (\Throwable $e) {
+                    static::log('error', 'Push notification provider request failed.', [
+                        'channel'     => $channel->app_key,
+                        'scheme'      => $channel->scheme,
+                        'environment' => $environment,
+                        'error'       => $e->getMessage(),
+                    ]);
+                    foreach ($pending as $token) {
+                        $outcomes[$token] = PushOutcome::error($e->getMessage());
+                    }
+                    // Credentials for this channel are unusable; the next channel may still work.
+                    $pending = array_values(array_unique(array_merge($pending, $retryOtherApp)));
+                    continue 2;
+                }
+
+                $retryEnvironment = [];
+                foreach ($pending as $token) {
+                    $outcome          = $results[$token] ?? PushOutcome::error('No response from provider.');
+                    $outcomes[$token] = $outcome;
+
+                    if ($outcome->is(PushOutcome::WRONG_ENVIRONMENT)) {
+                        $retryEnvironment[] = $token;
+                    } elseif ($outcome->is(PushOutcome::WRONG_APP)) {
+                        $retryOtherApp[] = $token;
+                    }
+                }
+
+                $pending = $retryEnvironment;
+            }
+
+            // Still failing with BadDeviceToken in every environment: the token is invalid.
+            foreach ($pending as $token) {
+                $outcomes[$token] = PushOutcome::dead($outcomes[$token]->reason ?? 'BadDeviceToken');
+            }
+
+            $pending = $retryOtherApp;
+            if (empty($pending)) {
+                break;
+            }
+        }
+
+        foreach ($outcomes as $token => $outcome) {
+            $device = $devicesByToken->get($token);
+
+            if ($outcome->is(PushOutcome::DEAD)) {
+                static::pruneDevice($device, $outcome->reason);
+            } elseif (!$outcome->is(PushOutcome::SENT)) {
+                static::log('warning', 'Push notification was not delivered to device.', [
+                    'device'   => $device?->public_id,
+                    'platform' => $device?->platform,
+                    'status'   => $outcome->status,
+                    'reason'   => $outcome->reason,
+                ]);
+            }
+        }
+
+        return $outcomes;
+    }
+
+    /**
+     * Active devices registered for the notifiable.
+     */
+    public static function devicesFor($notifiable): Collection
+    {
+        if (is_object($notifiable) && method_exists($notifiable, 'routeNotificationForStorefrontPush')) {
+            $devices = collect($notifiable->routeNotificationForStorefrontPush());
+        } elseif (is_object($notifiable) && (method_exists($notifiable, 'devices') || isset($notifiable->devices))) {
+            $devices = collect($notifiable->devices);
+        } else {
+            return collect();
+        }
+
+        return $devices
+            ->filter(fn ($device) => is_object($device) && !empty($device->token) && !in_array($device->status, ['invalid', 'inactive'], true))
+            ->unique('token')
+            ->values();
+    }
+
+    public static function normalizePlatform(?string $platform): ?string
+    {
+        $platform = strtolower(trim((string) $platform));
+
+        return match ($platform) {
+            'ios', 'iphone', 'ipad', 'ipados', 'apple', 'apn', 'apns' => 'ios',
+            'android', 'fcm'                                          => 'android',
+            default                                                   => null,
+        };
+    }
+
+    protected static function pruneDevice($device, ?string $reason): void
+    {
+        if (!$device instanceof UserDevice) {
+            return;
+        }
+
+        static::log('info', 'Pruning push device with a dead token.', ['device' => $device->public_id, 'platform' => $device->platform, 'reason' => $reason]);
+
+        try {
+            $device->status = 'invalid';
+            $device->save();
+            $device->delete();
+        } catch (\Throwable $e) {
+            static::log('error', 'Unable to prune push device.', ['device' => $device->public_id, 'error' => $e->getMessage()]);
+        }
+    }
+
+    protected static function log(string $level, string $message, array $context = []): void
+    {
+        try {
+            Log::{$level}('[Storefront Push] ' . $message, $context);
+        } catch (\Throwable $e) {
+            // Logging must never break delivery.
+        }
+    }
+}
diff --git a/server/src/Push/Transports/ApnTransport.php b/server/src/Push/Transports/ApnTransport.php
new file mode 100644
index 00000000..deb144e3
--- /dev/null
+++ b/server/src/Push/Transports/ApnTransport.php
@@ -0,0 +1,68 @@
+<?php
+
+namespace Fleetbase\Storefront\Push\Transports;
+
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Push\ApnClientFactory;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\PushOutcome;
+use Pushok\Notification;
+use Pushok\Response;
+
+/**
+ * Sends push messages to iOS devices through APNs (token based .p8 auth).
+ */
+class ApnTransport
+{
+    public function __construct(protected ApnClientFactory $factory)
+    {
+    }
+
+    /**
+     * @param string[] $tokens
+     *
+     * @return array<string, PushOutcome> keyed by token
+     */
+    public function send(NotificationChannel $channel, string $environment, PushMessage $message, array $tokens): array
+    {
+        if (empty($tokens)) {
+            return [];
+        }
+
+        $client  = $this->factory->make($channel, $environment);
+        $payload = $message->toApnPayload();
+
+        foreach ($tokens as $token) {
+            $notification = new Notification($payload, $token);
+            $notification->setHighPriority();
+            if ($message->collapseKey) {
+                $notification->setCollapseId(substr($message->collapseKey, 0, 64));
+            }
+            $client->addNotification($notification);
+        }
+
+        $outcomes = [];
+        foreach ($client->push() as $response) {
+            $outcomes[$response->getDeviceToken()] = static::outcomeFor($response);
+        }
+
+        return $outcomes;
+    }
+
+    public static function outcomeFor(Response $response): PushOutcome
+    {
+        $status = $response->getStatusCode();
+        if ($status === 200) {
+            return PushOutcome::sent();
+        }
+
+        $reason = $response->getErrorReason();
+
+        return match (true) {
+            $status === 410, $reason === 'Unregistered', $reason === 'ExpiredToken' => PushOutcome::dead($reason),
+            $reason === 'BadDeviceToken'                                            => PushOutcome::wrongEnvironment($reason),
+            $reason === 'DeviceTokenNotForTopic', $reason === 'TopicDisallowed'     => PushOutcome::wrongApp($reason),
+            default                                                                 => PushOutcome::error($status . ' ' . $reason),
+        };
+    }
+}
diff --git a/server/src/Push/Transports/FcmTransport.php b/server/src/Push/Transports/FcmTransport.php
new file mode 100644
index 00000000..825cab70
--- /dev/null
+++ b/server/src/Push/Transports/FcmTransport.php
@@ -0,0 +1,76 @@
+<?php
+
+namespace Fleetbase\Storefront\Push\Transports;
+
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Push\FirebaseMessagingFactory;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\PushOutcome;
+use Kreait\Firebase\Exception\Messaging\AuthenticationError;
+use Kreait\Firebase\Exception\Messaging\InvalidArgument;
+use Kreait\Firebase\Exception\Messaging\NotFound;
+use Kreait\Firebase\Messaging\CloudMessage;
+use Kreait\Firebase\Messaging\SendReport;
+
+/**
+ * Sends push messages to Android devices through FCM HTTP v1.
+ */
+class FcmTransport
+{
+    public function __construct(protected FirebaseMessagingFactory $factory)
+    {
+    }
+
+    /**
+     * @param string[] $tokens
+     *
+     * @return array<string, PushOutcome> keyed by token
+     */
+    public function send(NotificationChannel $channel, PushMessage $message, array $tokens): array
+    {
+        if (empty($tokens)) {
+            return [];
+        }
+
+        $config  = (array) $channel->config;
+        $payload = $message->toFcmArray([
+            'android_channel_id' => $config['android_channel_id'] ?? config('storefront.push.android_channel_id'),
+            'android_color'      => $config['android_color'] ?? null,
+        ]);
+
+        $report   = $this->factory->make($channel)->sendMulticast(CloudMessage::fromArray($payload), array_values($tokens));
+        $outcomes = [];
+
+        foreach ($report->getItems() as $item) {
+            $outcomes[$item->target()->value()] = static::outcomeFor($item);
+        }
+
+        return $outcomes;
+    }
+
+    public static function outcomeFor(SendReport $report): PushOutcome
+    {
+        if ($report->isSuccess()) {
+            return PushOutcome::sent();
+        }
+
+        $error  = $report->error();
+        $reason = $error?->getMessage();
+
+        // 403 SENDER_ID_MISMATCH: token was issued for a different Firebase project.
+        if ($error instanceof AuthenticationError && stripos((string) $reason, 'mismatch') !== false) {
+            return PushOutcome::wrongApp($reason);
+        }
+
+        // 404 UNREGISTERED or 400 INVALID_ARGUMENT for the registration token.
+        if ($error instanceof NotFound || $report->messageWasSentToUnknownToken() || $report->messageTargetWasInvalid()) {
+            return PushOutcome::dead($reason);
+        }
+
+        if ($error instanceof InvalidArgument && stripos((string) $reason, 'registration') !== false) {
+            return PushOutcome::dead($reason);
+        }
+
+        return PushOutcome::error($reason);
+    }
+}
diff --git a/server/src/Support/PushNotification.php b/server/src/Support/PushNotification.php
deleted file mode 100644
index 60f07f1c..00000000
--- a/server/src/Support/PushNotification.php
+++ /dev/null
@@ -1,152 +0,0 @@
-<?php
-
-namespace Fleetbase\Storefront\Support;
-
-use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\NotificationChannel;
-use Fleetbase\Storefront\Models\Store;
-use Fleetbase\Support\Utils;
-use Illuminate\Container\Container;
-use Kreait\Laravel\Firebase\FirebaseProjectManager;
-use NotificationChannels\Apn\ApnMessage;
-use NotificationChannels\Fcm\FcmMessage;
-use NotificationChannels\Fcm\Resources\Notification as FcmNotification;
-use Pushok\AuthProvider\Token as PuskOkToken;
-use Pushok\Client as PushOkClient;
-
-class PushNotification
-{
-    public static function createApnMessage(Order $order, string $title, string $body, string $status, $notifiable = null): ?ApnMessage
-    {
-        $storefront = static::getStorefrontFromOrder($order);
-        $client     = static::getApnClient($storefront, $order);
-        if (!$client) {
-            // create apn message anyway
-            return new ApnMessage($title, $body);
-        }
-
-        return ApnMessage::create()
-            ->badge(1)
-            ->title($title)
-            ->body($body)
-            ->custom('type', $status)
-            ->custom('order', $order->uuid)
-            ->custom('id', $order->public_id)
-            ->action('view_order', ['id' => $order->public_id])
-            ->via($client);
-    }
-
-    public static function createFcmMessage(Order $order, string $title, string $body, string $status, $notifiable = null): ?FcmMessage
-    {
-        $storefront          = static::getStorefrontFromOrder($order);
-        $notificationChannel = static::getNotificationChannel('fcm', $storefront, $order);
-        if (!$notificationChannel) {
-            // create fcm message anyway
-            return new FcmMessage(
-                notification: new FcmNotification(
-                    title: $title,
-                    body: $body
-                )
-            );
-        }
-
-        // Configure FCM
-        static::configureFcm($notificationChannel);
-
-        // Get FCM Client using Notification Channel
-        $client = static::getFcmClient($notificationChannel);
-
-        // Create Notification
-        $notification = new FcmNotification(
-            title: $title,
-            body: $body
-        );
-
-        return (new FcmMessage(notification: $notification))
-            ->data(['order' => $order->uuid, 'id' => $order->public_id, 'type' => $status])
-            ->custom([
-                'android' => [
-                    'notification' => [
-                        'color' => '#4391EA',
-                        'sound' => 'default',
-                    ],
-                    'fcm_options' => [
-                        'analytics_label' => 'analytics',
-                    ],
-                ],
-                'apns' => [
-                    'payload' => [
-                        'aps' => [
-                            'sound' => 'default',
-                        ],
-                    ],
-                    'fcm_options' => [
-                        'analytics_label' => 'analytics',
-                    ],
-                ],
-            ])
-            ->usingClient($client);
-    }
-
-    protected static function getFcmClient(NotificationChannel $notificationChannel)
-    {
-        $container      = Container::getInstance();
-        $projectManager = new FirebaseProjectManager($container);
-
-        return $projectManager->project($notificationChannel->app_key)->messaging();
-    }
-
-    public static function configureFcm(NotificationChannel $notificationChannel)
-    {
-        // Convert the channel's config to an array.
-        $config = (array) $notificationChannel->config;
-
-        // Get the base firebase config.
-        $firebaseConfig = config('firebase.projects.app');
-
-        // Update the firebase config with values from the channel.
-        data_set($firebaseConfig, 'credentials.private_key', $config['firebase_credentials_json']);
-        data_set($firebaseConfig, 'database.url', $config['firebase_database_url']);
-
-        // Update the Laravel config for this project key.
-        config(['firebase.projects.' . $notificationChannel->app_key => $firebaseConfig]);
-
-        // Return the updated firebase config.
-        return $firebaseConfig;
-    }
-
-    public static function getNotificationChannel(string $scheme, Network|Store $storefront, ?Order $order = null): ?NotificationChannel
-    {
-        if ($order && $order->hasMeta('storefront_notification_channel')) {
-            return NotificationChannel::where([
-                'owner_uuid' => $storefront->uuid,
-                'app_key'    => $order->getMeta('storefront_notification_channel'),
-                'scheme'     => $scheme,
-            ])->first();
-        }
-
-        return NotificationChannel::where([
-            'owner_uuid' => $storefront->uuid,
-            'scheme'     => $scheme,
-        ])->first();
-    }
-
-    public static function getApnClient(Network|Store $storefront, ?Order $order = null): ?PushOkClient
-    {
-        $notificationChannel = static::getNotificationChannel('apn', $storefront, $order);
-        if (!$notificationChannel) {
-            return null;
-        }
-        $config              = (array) $notificationChannel->config;
-
-        $isProductionEnv = Utils::castBoolean(data_get($config, 'production', app()->isProduction()));
-
-        return new PushOkClient(PuskOkToken::create($config), $isProductionEnv);
-    }
-
-    public static function getStorefrontFromOrder(Order $order): Network|Store|null
-    {
-        return Storefront::findAbout($order->getMeta('storefront_id'));
-    }
-}
diff --git a/server/src/Support/Storefront.php b/server/src/Support/Storefront.php
index 6ef091ef..b3b40e8c 100644
--- a/server/src/Support/Storefront.php
+++ b/server/src/Support/Storefront.php
@@ -632,7 +632,8 @@ public static function autoAcceptOrder(Order $order)
         // Notify customer order was accepted
         try {
             $order->customer->notify(new StorefrontOrderAccepted($order));
-        } catch (\Exception $e) {
+        } catch (\Throwable $e) {
+            Log::error('[Storefront] was unable to notify the customer that their order was accepted.', ['order' => $order->public_id, 'error' => $e->getMessage()]);
         }
 
         return $order;
diff --git a/server/src/routes.php b/server/src/routes.php
index 52adcd83..f762f4b1 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -104,6 +104,7 @@ function ($router) {
                     $router->put('{id}', 'CustomerController@update');
                     $router->get('/', 'CustomerController@query');
                     $router->post('register-device', 'CustomerController@registerDevice');
+                    $router->post('unregister-device', 'CustomerController@unregisterDevice');
                     $router->get('places', 'CustomerController@places');
                     $router->get('orders', 'CustomerController@orders');
                     $router->get('{id}', 'CustomerController@find');
@@ -213,7 +214,12 @@ function ($router, $controller) {
                         $router->fleetbaseRoutes('product-addon-categories');
                         $router->fleetbaseRoutes('addon-categories');
                         $router->fleetbaseRoutes('gateways');
-                        $router->fleetbaseRoutes('notification-channels');
+                        $router->fleetbaseRoutes(
+                            'notification-channels',
+                            function ($router, $controller) {
+                                $router->post('{id}/test', $controller('testPush'));
+                            }
+                        );
                         $router->fleetbaseRoutes('reviews');
                         $router->fleetbaseRoutes('votes');
                         $router->fleetbaseRoutes('food-trucks');
diff --git a/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php b/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
new file mode 100644
index 00000000..0ca0a0a6
--- /dev/null
+++ b/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
@@ -0,0 +1,175 @@
+<?php
+
+use Fleetbase\Models\UserDevice;
+use Fleetbase\Storefront\Http\Controllers\v1\CustomerController;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Request;
+use Illuminate\Session\ArraySessionHandler;
+use Illuminate\Session\Store as SessionStore;
+
+function bootDeviceRegistrationCustomer(string $customerUuid, string $userUuid, string $secret): void
+{
+    $connection = Model::getConnectionResolver()->connection('mysql');
+    $schema     = $connection->getSchemaBuilder();
+
+    if (!$schema->hasTable('contacts')) {
+        $schema->create('contacts', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('user_uuid')->nullable();
+            $table->string('type')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    if (!$schema->hasTable('personal_access_tokens')) {
+        $schema->create('personal_access_tokens', function ($table) {
+            $table->increments('id');
+            $table->string('tokenable_type')->nullable();
+            $table->string('tokenable_id')->nullable();
+            $table->string('name');
+            $table->string('token', 64)->unique();
+            $table->text('abilities')->nullable();
+            $table->timestamp('last_used_at')->nullable();
+            $table->timestamp('expires_at')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    $connection->table('contacts')->insert([
+        'uuid'      => $customerUuid,
+        'public_id' => 'contact_' . substr($customerUuid, 0, 4),
+        'user_uuid' => $userUuid,
+        'type'      => 'customer',
+    ]);
+    $connection->table('personal_access_tokens')->insert([
+        'name'       => $customerUuid,
+        'token'      => hash('sha256', $secret),
+        'abilities'  => '["*"]',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+}
+
+function deviceRegistrationRequest(string $secret, array $input): Request
+{
+    $request = Request::create('/customers/register-device', 'POST', $input);
+    $request->setLaravelSession(new SessionStore('device-registration-test', new ArraySessionHandler(120)));
+    $request->headers->set('Customer-Token', $secret);
+    app()->instance('request', $request);
+
+    return $request;
+}
+
+beforeEach(function () {
+    $schema = Model::getConnectionResolver()->connection('mysql')->getSchemaBuilder();
+    foreach (['contacts', 'personal_access_tokens', 'user_devices'] as $table) {
+        $schema->dropIfExists($table);
+    }
+    $schema->create('user_devices', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('platform')->nullable();
+        $table->text('token')->nullable();
+        $table->string('status')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+
+    bootDeviceRegistrationCustomer('11111111-1111-4111-8111-111111111111', 'first_user', 'first-secret');
+    bootDeviceRegistrationCustomer('22222222-2222-4222-8222-222222222222', 'second_user', 'second-secret');
+});
+
+test('device registration validates the token and platform', function () {
+    $controller = new CustomerController();
+
+    $missingToken = $controller->registerDevice(deviceRegistrationRequest('first-secret', ['platform' => 'ios']));
+    $badPlatform  = $controller->registerDevice(deviceRegistrationRequest('first-secret', ['token' => 'abc', 'platform' => 'web']));
+
+    expect($missingToken->getData(true))->toBe(['error' => 'A device token is required.'])
+        ->and($badPlatform->getData(true))->toBe(['error' => 'Device platform must be either ios or android.'])
+        ->and(UserDevice::query()->count())->toBe(0);
+});
+
+test('device registration normalizes the platform and reassigns a token to the latest customer', function () {
+    $controller = new CustomerController();
+
+    $controller->registerDevice(deviceRegistrationRequest('first-secret', ['token' => ' shared-token ', 'os' => 'Android']));
+
+    expect(UserDevice::where('token', 'shared-token')->get(['user_uuid', 'platform', 'status'])->toArray())->toBe([
+        ['user_uuid' => 'first_user', 'platform' => 'android', 'status' => 'active'],
+    ]);
+
+    // The same install logs in as another customer.
+    $response = $controller->registerDevice(deviceRegistrationRequest('second-secret', ['token' => 'shared-token', 'platform' => 'android']));
+
+    expect($response->getData(true)['status'])->toBe('OK')
+        ->and(UserDevice::withTrashed()->where('token', 'shared-token')->count())->toBe(1)
+        ->and(UserDevice::where('token', 'shared-token')->value('user_uuid'))->toBe('second_user');
+});
+
+test('device registration restores pruned tokens and collapses legacy duplicates', function () {
+    $connection = Model::getConnectionResolver()->connection('mysql');
+    $connection->table('user_devices')->insert([
+        ['uuid' => 'd1', 'user_uuid' => 'first_user', 'platform' => 'ios', 'token' => 'ios-token', 'status' => 'invalid', 'deleted_at' => now(), 'updated_at' => now()->subDay()],
+        ['uuid' => 'd2', 'user_uuid' => 'first_user', 'platform' => 'iOS', 'token' => 'ios-token', 'status' => 'active', 'deleted_at' => null, 'updated_at' => now()->subDays(2)],
+    ]);
+
+    (new CustomerController())->registerDevice(deviceRegistrationRequest('first-secret', ['token' => 'ios-token', 'platform' => 'ios']));
+
+    expect(UserDevice::withTrashed()->where('token', 'ios-token')->get(['uuid', 'platform', 'status', 'deleted_at'])->toArray())->toBe([
+        ['uuid' => 'd1', 'platform' => 'ios', 'status' => 'active', 'deleted_at' => null],
+    ]);
+});
+
+test('device unregistration only removes the authenticated customer token', function () {
+    $connection = Model::getConnectionResolver()->connection('mysql');
+    $connection->table('user_devices')->insert([
+        ['uuid' => 'd1', 'user_uuid' => 'first_user', 'platform' => 'ios', 'token' => 'first-token', 'status' => 'active'],
+        ['uuid' => 'd2', 'user_uuid' => 'second_user', 'platform' => 'ios', 'token' => 'second-token', 'status' => 'active'],
+    ]);
+    $controller = new CustomerController();
+
+    $other = $controller->unregisterDevice(deviceRegistrationRequest('first-secret', ['token' => 'second-token']));
+    $own   = $controller->unregisterDevice(deviceRegistrationRequest('first-secret', ['token' => 'first-token']));
+
+    expect($other->getData(true))->toBe(['status' => 'OK', 'deleted' => 0])
+        ->and($own->getData(true))->toBe(['status' => 'OK', 'deleted' => 1])
+        ->and(UserDevice::pluck('token')->all())->toBe(['second-token']);
+});
+
+test('device unregistration requires an authenticated customer and a token', function () {
+    $controller = new CustomerController();
+
+    $unauthenticated = $controller->unregisterDevice(deviceRegistrationRequest('wrong-secret', ['token' => 'first-token']));
+    $missingToken    = $controller->unregisterDevice(deviceRegistrationRequest('first-secret', []));
+
+    expect($unauthenticated->getData(true))->toBe(['error' => 'Not authorized to unregister device for customer'])
+        ->and($missingToken->getData(true))->toBe(['error' => 'A device token is required.']);
+});
+
+test('device registration records the app and APNs environment when core-api supports it', function () {
+    $schema = Model::getConnectionResolver()->connection('mysql')->getSchemaBuilder();
+    $schema->table('user_devices', function ($table) {
+        $table->string('app_identifier')->nullable();
+        $table->string('environment')->nullable();
+        $table->timestamp('last_seen_at')->nullable();
+    });
+
+    $request = deviceRegistrationRequest('first-secret', ['token' => 'ios-token', 'platform' => 'ios', 'environment' => 'sandbox']);
+    $request->session()->put('storefront_network', 'network_uuid');
+    session(['storefront_store' => null, 'storefront_network' => 'network_uuid']);
+
+    (new CustomerController())->registerDevice($request);
+    (new CustomerController())->registerDevice(deviceRegistrationRequest('first-secret', ['token' => 'android-token', 'platform' => 'android', 'environment' => 'bogus']));
+
+    expect(UserDevice::where('token', 'ios-token')->first(['app_identifier', 'environment'])->toArray())->toBe(['app_identifier' => 'network_uuid', 'environment' => 'sandbox'])
+        ->and(UserDevice::where('token', 'ios-token')->value('last_seen_at'))->not->toBeNull()
+        ->and(UserDevice::where('token', 'android-token')->value('environment'))->toBeNull();
+});
diff --git a/server/tests/Unit/Http/Controllers/NotificationChannelTestPushTest.php b/server/tests/Unit/Http/Controllers/NotificationChannelTestPushTest.php
new file mode 100644
index 00000000..bc38b8f4
--- /dev/null
+++ b/server/tests/Unit/Http/Controllers/NotificationChannelTestPushTest.php
@@ -0,0 +1,121 @@
+<?php
+
+use Fleetbase\Storefront\Http\Controllers\NotificationChannelController;
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Push\ApnClientFactory;
+use Fleetbase\Storefront\Push\FirebaseMessagingFactory;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\PushOutcome;
+use Fleetbase\Storefront\Push\Transports\ApnTransport;
+use Fleetbase\Storefront\Push\Transports\FcmTransport;
+use Illuminate\Database\Capsule\Manager as Capsule;
+use Illuminate\Http\Request;
+
+beforeEach(function () {
+    $schema = Capsule::schema('mysql');
+    $schema->dropIfExists('notification_channels');
+    $schema->create('notification_channels', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('owner_uuid')->nullable();
+        $table->string('owner_type')->nullable();
+        $table->string('name')->nullable();
+        $table->string('scheme')->nullable();
+        $table->string('app_key')->nullable();
+        $table->text('config')->nullable();
+        $table->text('options')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    Capsule::connection('mysql')->table('notification_channels')->insert([
+        ['uuid' => 'fcm_uuid', 'company_uuid' => 'company_uuid', 'name' => 'Android', 'scheme' => 'fcm', 'app_key' => 'fcm_key', 'config' => '{}'],
+        ['uuid' => 'apn_uuid', 'company_uuid' => 'company_uuid', 'name' => 'iOS', 'scheme' => 'apn', 'app_key' => 'apn_key', 'config' => '{"environment":"auto"}'],
+        ['uuid' => 'foreign_uuid', 'company_uuid' => 'other_company', 'name' => 'Other', 'scheme' => 'fcm', 'app_key' => 'foreign_key', 'config' => '{}'],
+    ]);
+    session(['company' => 'company_uuid']);
+});
+
+function testPushFcm(PushOutcome|Throwable $result): FcmTransport
+{
+    return new class($result) extends FcmTransport {
+        public function __construct(public PushOutcome|Throwable $result)
+        {
+            parent::__construct(new FirebaseMessagingFactory());
+        }
+
+        public function send(NotificationChannel $channel, PushMessage $message, array $tokens): array
+        {
+            if ($this->result instanceof Throwable) {
+                throw $this->result;
+            }
+
+            return [$tokens[0] => $this->result];
+        }
+    };
+}
+
+function testPushApn(array $byEnvironment): ApnTransport
+{
+    return new class($byEnvironment) extends ApnTransport {
+        public array $environments = [];
+
+        public function __construct(public array $byEnvironment)
+        {
+            parent::__construct(new ApnClientFactory());
+        }
+
+        public function send(NotificationChannel $channel, string $environment, PushMessage $message, array $tokens): array
+        {
+            $this->environments[] = $environment;
+
+            return [$tokens[0] => $this->byEnvironment[$environment]];
+        }
+    };
+}
+
+test('test push reports FCM provider outcomes for a company channel', function () {
+    $controller = new NotificationChannelController();
+    $apn        = testPushApn([]);
+
+    $sent   = $controller->testPush('fcm_uuid', Request::create('/', 'POST', ['token' => 'android-token']), testPushFcm(PushOutcome::sent()), $apn);
+    $failed = $controller->testPush('fcm_key', Request::create('/', 'POST', ['token' => 'android-token']), testPushFcm(new RuntimeException('missing "private_key"')), $apn);
+
+    expect($sent->getData(true))->toBe([
+        'status'  => 'OK',
+        'scheme'  => 'fcm',
+        'results' => [['environment' => null, 'status' => 'sent', 'reason' => null]],
+    ])->and($failed->getData(true))->toBe([
+        'status'  => 'FAILED',
+        'scheme'  => 'fcm',
+        'results' => [['environment' => null, 'status' => 'error', 'reason' => 'missing "private_key"']],
+    ]);
+});
+
+test('test push tries each APNs environment until one accepts the token', function () {
+    $apn = testPushApn([
+        'production' => PushOutcome::wrongEnvironment('BadDeviceToken'),
+        'sandbox'    => PushOutcome::sent(),
+    ]);
+
+    $response = (new NotificationChannelController())->testPush('apn_uuid', Request::create('/', 'POST', ['token' => 'ios-token']), testPushFcm(PushOutcome::sent()), $apn);
+
+    expect($response->getData(true)['status'])->toBe('OK')
+        ->and($response->getData(true)['results'])->toBe([
+            ['environment' => 'production', 'status' => 'wrong_environment', 'reason' => 'BadDeviceToken'],
+            ['environment' => 'sandbox', 'status' => 'sent', 'reason' => null],
+        ])
+        ->and($apn->environments)->toBe(['production', 'sandbox']);
+});
+
+test('test push requires a token and a channel owned by the company', function () {
+    $controller = new NotificationChannelController();
+    $fcm        = testPushFcm(PushOutcome::sent());
+    $apn        = testPushApn([]);
+
+    $missingToken = $controller->testPush('fcm_uuid', Request::create('/', 'POST'), $fcm, $apn);
+    $foreign      = $controller->testPush('foreign_uuid', Request::create('/', 'POST', ['token' => 'android-token']), $fcm, $apn);
+
+    expect($missingToken->getStatusCode())->toBe(400)
+        ->and($foreign->getStatusCode())->toBe(404);
+});
diff --git a/server/tests/Unit/Notifications/NotificationContractsTest.php b/server/tests/Unit/Notifications/NotificationContractsTest.php
index 1c9db676..8ee760ee 100644
--- a/server/tests/Unit/Notifications/NotificationContractsTest.php
+++ b/server/tests/Unit/Notifications/NotificationContractsTest.php
@@ -1,8 +1,6 @@
 <?php
 
 use Fleetbase\FleetOps\Models\Order;
-use Fleetbase\Storefront\Models\Network;
-use Fleetbase\Storefront\Models\NotificationChannel;
 use Fleetbase\Storefront\Models\Store;
 use Fleetbase\Storefront\Notifications\PromotionalPushNotification;
 use Fleetbase\Storefront\Notifications\StorefrontOrderAccepted;
@@ -14,35 +12,12 @@
 use Fleetbase\Storefront\Notifications\StorefrontOrderNearby;
 use Fleetbase\Storefront\Notifications\StorefrontOrderPreparing;
 use Fleetbase\Storefront\Notifications\StorefrontOrderReadyForPickup;
-use Fleetbase\Storefront\Support\PushNotification;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
 use Illuminate\Notifications\Messages\MailMessage;
-use NotificationChannels\Apn\ApnMessage;
-use NotificationChannels\Fcm\FcmMessage;
 use NotificationChannels\Twilio\TwilioChannel;
 use NotificationChannels\Twilio\TwilioSmsMessage;
 
-class TestablePromotionalPushNotification extends PromotionalPushNotification
-{
-    public static ?Pushok\Client $apnClient        = null;
-    public static ?NotificationChannel $fcmChannel = null;
-    public static mixed $fcmClient                 = null;
-
-    protected function getApnClient(): ?Pushok\Client
-    {
-        return static::$apnClient;
-    }
-
-    protected function getFcmNotificationChannel(): ?NotificationChannel
-    {
-        return static::$fcmChannel;
-    }
-
-    protected function getFcmClient(NotificationChannel $notificationChannel)
-    {
-        return static::$fcmClient;
-    }
-}
-
 function notificationWithoutConstructor(string $class, Order $order, Store $store, array $properties = []): object
 {
     $notification                 = (new ReflectionClass($class))->newInstanceWithoutConstructor();
@@ -97,8 +72,13 @@ function notificationOrder(array $meta = []): Order
             'notifiable'      => 'user_public',
             'notification_id' => 'notification_contract',
             'sent_at'         => '2026-07-26 12:00:00',
+            'type'            => $status,
+            'title'           => $subject,
+            'body'            => $body,
             'subject'         => $subject,
             'message'         => $arrayMessage,
+            'order'           => 'order_uuid',
+            'order_id'        => 'order_public',
             'storefront'      => 'Corner Store',
             'storefront_id'   => 'store_public',
             'id'              => 'contact_public',
@@ -113,7 +93,7 @@ function notificationOrder(array $meta = []): Order
         'Order accepted',
         'Your order was accepted.',
         'order_accepted',
-        'order_accepted',
+        'Your order was accepted.',
     ],
     'canceled' => [
         StorefrontOrderCanceled::class,
@@ -127,42 +107,42 @@ function notificationOrder(array $meta = []): Order
         'Order completed',
         'Your order was delivered.',
         'order_completed',
-        'order_completed',
+        'Your order was delivered.',
     ],
     'driver assigned' => [
         StorefrontOrderDriverAssigned::class,
         'Driver assigned',
         'A driver is heading to the store.',
         'order_driver_assigned',
-        'order_driver_assigned',
+        'A driver is heading to the store.',
     ],
     'enroute' => [
         StorefrontOrderEnroute::class,
         'Order enroute',
         'Your order is on the way.',
         'order_enroute',
-        'order_enroute',
+        'Your order is on the way.',
     ],
     'nearby' => [
         StorefrontOrderNearby::class,
         'Order nearby',
         'Your order is almost there.',
         'order_nearby',
-        'order_nearby',
+        'Your order is almost there.',
     ],
     'preparing' => [
         StorefrontOrderPreparing::class,
         'Order preparing',
         'Your order is being prepared.',
         'order_preparing',
-        'order_preparing',
+        'Your order is being prepared.',
     ],
     'ready for pickup' => [
         StorefrontOrderReadyForPickup::class,
         'Order ready',
         'Your order is ready for pickup.',
         'order_ready',
-        'order_ready',
+        'Your order is ready for pickup.',
     ],
 ]);
 
@@ -209,25 +189,23 @@ function notificationOrder(array $meta = []): Order
         : new $class($order);
     $notifiable = (object) ['public_id' => 'user_public'];
 
+    $push = $notification->toPush($notifiable);
+
     expect($notification->storefront->public_id)->toBe('store_public')
         ->and($notification->status)->toBe($expectedStatus)
         ->and($notification->subject)->not->toBeEmpty()
         ->and($notification->body)->not->toBeEmpty()
-        ->and($notification->via($notifiable))->toBe(['mail', 'database'])
-        ->and($notification->toFcm($notifiable))->toBeInstanceOf(FcmMessage::class)
-        ->and($notification->toApn($notifiable))->toBeInstanceOf(ApnMessage::class);
-
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->insert([
-        ['owner_uuid' => 'store_uuid', 'scheme' => 'apn'],
-        ['owner_uuid' => 'store_uuid', 'scheme' => 'fcm'],
-    ]);
-
-    expect($notification->via($notifiable))->toBe([
-        'mail',
-        'database',
-        NotificationChannels\Apn\ApnChannel::class,
-        NotificationChannels\Fcm\FcmChannel::class,
-    ]);
+        ->and($notification->via($notifiable))->toBe([StorefrontPushChannel::class, 'database', 'mail'])
+        ->and($push)->toBeInstanceOf(PushMessage::class)
+        ->and($push->title)->toBe($notification->subject)
+        ->and($push->body)->toBe($notification->body)
+        ->and($push->data)->toMatchArray([
+            'type'     => $expectedStatus,
+            'order'    => 'order_uuid',
+            'id'       => 'order_public',
+            'store_id' => 'store_public',
+        ])
+        ->and(collect($notification->pushStorefronts())->pluck('uuid')->all())->toBe(['store_uuid']);
 })->with([
     'accepted'        => [StorefrontOrderAccepted::class, 'order_accepted'],
     'canceled'        => [StorefrontOrderCanceled::class, 'order_canceled'],
@@ -335,6 +313,28 @@ function notificationOrder(array $meta = []): Order
         ->and($notification->sentAt)->not->toBeEmpty();
 });
 
+test('order notifications tolerate orders without a loaded customer or company', function () {
+    $order = new Order();
+    $order->forceFill(['uuid' => 'order_uuid', 'public_id' => 'order_public', 'meta' => []]);
+    $order->setRelation('customer', null);
+    $order->setRelation('company', null);
+    $store = new Store();
+    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public', 'name' => 'Corner Store']);
+
+    $notification = notificationWithoutConstructor(StorefrontOrderCompleted::class, $order, $store, [
+        'subject' => 'Order completed',
+        'body'    => 'Your order was delivered.',
+        'status'  => 'order_completed',
+    ]);
+
+    expect($notification->toArray(null))->toMatchArray([
+        'notifiable' => null,
+        'id'         => null,
+        'companyId'  => null,
+        'message'    => 'Your order was delivered.',
+    ]);
+});
+
 test('promotional notifications expose their persisted payload contract', function () {
     $store = new Store();
     $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public', 'name' => 'Corner Store']);
@@ -345,6 +345,7 @@ function notificationOrder(array $meta = []): Order
     expect($payload)->toMatchArray([
         'title'    => 'Weekend sale',
         'body'     => 'Save twenty percent',
+        'message'  => 'Save twenty percent',
         'store'    => 'store_uuid',
         'store_id' => 'store_public',
         'type'     => 'promotional',
@@ -352,409 +353,17 @@ function notificationOrder(array $meta = []): Order
         ->and($payload['notification_id'])->toStartWith('notification_');
 });
 
-test('promotional notifications build configured APN and FCM provider messages', function () {
-    config(['firebase.projects.app' => [
-        'credentials' => ['private_key' => 'default-key'],
-        'database'    => ['url' => 'https://default.example.test'],
-    ]]);
-
+test('promotional notifications deliver through the storefront push channel and the inbox', function () {
     $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
-
-    $channel = new NotificationChannel();
-    $channel->forceFill(['app_key' => 'store-app']);
-    $channel->config = [
-        'firebase_credentials_json' => 'channel-private-key',
-        'firebase_database_url'     => 'https://channel.example.test',
-    ];
-
-    TestablePromotionalPushNotification::$apnClient  = (new ReflectionClass(Pushok\Client::class))->newInstanceWithoutConstructor();
-    TestablePromotionalPushNotification::$fcmChannel = $channel;
-    TestablePromotionalPushNotification::$fcmClient  = (new ReflectionClass(Kreait\Firebase\Messaging::class))->newInstanceWithoutConstructor();
-
-    $notification = new TestablePromotionalPushNotification('Weekend sale', 'Save now', $store);
-
-    expect($notification->toApn(null))->toBeInstanceOf(ApnMessage::class)
-        ->and($notification->toFcm(null))->toBeInstanceOf(FcmMessage::class)
-        ->and(data_get(config('firebase.projects.store-app'), 'credentials.private_key'))->toBe('channel-private-key');
-});
-
-test('promotional notification provider resolvers honor the persisted channel configuration', function () {
-    $schema = Illuminate\Database\Capsule\Manager::schema('mysql');
-    $schema->dropIfExists('notification_channels');
-    $schema->create('notification_channels', function (Illuminate\Database\Schema\Blueprint $table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('owner_uuid');
-        $table->string('app_key');
-        $table->string('scheme');
-        $table->text('config')->nullable();
-        $table->timestamps();
-        $table->softDeletes();
-    });
-
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
-    $notification = new PromotionalPushNotification('Weekend sale', 'Save now', $store);
-
-    $apnResolver    = new ReflectionMethod($notification, 'getApnClient');
-    $fcmResolver    = new ReflectionMethod($notification, 'getFcmNotificationChannel');
-    $clientResolver = new ReflectionMethod($notification, 'getFcmClient');
-
-    expect($apnResolver->invoke($notification))->toBeNull()
-        ->and($fcmResolver->invoke($notification))->toBeNull();
-
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->insert([
-        'uuid'       => 'channel_uuid',
-        'owner_uuid' => 'store_uuid',
-        'app_key'    => 'store-app',
-        'scheme'     => 'fcm',
-        'config'     => '{}',
-    ]);
-
-    $channel = $fcmResolver->invoke($notification);
-
-    expect($channel?->app_key)->toBe('store-app');
-
-    try {
-        $clientResolver->invoke($notification, $channel);
-    } catch (Throwable $exception) {
-        expect($exception)->toBeInstanceOf(Throwable::class);
-    }
-});
-
-test('push notification messages retain payloads when provider channels are not configured', function () {
-    $order = notificationOrder();
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
-
-    $double = new class extends PushNotification {
-        public static Store $store;
-        public static ?string $requestedScheme = null;
-
-        public static function getStorefrontFromOrder(Order $order): Network|Store|null
-        {
-            return static::$store;
-        }
-
-        public static function getApnClient(Network|Store $storefront, ?Order $order = null): ?Pushok\Client
-        {
-            return null;
-        }
-
-        public static function getNotificationChannel(string $scheme, Network|Store $storefront, ?Order $order = null): ?NotificationChannel
-        {
-            static::$requestedScheme = $scheme;
-
-            return null;
-        }
-    };
-    $double::$store = $store;
-
-    $apn = $double::createApnMessage($order, 'Order ready', 'Collect your order', 'pickup_ready');
-    $fcm = $double::createFcmMessage($order, 'Order ready', 'Collect your order', 'pickup_ready');
-
-    expect($apn)->toBeInstanceOf(ApnMessage::class)
-        ->and($fcm)->toBeInstanceOf(FcmMessage::class)
-        ->and($double::$requestedScheme)->toBe('fcm');
-});
-
-test('configured FCM messages include order routing metadata and the isolated provider client', function () {
-    $order = notificationOrder();
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
-    $channel = new NotificationChannel();
-    $channel->forceFill(['app_key' => 'store-app']);
-    $channel->config = [
-        'firebase_credentials_json' => 'channel-private-key',
-        'firebase_database_url'     => 'https://channel.example.test',
-    ];
-    $client = (new ReflectionClass(Kreait\Firebase\Messaging::class))->newInstanceWithoutConstructor();
-
-    $double = new class extends PushNotification {
-        public static Store $store;
-        public static NotificationChannel $channel;
-        public static Kreait\Firebase\Contract\Messaging $client;
-
-        public static function getStorefrontFromOrder(Order $order): Network|Store|null
-        {
-            return static::$store;
-        }
-
-        public static function getNotificationChannel(string $scheme, Network|Store $storefront, ?Order $order = null): ?NotificationChannel
-        {
-            return static::$channel;
-        }
-
-        protected static function getFcmClient(NotificationChannel $notificationChannel)
-        {
-            return static::$client;
-        }
-    };
-    $double::$store   = $store;
-    $double::$channel = $channel;
-    $double::$client  = $client;
-    config(['firebase.projects.app' => [
-        'credentials' => ['private_key' => 'default-key'],
-        'database'    => ['url' => 'https://default.example.test'],
-    ]]);
-
-    $message = $double::createFcmMessage($order, 'Order ready', 'Collect your order', 'pickup_ready');
-    $payload = $message->toArray();
-
-    expect($message->client)->toBe($client)
-        ->and($message->notification?->title)->toBe('Order ready')
-        ->and($message->notification?->body)->toBe('Collect your order')
-        ->and($message->data)->toBe([
-            'order' => $order->uuid,
-            'id'    => $order->public_id,
-            'type'  => 'pickup_ready',
-        ])
-        ->and(data_get($payload, 'android.notification.sound'))->toBe('default')
-        ->and(data_get($payload, 'apns.payload.aps.sound'))->toBe('default');
-});
-
-test('push notification creates the configured firebase project messaging client', function () {
-    $privateKey = openssl_pkey_new(['private_key_bits' => 2048]);
-    openssl_pkey_export($privateKey, $privateKeyContent);
-    config(['firebase.projects.real-app' => [
-        'credentials' => [
-            'type'                        => 'service_account',
-            'project_id'                  => 'storefront-tests',
-            'private_key_id'              => 'key-id',
-            'private_key'                 => $privateKeyContent,
-            'client_email'                => 'firebase-admin@example.test',
-            'client_id'                   => '123456789',
-            'auth_uri'                    => 'https://accounts.google.com/o/oauth2/auth',
-            'token_uri'                   => 'https://oauth2.googleapis.com/token',
-            'auth_provider_x509_cert_url' => 'https://www.googleapis.com/oauth2/v1/certs',
-            'client_x509_cert_url'        => 'https://www.googleapis.com/robot/v1/metadata/x509/firebase-admin',
-        ],
-    ]]);
-    Illuminate\Container\Container::getInstance()->instance('config', new class {
-        public function get(string $key)
-        {
-            return config($key);
-        }
-    });
-    $channel = new NotificationChannel();
-    $channel->forceFill(['app_key' => 'real-app']);
-    $method = new ReflectionMethod(PushNotification::class, 'getFcmClient');
-
-    $client = $method->invoke(null, $channel);
-
-    expect($client)->toBeInstanceOf(Kreait\Firebase\Contract\Messaging::class);
-});
-
-test('push notification configures isolated firebase projects from channel credentials', function () {
-    config(['firebase.projects.app' => [
-        'credentials' => ['private_key' => 'default-key', 'client_email' => 'firebase@example.test'],
-        'database'    => ['url' => 'https://default.example.test'],
-    ]]);
-
-    $channel = new NotificationChannel();
-    $channel->forceFill(['app_key' => 'store-app']);
-    $channel->config = [
-        'firebase_credentials_json' => 'channel-private-key',
-        'firebase_database_url'     => 'https://channel.example.test',
-    ];
-
-    $configured = PushNotification::configureFcm($channel);
-
-    expect(data_get($configured, 'credentials.private_key'))->toBe('channel-private-key')
-        ->and(data_get($configured, 'credentials.client_email'))->toBe('firebase@example.test')
-        ->and(data_get($configured, 'database.url'))->toBe('https://channel.example.test')
-        ->and(config('firebase.projects.store-app'))->toBe($configured);
-});
-
-test('push notification channel lookup honors an order channel override before storefront defaults', function () {
-    $schema = Illuminate\Database\Capsule\Manager::schema('mysql');
-    $schema->dropIfExists('notification_channels');
-    $schema->create('notification_channels', function (Illuminate\Database\Schema\Blueprint $table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('owner_uuid');
-        $table->string('owner_type')->nullable();
-        $table->string('app_key');
-        $table->string('scheme');
-        $table->text('config')->nullable();
-        $table->text('options')->nullable();
-        $table->timestamps();
-        $table->softDeletes();
-    });
-
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->insert([
-        [
-            'uuid'       => 'channel_default',
-            'owner_uuid' => 'store_uuid',
-            'app_key'    => 'default-app',
-            'scheme'     => 'fcm',
-        ],
-        [
-            'uuid'       => 'channel_override',
-            'owner_uuid' => 'store_uuid',
-            'app_key'    => 'override-app',
-            'scheme'     => 'fcm',
-        ],
-    ]);
-
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid']);
-
-    $default  = PushNotification::getNotificationChannel('fcm', $store);
-    $order    = notificationOrder(['storefront_notification_channel' => 'override-app']);
-    $override = PushNotification::getNotificationChannel('fcm', $store, $order);
-
-    expect($default?->app_key)->toBe('default-app')
-        ->and($override?->app_key)->toBe('override-app')
-        ->and(PushNotification::getNotificationChannel('apn', $store))->toBeNull();
-});
-
-test('push notification resolves APN credentials into a production-aware provider client', function () {
-    $schema = Illuminate\Database\Capsule\Manager::schema('mysql');
-    $schema->dropIfExists('notification_channels');
-    $schema->create('notification_channels', function (Illuminate\Database\Schema\Blueprint $table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('owner_uuid');
-        $table->string('owner_type')->nullable();
-        $table->string('app_key');
-        $table->string('scheme');
-        $table->text('config')->nullable();
-        $table->text('options')->nullable();
-        $table->timestamps();
-        $table->softDeletes();
-    });
-    $privateKey = openssl_pkey_new([
-        'private_key_type' => OPENSSL_KEYTYPE_EC,
-        'curve_name'       => 'secp521r1',
-    ]);
-    openssl_pkey_export($privateKey, $privateKeyContent);
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->insert([
-        'uuid'       => 'channel_apn',
-        'owner_uuid' => 'store_uuid',
-        'app_key'    => 'store-app',
-        'scheme'     => 'apn',
-        'config'     => json_encode([
-            'key_id'              => 'KEY123',
-            'team_id'             => 'TEAM123',
-            'app_bundle_id'       => 'com.example.storefront',
-            'private_key_content' => $privateKeyContent,
-            'production'          => false,
-        ]),
-    ]);
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid']);
-
-    $client = PushNotification::getApnClient($store);
-
-    expect($client)->toBeInstanceOf(Pushok\Client::class);
-});
-
-test('push notification resolves the storefront referenced by order metadata', function () {
-    $schema = Illuminate\Database\Capsule\Manager::schema('mysql');
-    $schema->dropIfExists('stores');
-    $schema->create('stores', function (Illuminate\Database\Schema\Blueprint $table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('public_id')->nullable();
-        $table->string('key')->nullable();
-        $table->string('name')->nullable();
-        $table->string('company_uuid')->nullable();
-        $table->string('backdrop_uuid')->nullable();
-        $table->string('logo_uuid')->nullable();
-        $table->string('order_config_uuid')->nullable();
-        $table->text('description')->nullable();
-        $table->text('translations')->nullable();
-        $table->string('website')->nullable();
-        $table->string('facebook')->nullable();
-        $table->string('instagram')->nullable();
-        $table->string('twitter')->nullable();
-        $table->string('email')->nullable();
-        $table->string('phone')->nullable();
-        $table->text('tags')->nullable();
-        $table->string('currency')->nullable();
-        $table->string('timezone')->nullable();
-        $table->string('pod_method')->nullable();
-        $table->text('options')->nullable();
-        $table->timestamp('deleted_at')->nullable();
-    });
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('stores')->insert([
-        'uuid'      => 'store_uuid',
-        'public_id' => 'store_public',
-        'key'       => 'store_key',
-        'name'      => 'Test store',
-    ]);
-
-    $storefront = PushNotification::getStorefrontFromOrder(
-        notificationOrder(['storefront_id' => 'store_public'])
-    );
-
-    expect($storefront)->toBeInstanceOf(Store::class)
-        ->and($storefront->uuid)->toBe('store_uuid');
-});
-
-test('configured APN messages include order routing metadata and provider client', function () {
-    $order = notificationOrder();
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
-    $client = (new ReflectionClass(Pushok\Client::class))->newInstanceWithoutConstructor();
-
-    $double = new class extends PushNotification {
-        public static Store $store;
-        public static Pushok\Client $client;
-
-        public static function getStorefrontFromOrder(Order $order): Network|Store|null
-        {
-            return static::$store;
-        }
-
-        public static function getApnClient(Network|Store $storefront, ?Order $order = null): ?Pushok\Client
-        {
-            return static::$client;
-        }
-    };
-    $double::$store  = $store;
-    $double::$client = $client;
-
-    $message = $double::createApnMessage($order, 'Order ready', 'Collect it now', 'pickup_ready');
-
-    expect($message)->toBeInstanceOf(ApnMessage::class);
-});
-
-test('promotional notifications select only configured provider channels and fail closed without them', function () {
-    $schema = Illuminate\Database\Capsule\Manager::schema('mysql');
-    $schema->dropIfExists('notification_channels');
-    $schema->create('notification_channels', function (Illuminate\Database\Schema\Blueprint $table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('owner_uuid');
-        $table->string('owner_type')->nullable();
-        $table->string('app_key');
-        $table->string('scheme');
-        $table->text('config')->nullable();
-        $table->text('options')->nullable();
-        $table->timestamps();
-        $table->softDeletes();
-    });
-
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->insert([
-        ['owner_uuid' => 'store_uuid', 'app_key' => 'apn-app', 'scheme' => 'apn'],
-        ['owner_uuid' => 'store_uuid', 'app_key' => 'fcm-app', 'scheme' => 'fcm'],
-    ]);
+    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public', 'name' => 'Corner Store']);
+    $store->setRelation('networks', collect([tap(new Fleetbase\Storefront\Models\Network())->forceFill(['uuid' => 'network_uuid'])]));
 
-    $store = new Store();
-    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
     $notification = new PromotionalPushNotification('Weekend sale', 'Save now', $store);
+    $push         = $notification->toPush(null);
 
-    expect($notification->via(null))->toBe([
-        NotificationChannels\Apn\ApnChannel::class,
-        NotificationChannels\Fcm\FcmChannel::class,
-    ]);
-
-    Illuminate\Database\Capsule\Manager::connection('mysql')->table('notification_channels')->delete();
-
-    expect($notification->via(null))->toBe([])
-        ->and($notification->toApn(null))->toBeNull()
-        ->and($notification->toFcm(null))->toBeNull();
+    expect($notification->via(null))->toBe([StorefrontPushChannel::class, 'database'])
+        ->and($push)->toBeInstanceOf(PushMessage::class)
+        ->and($push->title)->toBe('Weekend sale')
+        ->and($push->data)->toBe(['type' => 'promotional', 'store' => 'store_uuid', 'store_id' => 'store_public'])
+        ->and(collect($notification->pushStorefronts())->pluck('uuid')->all())->toBe(['store_uuid', 'network_uuid']);
 });
diff --git a/server/tests/Unit/Push/PushLayerTest.php b/server/tests/Unit/Push/PushLayerTest.php
new file mode 100644
index 00000000..249aa7b9
--- /dev/null
+++ b/server/tests/Unit/Push/PushLayerTest.php
@@ -0,0 +1,526 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Models\UserDevice;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\NotificationChannel;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Push\ApnClientFactory;
+use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
+use Fleetbase\Storefront\Push\FirebaseMessagingFactory;
+use Fleetbase\Storefront\Push\PushConfigurationException;
+use Fleetbase\Storefront\Push\PushCredentialResolver;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\PushOutcome;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Push\Transports\ApnTransport;
+use Fleetbase\Storefront\Push\Transports\FcmTransport;
+use Illuminate\Database\Capsule\Manager as Capsule;
+use Illuminate\Notifications\Notification;
+use Kreait\Firebase\Exception\Messaging\AuthenticationError;
+use Kreait\Firebase\Exception\Messaging\InvalidMessage;
+use Kreait\Firebase\Exception\Messaging\NotFound;
+use Kreait\Firebase\Exception\Messaging\ServerUnavailable;
+use Kreait\Firebase\Messaging\MessageTarget;
+use Kreait\Firebase\Messaging\SendReport;
+
+function pushChannel(array $attributes, array $config = []): NotificationChannel
+{
+    $channel = new NotificationChannel();
+    $channel->forceFill(array_merge(['uuid' => $attributes['app_key'] ?? 'channel', 'name' => 'Test channel'], $attributes));
+    $channel->config = $config;
+
+    return $channel;
+}
+
+function pushDevice(string $token, string $platform, array $attributes = []): UserDevice
+{
+    $device = new UserDevice();
+    $device->forceFill(array_merge(['token' => $token, 'platform' => $platform, 'status' => 'active'], $attributes));
+
+    return $device;
+}
+
+function pushServiceAccount(): array
+{
+    $key = openssl_pkey_new(['private_key_bits' => 2048]);
+    openssl_pkey_export($key, $privateKey);
+
+    return [
+        'type'         => 'service_account',
+        'project_id'   => 'storefront-tests',
+        'client_email' => 'firebase-admin@storefront-tests.iam.gserviceaccount.com',
+        'client_id'    => '1234567890',
+        'private_key'  => $privateKey,
+    ];
+}
+
+function pushNotification(array $storefronts, ?PushMessage $message = null): Notification
+{
+    return new class($storefronts, $message ?? PushMessage::create('Order ready', 'Collect it now', ['id' => 'order_public'])) extends Notification implements SendsPushNotification {
+        public function __construct(public array $storefronts, public PushMessage $message)
+        {
+        }
+
+        public function toPush($notifiable): ?PushMessage
+        {
+            return $this->message;
+        }
+
+        public function pushStorefronts(): array
+        {
+            return $this->storefronts;
+        }
+    };
+}
+
+function fakeResolver(array $channelsByScheme): PushCredentialResolver
+{
+    return new class($channelsByScheme) extends PushCredentialResolver {
+        public array $calls = [];
+
+        public function __construct(public array $channelsByScheme)
+        {
+        }
+
+        public function channels(string $scheme, array $storefronts, ?string $appIdentifier = null): Illuminate\Support\Collection
+        {
+            $this->calls[] = [$scheme, $appIdentifier];
+
+            return collect($this->channelsByScheme[$scheme] ?? []);
+        }
+    };
+}
+
+function fakeFcm(callable $handler): FcmTransport
+{
+    return new class($handler) extends FcmTransport {
+        public array $calls = [];
+
+        public function __construct(public $handler)
+        {
+        }
+
+        public function send(NotificationChannel $channel, PushMessage $message, array $tokens): array
+        {
+            $this->calls[] = [$channel->app_key, $tokens];
+
+            return ($this->handler)($channel, $tokens);
+        }
+    };
+}
+
+function fakeApn(callable $handler): ApnTransport
+{
+    return new class($handler) extends ApnTransport {
+        public array $calls = [];
+
+        public function __construct(public $handler)
+        {
+        }
+
+        public function send(NotificationChannel $channel, string $environment, PushMessage $message, array $tokens): array
+        {
+            $this->calls[] = [$channel->app_key, $environment, $tokens];
+
+            return ($this->handler)($channel, $environment, $tokens);
+        }
+    };
+}
+
+function createUserDevicesTable(): void
+{
+    $schema = Capsule::schema('mysql');
+    $schema->dropIfExists('user_devices');
+    $schema->create('user_devices', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('platform')->nullable();
+        $table->text('token')->nullable();
+        $table->string('status')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+}
+
+test('push messages render high priority FCM payloads with string data', function () {
+    $message = PushMessage::create('Order ready', 'Collect it now', [
+        'id'       => 'order_public',
+        'count'    => 2,
+        'pickup'   => true,
+        'meta'     => ['a' => 1],
+        'optional' => null,
+    ])->analyticsLabel('storefront_order');
+
+    $payload = $message->toFcmArray(['android_channel_id' => 'orders']);
+
+    expect($payload['notification'])->toBe(['title' => 'Order ready', 'body' => 'Collect it now'])
+        ->and($payload['data'])->toBe(['id' => 'order_public', 'count' => '2', 'pickup' => 'true', 'meta' => '{"a":1}'])
+        ->and($payload['android']['priority'])->toBe('high')
+        ->and($payload['android']['notification'])->toMatchArray(['channel_id' => 'orders', 'sound' => 'default'])
+        ->and($payload['apns']['headers'])->toBe(['apns-priority' => '10', 'apns-push-type' => 'alert'])
+        ->and($payload['apns']['payload']['aps'])->toBe(['sound' => 'default', 'badge' => 1])
+        ->and($payload['fcm_options'])->toBe(['analytics_label' => 'storefront_order'])
+        ->and(Kreait\Firebase\Messaging\CloudMessage::fromArray($payload))->toBeInstanceOf(Kreait\Firebase\Messaging\CloudMessage::class);
+
+    expect(PushMessage::create('Hi', 'There')->toFcmArray())->not->toHaveKey('data')
+        ->and(PushMessage::create('Hi', 'There')->toFcmArray()['android']['notification'])->not->toHaveKey('channel_id');
+});
+
+test('push messages render APNs payloads with sound badge and custom data', function () {
+    $payload = json_decode(json_encode(
+        PushMessage::create('Order ready', 'Collect it now', ['id' => 'order_public', 'type' => 'order_ready', 'aps' => 'ignored'])->toApnPayload()
+    ), true);
+
+    expect($payload['aps'])->toMatchArray([
+        'alert' => ['title' => 'Order ready', 'body' => 'Collect it now'],
+        'sound' => 'default',
+        'badge' => 1,
+    ])->and($payload['id'])->toBe('order_public')
+        ->and($payload['type'])->toBe('order_ready');
+});
+
+test('firebase service accounts are decoded from the channel and repaired', function () {
+    $account                = pushServiceAccount();
+    $escaped                = $account;
+    $escaped['private_key'] = str_replace("\n", '\\n', $account['private_key']);
+    unset($escaped['type']);
+
+    $decoded = FirebaseMessagingFactory::serviceAccountFromChannel(
+        pushChannel(['app_key' => 'fcm'], ['firebase_credentials_json' => json_encode($escaped)])
+    );
+
+    expect($decoded['private_key'])->toBe($account['private_key'])
+        ->and($decoded['type'])->toBe('service_account')
+        ->and($decoded['project_id'])->toBe('storefront-tests');
+
+    expect(fn () => FirebaseMessagingFactory::serviceAccountFromChannel(pushChannel(['app_key' => 'fcm'], ['firebase_credentials_json' => 'not json'])))
+        ->toThrow(PushConfigurationException::class, 'invalid Firebase service account JSON')
+        ->and(fn () => FirebaseMessagingFactory::serviceAccountFromChannel(pushChannel(['app_key' => 'fcm'], [])))
+        ->toThrow(PushConfigurationException::class, 'missing its Firebase service account JSON')
+        ->and(fn () => FirebaseMessagingFactory::serviceAccountFromChannel(pushChannel(['app_key' => 'fcm'], ['firebase_credentials_json' => json_encode(['project_id' => 'x'])])))
+        ->toThrow(PushConfigurationException::class, 'missing "client_email"');
+});
+
+test('firebase messaging clients are built from the channel without touching application config', function () {
+    FirebaseMessagingFactory::flush();
+    config(['firebase.projects.app' => null]);
+
+    $channel  = pushChannel(['app_key' => 'fcm', 'uuid' => 'fcm_uuid'], ['firebase_credentials_json' => json_encode(pushServiceAccount())]);
+    $factory  = new FirebaseMessagingFactory();
+    $client   = $factory->make($channel);
+
+    expect($client)->toBeInstanceOf(Kreait\Firebase\Contract\Messaging::class)
+        ->and($factory->make($channel))->toBe($client)
+        ->and(config('firebase.projects.fcm'))->toBeNull()
+        ->and(config('firebase.projects.app'))->toBeNull();
+});
+
+test('APNs environments honor device, explicit and legacy channel settings', function () {
+    $channel = fn (array $config) => pushChannel(['app_key' => 'apn'], $config);
+
+    expect(ApnClientFactory::environments($channel(['environment' => 'sandbox'])))->toBe(['sandbox'])
+        ->and(ApnClientFactory::environments($channel(['environment' => 'production'])))->toBe(['production'])
+        ->and(ApnClientFactory::environments($channel(['environment' => 'auto'])))->toBe(['production', 'sandbox'])
+        ->and(ApnClientFactory::environments($channel(['production' => true])))->toBe(['production', 'sandbox'])
+        ->and(ApnClientFactory::environments($channel(['production' => false])))->toBe(['sandbox', 'production'])
+        ->and(ApnClientFactory::environments($channel(['production' => 'false'])))->toBe(['sandbox', 'production'])
+        ->and(ApnClientFactory::environments($channel([])))->toBe(['production', 'sandbox'])
+        ->and(ApnClientFactory::environments($channel(['environment' => 'production']), 'sandbox'))->toBe(['sandbox']);
+});
+
+test('APNs credentials are validated and normalized', function () {
+    $credentials = ApnClientFactory::credentialsFromChannel(pushChannel(['app_key' => 'apn'], [
+        'key_id'              => ' KEY123 ',
+        'team_id'             => 'TEAM123',
+        'app_bundle_id'       => 'com.example.storefront',
+        'private_key_content' => "-----BEGIN PRIVATE KEY-----\\nabc\\n-----END PRIVATE KEY-----\n",
+    ]));
+
+    expect($credentials['key_id'])->toBe('KEY123')
+        ->and($credentials['private_key_content'])->toBe("-----BEGIN PRIVATE KEY-----\nabc\n-----END PRIVATE KEY-----");
+
+    expect(fn () => ApnClientFactory::credentialsFromChannel(pushChannel(['app_key' => 'apn'], ['key_id' => 'a', 'team_id' => 'b'])))
+        ->toThrow(PushConfigurationException::class, 'missing "app_bundle_id"')
+        ->and(fn () => ApnClientFactory::credentialsFromChannel(pushChannel(['app_key' => 'apn'], ['key_id' => 'a', 'team_id' => 'b', 'app_bundle_id' => 'c'])))
+        ->toThrow(PushConfigurationException::class, 'missing its .p8 private key');
+
+    $key = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_EC, 'curve_name' => 'prime256v1']);
+    openssl_pkey_export($key, $privateKey);
+    $client = (new ApnClientFactory())->make(pushChannel(['app_key' => 'apn'], [
+        'key_id'              => 'KEY123',
+        'team_id'             => 'TEAM123',
+        'app_bundle_id'       => 'com.example.storefront',
+        'private_key_content' => $privateKey,
+    ]), 'sandbox');
+
+    expect($client)->toBeInstanceOf(Pushok\Client::class);
+});
+
+test('APNs responses map to push outcomes', function ($status, $reason, $expected) {
+    $response = new Pushok\Response($status, '', $reason ? json_encode(['reason' => $reason]) : '', 'token');
+
+    expect(ApnTransport::outcomeFor($response)->status)->toBe($expected);
+})->with([
+    'sent'                => [200, null, PushOutcome::SENT],
+    'unregistered'        => [410, 'Unregistered', PushOutcome::DEAD],
+    'expired'             => [410, 'ExpiredToken', PushOutcome::DEAD],
+    'bad device token'    => [400, 'BadDeviceToken', PushOutcome::WRONG_ENVIRONMENT],
+    'wrong topic'         => [400, 'DeviceTokenNotForTopic', PushOutcome::WRONG_APP],
+    'bad provider token'  => [403, 'InvalidProviderToken', PushOutcome::ERROR],
+]);
+
+test('FCM send reports map to push outcomes', function ($error, $expected) {
+    $target = MessageTarget::with(MessageTarget::TOKEN, 'token');
+    $error  = $error instanceof Closure ? $error() : $error;
+    $report = $error ? SendReport::failure($target, $error) : SendReport::success($target, ['name' => 'projects/x/messages/1']);
+
+    expect(FcmTransport::outcomeFor($report)->status)->toBe($expected);
+})->with([
+    'sent'               => [null, PushOutcome::SENT],
+    'unregistered'       => [fn () => new NotFound('Requested entity was not found.'), PushOutcome::DEAD],
+    'invalid token'      => [fn () => new InvalidMessage('The registration token is not a valid FCM registration token'), PushOutcome::DEAD],
+    'sender mismatch'    => [fn () => new AuthenticationError('SenderId mismatch'), PushOutcome::WRONG_APP],
+    'bad credentials'    => [fn () => new AuthenticationError('Request had invalid authentication credentials.'), PushOutcome::ERROR],
+    'provider outage'    => [fn () => new ServerUnavailable('Service unavailable'), PushOutcome::ERROR],
+]);
+
+test('storefront push channel routes devices by platform and retries tokens from another app on the next channel', function () {
+    $network = pushChannel(['app_key' => 'network_fcm', 'scheme' => 'fcm']);
+    $store   = pushChannel(['app_key' => 'store_fcm', 'scheme' => 'fcm']);
+    $apn     = pushChannel(['app_key' => 'store_apn', 'scheme' => 'apn'], ['environment' => 'production']);
+
+    $fcm = fakeFcm(fn (NotificationChannel $channel, array $tokens) => collect($tokens)->mapWithKeys(fn ($token) => [
+        $token => $channel->app_key === 'network_fcm' && $token === 'android_store_app' ? PushOutcome::wrongApp('SenderId mismatch') : PushOutcome::sent(),
+    ])->all());
+    $apnTransport = fakeApn(fn ($channel, $environment, array $tokens) => array_fill_keys($tokens, PushOutcome::sent()));
+    $pushChannel  = new StorefrontPushChannel(fakeResolver(['fcm' => [$network, $store], 'apn' => [$apn]]), $fcm, $apnTransport);
+
+    $notifiable = new class {
+        public $devices;
+    };
+    $notifiable->devices = collect([
+        pushDevice('android_network_app', 'android'),
+        pushDevice('android_store_app', 'Android'),
+        pushDevice('ios_device', 'iOS'),
+        pushDevice('ios_device', 'ios'),
+        pushDevice('stale_device', 'android', ['status' => 'invalid']),
+        pushDevice('web_device', 'web'),
+    ]);
+
+    $outcomes = $pushChannel->send($notifiable, pushNotification([]));
+
+    expect(collect($outcomes)->map->status->all())->toBe([
+        'android_network_app' => PushOutcome::SENT,
+        'android_store_app'   => PushOutcome::SENT,
+        'ios_device'          => PushOutcome::SENT,
+    ])->and($fcm->calls)->toBe([
+        ['network_fcm', ['android_network_app', 'android_store_app']],
+        ['store_fcm', ['android_store_app']],
+    ])->and($apnTransport->calls)->toBe([
+        ['store_apn', 'production', ['ios_device']],
+    ]);
+});
+
+test('storefront push channel retries BadDeviceToken in the other APNs environment', function () {
+    $apn = pushChannel(['app_key' => 'store_apn', 'scheme' => 'apn'], ['production' => true]);
+
+    $transport = fakeApn(fn ($channel, string $environment, array $tokens) => collect($tokens)->mapWithKeys(fn ($token) => [
+        $token => $environment === 'production' && $token === 'dev_build' ? PushOutcome::wrongEnvironment('BadDeviceToken') : PushOutcome::sent(),
+    ])->all());
+    $pushChannel = new StorefrontPushChannel(fakeResolver(['apn' => [$apn]]), fakeFcm(fn () => []), $transport);
+
+    $notifiable          = new stdClass();
+    $notifiable->devices = collect([pushDevice('dev_build', 'ios'), pushDevice('app_store_build', 'ios')]);
+    $notifiable          = new class($notifiable->devices) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+
+    $outcomes = $pushChannel->send($notifiable, pushNotification([]));
+
+    expect($outcomes['dev_build']->status)->toBe(PushOutcome::SENT)
+        ->and($outcomes['app_store_build']->status)->toBe(PushOutcome::SENT)
+        ->and($transport->calls)->toBe([
+            ['store_apn', 'production', ['dev_build', 'app_store_build']],
+            ['store_apn', 'sandbox', ['dev_build']],
+        ]);
+});
+
+test('storefront push channel prunes dead tokens and keeps tokens with transient errors', function () {
+    createUserDevicesTable();
+    $dead      = tap(new UserDevice())->forceFill(['uuid' => 'dead_uuid', 'public_id' => 'device_dead', 'user_uuid' => 'user_uuid', 'platform' => 'android', 'token' => 'dead_token', 'status' => 'active']);
+    $dead->save();
+    $transient = tap(new UserDevice())->forceFill(['uuid' => 'transient_uuid', 'public_id' => 'device_transient', 'user_uuid' => 'user_uuid', 'platform' => 'android', 'token' => 'transient_token', 'status' => 'active']);
+    $transient->save();
+    $garbage   = tap(new UserDevice())->forceFill(['uuid' => 'garbage_uuid', 'public_id' => 'device_garbage', 'user_uuid' => 'user_uuid', 'platform' => 'ios', 'token' => 'garbage_token', 'status' => 'active']);
+    $garbage->save();
+
+    $pushChannel = new StorefrontPushChannel(
+        fakeResolver([
+            'fcm' => [pushChannel(['app_key' => 'fcm', 'scheme' => 'fcm'])],
+            'apn' => [pushChannel(['app_key' => 'apn', 'scheme' => 'apn'], ['environment' => 'auto'])],
+        ]),
+        fakeFcm(fn ($channel, array $tokens) => ['dead_token' => PushOutcome::dead('Unregistered'), 'transient_token' => PushOutcome::error('503')]),
+        fakeApn(fn ($channel, $environment, array $tokens) => ['garbage_token' => PushOutcome::wrongEnvironment('BadDeviceToken')])
+    );
+    $notifiable = new class(collect([$dead, $transient, $garbage])) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+
+    $outcomes = $pushChannel->send($notifiable, pushNotification([]));
+
+    expect($outcomes['dead_token']->status)->toBe(PushOutcome::DEAD)
+        ->and($outcomes['transient_token']->status)->toBe(PushOutcome::ERROR)
+        ->and($outcomes['garbage_token']->status)->toBe(PushOutcome::DEAD)
+        ->and(UserDevice::pluck('token')->all())->toBe(['transient_token'])
+        ->and(UserDevice::withTrashed()->where('token', 'dead_token')->value('status'))->toBe('invalid');
+});
+
+test('storefront push channel falls through to the next channel when a provider request throws', function () {
+    $broken  = pushChannel(['app_key' => 'broken', 'scheme' => 'fcm']);
+    $working = pushChannel(['app_key' => 'working', 'scheme' => 'fcm']);
+    $fcm     = fakeFcm(function (NotificationChannel $channel, array $tokens) {
+        if ($channel->app_key === 'broken') {
+            throw new PushConfigurationException('missing "private_key"');
+        }
+
+        return array_fill_keys($tokens, PushOutcome::sent());
+    });
+    $pushChannel = new StorefrontPushChannel(fakeResolver(['fcm' => [$broken, $working]]), $fcm, fakeApn(fn () => []));
+    $notifiable  = new class(collect([pushDevice('android_token', 'android')])) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+
+    $outcomes = $pushChannel->send($notifiable, pushNotification([]));
+
+    expect($outcomes['android_token']->status)->toBe(PushOutcome::SENT)
+        ->and(collect($fcm->calls)->pluck(0)->all())->toBe(['broken', 'working']);
+});
+
+test('storefront push channel is a no-op without devices, channels, a push payload or push support', function () {
+    $fcm         = fakeFcm(fn () => throw new RuntimeException('should not send'));
+    $pushChannel = new StorefrontPushChannel(fakeResolver([]), $fcm, fakeApn(fn () => throw new RuntimeException('should not send')));
+    $withDevices = new class(collect([pushDevice('android_token', 'android'), pushDevice('ios_token', 'ios')])) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+    $withoutDevices = new class(collect()) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+    $silent = new class extends Notification implements SendsPushNotification {
+        public function toPush($notifiable): ?PushMessage
+        {
+            return null;
+        }
+
+        public function pushStorefronts(): array
+        {
+            return [];
+        }
+    };
+
+    expect($pushChannel->send($withDevices, pushNotification([])))->toBe([])
+        ->and($pushChannel->send($withoutDevices, pushNotification([])))->toBe([])
+        ->and($pushChannel->send($withDevices, $silent))->toBe([])
+        ->and($pushChannel->send($withDevices, new class extends Notification {}))->toBe([])
+        ->and($pushChannel->send(null, pushNotification([])))->toBe([])
+        ->and($fcm->calls)->toBe([]);
+});
+
+test('storefront push channel prefers channels of the app the device registered from', function () {
+    $resolver    = fakeResolver(['fcm' => [pushChannel(['app_key' => 'fcm', 'scheme' => 'fcm'])]]);
+    $pushChannel = new StorefrontPushChannel($resolver, fakeFcm(fn ($channel, $tokens) => array_fill_keys($tokens, PushOutcome::sent())), fakeApn(fn () => []));
+    $notifiable  = new class(collect([pushDevice('a', 'android', ['app_identifier' => 'network_uuid']), pushDevice('b', 'android')])) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+
+    $pushChannel->send($notifiable, pushNotification([]));
+
+    expect($resolver->calls)->toBe([['fcm', 'network_uuid'], ['fcm', null]]);
+});
+
+test('credential resolver orders channels by device app, storefront preference and age', function () {
+    $schema = Capsule::schema('mysql');
+    $schema->dropIfExists('notification_channels');
+    $schema->create('notification_channels', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('owner_uuid')->nullable();
+        $table->string('owner_type')->nullable();
+        $table->string('name')->nullable();
+        $table->string('scheme')->nullable();
+        $table->string('app_key')->nullable();
+        $table->text('config')->nullable();
+        $table->text('options')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    Capsule::connection('mysql')->table('notification_channels')->insert([
+        ['uuid' => 'c1', 'owner_uuid' => 'store_uuid', 'scheme' => 'fcm', 'app_key' => 'store_old', 'created_at' => '2024-01-01 00:00:00'],
+        ['uuid' => 'c2', 'owner_uuid' => 'store_uuid', 'scheme' => 'fcm', 'app_key' => 'store_new', 'created_at' => '2025-01-01 00:00:00'],
+        ['uuid' => 'c3', 'owner_uuid' => 'network_uuid', 'scheme' => 'fcm', 'app_key' => 'network', 'created_at' => '2025-06-01 00:00:00'],
+        ['uuid' => 'c4', 'owner_uuid' => 'network_uuid', 'scheme' => 'apn', 'app_key' => 'network_apn', 'created_at' => '2023-01-01 00:00:00'],
+        ['uuid' => 'c5', 'owner_uuid' => 'other_store', 'scheme' => 'fcm', 'app_key' => 'other', 'created_at' => '2020-01-01 00:00:00'],
+    ]);
+
+    $store    = tap(new Store())->forceFill(['uuid' => 'store_uuid']);
+    $network  = tap(new Network())->forceFill(['uuid' => 'network_uuid']);
+    $resolver = new PushCredentialResolver();
+
+    expect($resolver->channels('fcm', [$network, $store])->pluck('app_key')->all())->toBe(['network', 'store_old', 'store_new'])
+        ->and($resolver->channels('fcm', [$network, $store], 'store_uuid')->pluck('app_key')->all())->toBe(['store_old', 'store_new', 'network'])
+        ->and($resolver->channels('fcm', [$store], 'other_store')->pluck('app_key')->all())->toBe(['other', 'store_old', 'store_new'])
+        ->and($resolver->channels('apn', [$network, $store])->pluck('app_key')->all())->toBe(['network_apn'])
+        ->and($resolver->channels('fcm', []))->toHaveCount(0);
+});
+
+test('credential resolver prefers the network app for marketplace orders', function () {
+    $columns = function ($table) {
+        $table->increments('id');
+        foreach (['uuid', 'public_id', 'company_uuid', 'backdrop_uuid', 'logo_uuid', 'order_config_uuid', 'name', 'description', 'translations', 'website', 'facebook', 'instagram', 'twitter', 'email', 'phone', 'tags', 'currency', 'timezone', 'pod_method', 'options'] as $column) {
+            $table->text($column)->nullable();
+        }
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    };
+    $schema = Capsule::schema('mysql');
+    $schema->dropIfExists('stores');
+    $schema->dropIfExists('networks');
+    $schema->create('stores', $columns);
+    $schema->create('networks', $columns);
+    Capsule::connection('mysql')->table('stores')->insert(['uuid' => 'store_uuid', 'public_id' => 'store_public', 'name' => 'Corner Store']);
+    Capsule::connection('mysql')->table('networks')->insert(['uuid' => 'network_uuid', 'public_id' => 'network_public', 'name' => 'Marketplace']);
+
+    $order = new Order();
+    $order->forceFill(['meta' => ['storefront_id' => 'store_public', 'storefront_network_id' => 'network_public']]);
+    $storeOrder = new Order();
+    $storeOrder->forceFill(['meta' => ['storefront_id' => 'store_public']]);
+    $masterOrder = new Order();
+    $masterOrder->forceFill(['meta' => ['storefront_id' => 'network_public', 'storefront_network_id' => 'network_public']]);
+
+    expect(collect(PushCredentialResolver::storefrontsForOrder($order))->pluck('uuid')->all())->toBe(['network_uuid', 'store_uuid'])
+        ->and(collect(PushCredentialResolver::storefrontsForOrder($storeOrder))->pluck('uuid')->all())->toBe(['store_uuid'])
+        ->and(collect(PushCredentialResolver::storefrontsForOrder($masterOrder))->pluck('uuid')->all())->toBe(['network_uuid'])
+        ->and(PushCredentialResolver::storefrontsForOrder(new Order()))->toBe([]);
+});
+
+test('platform names are normalized', function () {
+    expect(StorefrontPushChannel::normalizePlatform('iOS'))->toBe('ios')
+        ->and(StorefrontPushChannel::normalizePlatform(' ANDROID '))->toBe('android')
+        ->and(StorefrontPushChannel::normalizePlatform('ipados'))->toBe('ios')
+        ->and(StorefrontPushChannel::normalizePlatform('web'))->toBeNull()
+        ->and(StorefrontPushChannel::normalizePlatform(null))->toBeNull();
+});
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index e5bc11bc..353e68b9 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -153,6 +153,14 @@ storefront:
         name-text: Give your notification channel a name, this will only be relevent internally
         key: Channel Key
         key-text: This is your notification channel key, use this to specify which apps should utilize this notification channel via sdk configs.
+        environment-help-text: Auto tries production first and retries sandbox (development builds) when Apple rejects the device token.
+        android-channel-id-help-text: Optional Android notification channel ID. Leave empty to use the app's default channel.
+      test-notification-channel:
+        token: Device token
+        token-text: Paste an FCM registration token (Android) or APNs device token (iOS) from a device running your app.
+        environment: APNs environment
+        environment-text: Leave empty to try the channel's configured environments.
+        result: Provider result
       create-product-category:
         name: Category name
         name-text: Enter a name for category
@@ -658,6 +666,11 @@ storefront:
       notification-settings: Notification Settings
       notification-storefront: Configure notification channels for your storefront, each notification channel additionally can have it's own rules and options.
       new-channel: New channel
+      send-test: Send test
+      send-test-push: Send a test push notification
+      send-test-push-button: Send test push
+      test-push-sent: Test push notification was delivered to the provider.
+      test-push-failed: Test push notification failed, see the provider result below.
   service:
     storefront:
       new-incoming-order: You have a new incoming order!

From 28fdf2d03f8a8f10a23295e2b62d8359ebe61dfb Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 16:14:39 +0800
Subject: [PATCH 2/8] test: cover the push transports, message setters and
 delivery fallbacks

Codecov requires full patch coverage. Cover the FCM and APNs transport
send paths, PushMessage setters, APNs environment short-circuit, explicit
push routes, and pruning/logging failure handling. Read device
attributes with data_get so devices returned by a custom push route do
not need to be Eloquent models, and drop two unreachable branches.
---
 .../Controllers/v1/CustomerController.php     |   6 +-
 server/src/Push/FirebaseMessagingFactory.php  |   6 +-
 server/src/Push/StorefrontPushChannel.php     |   4 +-
 .../CustomerDeviceRegistrationTest.php        |   9 +
 .../NotificationContractsTest.php             |  18 ++
 server/tests/Unit/Push/PushLayerTest.php      | 185 ++++++++++++++++++
 6 files changed, 216 insertions(+), 12 deletions(-)

diff --git a/server/src/Http/Controllers/v1/CustomerController.php b/server/src/Http/Controllers/v1/CustomerController.php
index 9bc5b79a..1aa827e4 100644
--- a/server/src/Http/Controllers/v1/CustomerController.php
+++ b/server/src/Http/Controllers/v1/CustomerController.php
@@ -134,11 +134,7 @@ public function unregisterDevice(Request $request)
      */
     protected static function userDeviceColumns(): array
     {
-        try {
-            return (new UserDevice())->getConnection()->getSchemaBuilder()->getColumnListing('user_devices');
-        } catch (\Throwable $e) {
-            return [];
-        }
+        return (new UserDevice())->getConnection()->getSchemaBuilder()->getColumnListing('user_devices');
     }
 
     /**
diff --git a/server/src/Push/FirebaseMessagingFactory.php b/server/src/Push/FirebaseMessagingFactory.php
index 99bcf42a..beed569d 100644
--- a/server/src/Push/FirebaseMessagingFactory.php
+++ b/server/src/Push/FirebaseMessagingFactory.php
@@ -42,7 +42,7 @@ protected function createMessaging(array $serviceAccount): Messaging
     /**
      * Decode and normalize the service account stored on the channel.
      *
-     * Accepts the JSON string pasted in the console, an already decoded array/object, and
+     * Accepts the JSON string pasted in the console or an already decoded array, and
      * repairs private keys whose newlines were escaped (`\\n`) during copy/paste.
      *
      * @throws PushConfigurationException
@@ -52,10 +52,6 @@ public static function serviceAccountFromChannel(NotificationChannel $channel):
         $config      = (array) $channel->config;
         $credentials = $config['firebase_credentials_json'] ?? $config['credentials'] ?? null;
 
-        if (is_object($credentials)) {
-            $credentials = json_decode(json_encode($credentials), true);
-        }
-
         if (is_string($credentials)) {
             $decoded = json_decode(trim($credentials), true);
             if (!is_array($decoded)) {
diff --git a/server/src/Push/StorefrontPushChannel.php b/server/src/Push/StorefrontPushChannel.php
index cf0d2a72..a56e2edf 100644
--- a/server/src/Push/StorefrontPushChannel.php
+++ b/server/src/Push/StorefrontPushChannel.php
@@ -54,7 +54,7 @@ public function send($notifiable, Notification $notification): array
 
         $outcomes = [];
         foreach ($devices->groupBy(fn ($device) => static::normalizePlatform($device->platform)) as $platform => $platformDevices) {
-            foreach ($platformDevices->groupBy(fn ($device) => $device->getAttribute('app_identifier') ?? '') as $appIdentifier => $group) {
+            foreach ($platformDevices->groupBy(fn ($device) => data_get($device, 'app_identifier') ?? '') as $appIdentifier => $group) {
                 $outcomes += match ($platform) {
                     'android' => $this->sendToAndroid($group, $message, $storefronts, $appIdentifier ?: null),
                     'ios'     => $this->sendToIos($group, $message, $storefronts, $appIdentifier ?: null),
@@ -81,7 +81,7 @@ protected function sendToIos(Collection $devices, PushMessage $message, array $s
         $outcomes = [];
 
         // Devices that registered their APNs environment are sent to that environment only.
-        foreach ($devices->groupBy(fn ($device) => $device->getAttribute('environment') ?? '') as $deviceEnvironment => $group) {
+        foreach ($devices->groupBy(fn ($device) => data_get($device, 'environment') ?? '') as $deviceEnvironment => $group) {
             $outcomes += $this->deliver(
                 $group,
                 $channels,
diff --git a/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php b/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
index 0ca0a0a6..7ecded9c 100644
--- a/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
+++ b/server/tests/Unit/Http/Controllers/CustomerDeviceRegistrationTest.php
@@ -97,6 +97,15 @@ function deviceRegistrationRequest(string $secret, array $input): Request
         ->and(UserDevice::query()->count())->toBe(0);
 });
 
+test('device registration requires the customer to have a user account', function () {
+    bootDeviceRegistrationCustomer('33333333-3333-4333-8333-333333333333', '', 'userless-secret');
+    Model::getConnectionResolver()->connection('mysql')->table('contacts')->where('uuid', '33333333-3333-4333-8333-333333333333')->update(['user_uuid' => null]);
+
+    $response = (new CustomerController())->registerDevice(deviceRegistrationRequest('userless-secret', ['token' => 'abc', 'platform' => 'ios']));
+
+    expect($response->getData(true))->toBe(['error' => 'Unable to register device for customer without a user account.']);
+});
+
 test('device registration normalizes the platform and reassigns a token to the latest customer', function () {
     $controller = new CustomerController();
 
diff --git a/server/tests/Unit/Notifications/NotificationContractsTest.php b/server/tests/Unit/Notifications/NotificationContractsTest.php
index 8ee760ee..9e377f97 100644
--- a/server/tests/Unit/Notifications/NotificationContractsTest.php
+++ b/server/tests/Unit/Notifications/NotificationContractsTest.php
@@ -367,3 +367,21 @@ function notificationOrder(array $meta = []): Order
         ->and($push->data)->toBe(['type' => 'promotional', 'store' => 'store_uuid', 'store_id' => 'store_public'])
         ->and(collect($notification->pushStorefronts())->pluck('uuid')->all())->toBe(['store_uuid', 'network_uuid']);
 });
+
+test('promotional notifications still use the store app when network membership cannot be loaded', function () {
+    Illuminate\Database\Capsule\Manager::schema('mysql')->dropIfExists('network_stores');
+    Illuminate\Database\Capsule\Manager::schema('mysql')->dropIfExists('networks');
+
+    $store = new Store();
+    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public']);
+
+    expect(collect((new PromotionalPushNotification('Sale', 'Save now', $store))->pushStorefronts())->pluck('uuid')->all())->toBe(['store_uuid']);
+});
+
+test('order notifications fall back to their storefront when the order has no storefront metadata', function () {
+    $store = new Store();
+    $store->forceFill(['uuid' => 'store_uuid', 'public_id' => 'store_public', 'name' => 'Corner Store']);
+    $notification = notificationWithoutConstructor(StorefrontOrderAccepted::class, notificationOrder(), $store);
+
+    expect(collect($notification->pushStorefronts())->pluck('uuid')->all())->toBe(['store_uuid']);
+});
diff --git a/server/tests/Unit/Push/PushLayerTest.php b/server/tests/Unit/Push/PushLayerTest.php
index 249aa7b9..44160362 100644
--- a/server/tests/Unit/Push/PushLayerTest.php
+++ b/server/tests/Unit/Push/PushLayerTest.php
@@ -524,3 +524,188 @@ public function __construct(public $devices)
         ->and(StorefrontPushChannel::normalizePlatform('web'))->toBeNull()
         ->and(StorefrontPushChannel::normalizePlatform(null))->toBeNull();
 });
+
+test('push message fluent setters render into both provider payloads', function () {
+    $message = PushMessage::create('Order ready', 'Collect it now')
+        ->data(['id' => 'order_public'])
+        ->data(['type' => 'order_ready'])
+        ->badge(3)
+        ->sound('chime.caf')
+        ->image('https://example.test/order.png')
+        ->category('view_order')
+        ->collapseKey('order_public');
+
+    $fcm = $message->toFcmArray();
+    $apn = json_decode(json_encode($message->toApnPayload()), true);
+
+    expect($message->data)->toBe(['id' => 'order_public', 'type' => 'order_ready'])
+        ->and($fcm['notification']['image'])->toBe('https://example.test/order.png')
+        ->and($fcm['android']['collapse_key'])->toBe('order_public')
+        ->and($fcm['android']['notification'])->toMatchArray(['sound' => 'chime.caf', 'click_action' => 'view_order', 'tag' => 'order_public'])
+        ->and($fcm['apns']['payload']['aps'])->toBe(['sound' => 'chime.caf', 'badge' => 3, 'category' => 'view_order'])
+        ->and($apn['aps'])->toMatchArray(['sound' => 'chime.caf', 'badge' => 3, 'category' => 'view_order', 'mutable-content' => 1]);
+
+    $silent = json_decode(json_encode(PushMessage::create('Hi', 'There')->sound(null)->badge(null)->toApnPayload()), true);
+
+    expect($silent['aps'])->not->toHaveKey('sound')
+        ->and($silent['aps'])->not->toHaveKey('badge');
+});
+
+test('FCM transport multicasts the rendered message and maps each token report', function () {
+    $messaging = $this->createMock(Kreait\Firebase\Contract\Messaging::class);
+    $messaging->expects($this->once())
+        ->method('sendMulticast')
+        ->with(
+            $this->callback(fn ($message) => $message instanceof Kreait\Firebase\Messaging\CloudMessage
+                && data_get($message->jsonSerialize(), 'android.notification.channel_id') === 'orders'),
+            ['ok_token', 'dead_token']
+        )
+        ->willReturn(Kreait\Firebase\Messaging\MulticastSendReport::withItems([
+            SendReport::success(MessageTarget::with(MessageTarget::TOKEN, 'ok_token'), ['name' => 'projects/x/messages/1']),
+            SendReport::failure(MessageTarget::with(MessageTarget::TOKEN, 'dead_token'), new NotFound('Requested entity was not found.')),
+        ]));
+    $factory = new class($messaging) extends FirebaseMessagingFactory {
+        public function __construct(public $messaging)
+        {
+        }
+
+        public function make(NotificationChannel $channel): Kreait\Firebase\Contract\Messaging
+        {
+            return $this->messaging;
+        }
+    };
+    $transport = new FcmTransport($factory);
+    $channel   = pushChannel(['app_key' => 'fcm', 'scheme' => 'fcm'], ['android_channel_id' => 'orders']);
+
+    $outcomes = $transport->send($channel, PushMessage::create('Order ready', 'Collect it now'), ['ok_token', 'dead_token']);
+
+    expect(collect($outcomes)->map->status->all())->toBe(['ok_token' => PushOutcome::SENT, 'dead_token' => PushOutcome::DEAD])
+        ->and($transport->send($channel, PushMessage::create('Hi', 'There'), []))->toBe([]);
+});
+
+test('FCM invalid registration arguments are treated as dead tokens', function () {
+    $report = SendReport::failure(
+        MessageTarget::with(MessageTarget::TOKEN, 'token'),
+        new Kreait\Firebase\Exception\Messaging\InvalidArgument('The registration token is not valid')
+    );
+
+    expect(FcmTransport::outcomeFor($report)->status)->toBe(PushOutcome::DEAD);
+});
+
+test('APNs transport queues a high priority notification per token and maps each response', function () {
+    $client = $this->createMock(Pushok\Client::class);
+    $queued = [];
+    $client->expects($this->exactly(2))
+        ->method('addNotification')
+        ->willReturnCallback(function (Pushok\Notification $notification) use (&$queued) {
+            $queued[] = [$notification->getDeviceToken(), $notification->getPriority(), $notification->getCollapseId()];
+        });
+    $client->method('push')->willReturn([
+        new Pushok\Response(200, '', '', 'ok_token'),
+        new Pushok\Response(410, '', json_encode(['reason' => 'Unregistered']), 'gone_token'),
+    ]);
+    $factory = new class($client) extends ApnClientFactory {
+        public ?string $environment = null;
+
+        public function __construct(public $client)
+        {
+        }
+
+        public function make(NotificationChannel $channel, string $environment): Pushok\Client
+        {
+            $this->environment = $environment;
+
+            return $this->client;
+        }
+    };
+    $transport = new ApnTransport($factory);
+    $channel   = pushChannel(['app_key' => 'apn', 'scheme' => 'apn']);
+
+    $outcomes = $transport->send($channel, 'sandbox', PushMessage::create('Order ready', 'Collect it now')->collapseKey(str_repeat('k', 80)), ['ok_token', 'gone_token']);
+
+    expect(collect($outcomes)->map->status->all())->toBe(['ok_token' => PushOutcome::SENT, 'gone_token' => PushOutcome::DEAD])
+        ->and($factory->environment)->toBe('sandbox')
+        ->and($queued)->toBe([
+            ['ok_token', Pushok\Notification::PRIORITY_HIGH, str_repeat('k', 64)],
+            ['gone_token', Pushok\Notification::PRIORITY_HIGH, str_repeat('k', 64)],
+        ])
+        ->and($transport->send($channel, 'sandbox', PushMessage::create('Hi', 'There'), []))->toBe([]);
+});
+
+test('storefront push channel stops walking APNs environments once every token is delivered', function () {
+    $transport   = fakeApn(fn ($channel, $environment, array $tokens) => array_fill_keys($tokens, PushOutcome::sent()));
+    $pushChannel = new StorefrontPushChannel(fakeResolver(['apn' => [pushChannel(['app_key' => 'apn', 'scheme' => 'apn'], ['environment' => 'auto'])]]), fakeFcm(fn () => []), $transport);
+    $notifiable  = new class(collect([pushDevice('ios_token', 'ios')])) {
+        public function __construct(public $devices)
+        {
+        }
+    };
+
+    $pushChannel->send($notifiable, pushNotification([]));
+
+    expect($transport->calls)->toBe([['apn', 'production', ['ios_token']]]);
+});
+
+test('storefront push channel prefers an explicit push route and survives failing notifications', function () {
+    $fcm         = fakeFcm(fn ($channel, array $tokens) => array_fill_keys($tokens, PushOutcome::sent()));
+    $pushChannel = new StorefrontPushChannel(fakeResolver(['fcm' => [pushChannel(['app_key' => 'fcm', 'scheme' => 'fcm'])]]), $fcm, fakeApn(fn () => []));
+    $notifiable  = new class {
+        public $devices = [];
+
+        public function routeNotificationForStorefrontPush(): array
+        {
+            return [pushDevice('routed_token', 'android')];
+        }
+    };
+    $failing = new class extends Notification implements SendsPushNotification {
+        public function toPush($notifiable): ?PushMessage
+        {
+            throw new RuntimeException('payload failure');
+        }
+
+        public function pushStorefronts(): array
+        {
+            return [];
+        }
+    };
+
+    expect(array_keys($pushChannel->send($notifiable, pushNotification([]))))->toBe(['routed_token'])
+        ->and($pushChannel->send($notifiable, $failing))->toBe([]);
+});
+
+test('storefront push channel pruning tolerates non-model devices, storage failures and logger failures', function () {
+    $schema = Capsule::schema('mysql');
+    $schema->dropIfExists('user_devices');
+    $unsaved = tap(new UserDevice())->forceFill(['uuid' => 'unsaved_uuid', 'platform' => 'android', 'token' => 'unsaved_token', 'status' => 'active']);
+    $plain   = (object) ['token' => 'plain_token', 'platform' => 'android', 'status' => 'active'];
+
+    $app      = Illuminate\Container\Container::getInstance();
+    $original = $app->make('log');
+    $app->instance('log', new class {
+        public function __call($method, $arguments)
+        {
+            throw new RuntimeException('logger unavailable');
+        }
+    });
+    Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+
+    try {
+        $pushChannel = new StorefrontPushChannel(
+            fakeResolver(['fcm' => [pushChannel(['app_key' => 'fcm', 'scheme' => 'fcm'])]]),
+            fakeFcm(fn ($channel, array $tokens) => array_fill_keys($tokens, PushOutcome::dead('Unregistered'))),
+            fakeApn(fn () => [])
+        );
+        $notifiable = new class(collect([$unsaved, $plain])) {
+            public function __construct(public $devices)
+            {
+            }
+        };
+
+        $outcomes = $pushChannel->send($notifiable, pushNotification([]));
+    } finally {
+        $app->instance('log', $original);
+        Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+    }
+
+    expect(collect($outcomes)->map->status->all())->toBe(['unsaved_token' => PushOutcome::DEAD, 'plain_token' => PushOutcome::DEAD]);
+});

From 467a42059170c1e6446ee41437abfb76ccdce9d3 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 16:08:10 +0800
Subject: [PATCH 3/8] feat: add a customer notifications inbox API

Storefront order notifications were already stored in the core
notifications table, but customers had no way to read them. Add
storefront/v1/notifications endpoints for the authenticated customer to
list (filter by unread/type, limit/offset), count unread, read, mark as
read, mark all as read and delete their notifications, scoped to the
storefront app (store, or network and its member stores).

Add customer notification preferences (order update pushes, promotions)
stored on the contact meta and honored by the notifications, and
broadcast new notifications in realtime on contact.{uuid} through a
broadcast channel that never fails the send.
---
 .../Controllers/v1/NotificationController.php | 204 +++++++++++
 .../Resources/v1/CustomerNotification.php     |  34 ++
 .../Channels/SafeBroadcastChannel.php         |  31 ++
 .../PromotionalPushNotification.php           |  26 +-
 .../StorefrontOrderNotification.php           |  31 +-
 .../Support/CustomerNotificationPresenter.php |  47 +++
 .../src/Support/NotificationPreferences.php   |  57 ++++
 server/src/routes.php                         |  12 +
 .../CustomerNotificationInboxTest.php         | 323 ++++++++++++++++++
 .../NotificationContractsTest.php             |   4 +-
 10 files changed, 764 insertions(+), 5 deletions(-)
 create mode 100644 server/src/Http/Controllers/v1/NotificationController.php
 create mode 100644 server/src/Http/Resources/v1/CustomerNotification.php
 create mode 100644 server/src/Notifications/Channels/SafeBroadcastChannel.php
 create mode 100644 server/src/Support/CustomerNotificationPresenter.php
 create mode 100644 server/src/Support/NotificationPreferences.php
 create mode 100644 server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php

diff --git a/server/src/Http/Controllers/v1/NotificationController.php b/server/src/Http/Controllers/v1/NotificationController.php
new file mode 100644
index 00000000..fcf9eb80
--- /dev/null
+++ b/server/src/Http/Controllers/v1/NotificationController.php
@@ -0,0 +1,204 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers\v1;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Http\Controllers\Controller;
+use Fleetbase\Models\Notification;
+use Fleetbase\Storefront\Http\Resources\v1\CustomerNotification;
+use Fleetbase\Storefront\Models\Customer;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Support\NotificationPreferences;
+use Fleetbase\Storefront\Support\Storefront;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\Request;
+
+/**
+ * The authenticated customer's notification inbox.
+ */
+class NotificationController extends Controller
+{
+    /**
+     * List the customer's notifications, newest first.
+     *
+     * Query params: `unread` (bool), `type`, `limit` (default 25, max 100), `offset`.
+     */
+    public function query(Request $request)
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to view customer notifications', 401);
+        }
+
+        $limit  = min(max((int) $request->input('limit', 25), 1), 100);
+        $offset = max((int) $request->input('offset', 0), 0);
+
+        $notifications = $this->inbox($customer)
+            ->when($request->boolean('unread'), fn ($query) => $query->whereNull('read_at'))
+            ->when($request->filled('type'), fn ($query) => $query->where('data->type', $request->input('type')))
+            ->orderByDesc('created_at')
+            ->skip($offset)
+            ->take($limit)
+            ->get();
+
+        return CustomerNotification::collection($notifications);
+    }
+
+    /**
+     * Number of unread notifications, for badges.
+     */
+    public function unreadCount()
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to view customer notifications', 401);
+        }
+
+        return response()->json(['count' => $this->inbox($customer)->whereNull('read_at')->count()]);
+    }
+
+    public function find(string $id)
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to view customer notifications', 401);
+        }
+
+        $notification = $this->inbox($customer)->where('id', $id)->first();
+        if (!$notification) {
+            return response()->apiError('Notification not found.', 404);
+        }
+
+        return new CustomerNotification($notification);
+    }
+
+    public function markAsRead(string $id)
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to update customer notifications', 401);
+        }
+
+        $notification = $this->inbox($customer)->where('id', $id)->first();
+        if (!$notification) {
+            return response()->apiError('Notification not found.', 404);
+        }
+
+        if ($notification->read_at === null) {
+            $notification->forceFill(['read_at' => now()])->save();
+        }
+
+        return new CustomerNotification($notification);
+    }
+
+    public function markAllAsRead()
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to update customer notifications', 401);
+        }
+
+        $updated = $this->inbox($customer)->whereNull('read_at')->update(['read_at' => now()]);
+
+        return response()->json(['status' => 'OK', 'updated' => $updated]);
+    }
+
+    public function delete(string $id)
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to delete customer notifications', 401);
+        }
+
+        $deleted = $this->inbox($customer)->where('id', $id)->delete();
+        if (!$deleted) {
+            return response()->apiError('Notification not found.', 404);
+        }
+
+        return response()->json(['status' => 'OK', 'id' => $id, 'deleted' => true]);
+    }
+
+    public function getPreferences()
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to view notification preferences', 401);
+        }
+
+        return response()->json(NotificationPreferences::for($customer));
+    }
+
+    public function updatePreferences(Request $request)
+    {
+        $customer = $this->customer();
+        if (!$customer) {
+            return response()->apiError('Not authorized to update notification preferences', 401);
+        }
+
+        foreach (array_keys(NotificationPreferences::DEFAULTS) as $key) {
+            if ($request->has($key) && filter_var($request->input($key), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) === null) {
+                return response()->apiError('The ' . $key . ' preference must be true or false.');
+            }
+        }
+
+        return response()->json(NotificationPreferences::update($customer, $request->only(array_keys(NotificationPreferences::DEFAULTS))));
+    }
+
+    protected function customer(): ?Contact
+    {
+        return Storefront::getCustomerFromToken();
+    }
+
+    /**
+     * Notifications addressed to the customer, limited to the current storefront app.
+     *
+     * A notification belongs to the app when it references the app's store, network or one of
+     * the network's member stores. Notifications that reference no storefront are shown in every
+     * app of the customer's company.
+     */
+    protected function inbox(Contact $customer): Builder
+    {
+        $storefrontIds = $this->storefrontPublicIds();
+
+        return Notification::query()
+            ->whereIn('notifiable_type', [Contact::class, Customer::class])
+            ->where('notifiable_id', $customer->uuid)
+            ->when(!empty($storefrontIds), function ($query) use ($storefrontIds) {
+                $query->where(function ($query) use ($storefrontIds) {
+                    foreach (['store_id', 'network_id', 'storefront_id'] as $key) {
+                        $query->orWhereIn('data->' . $key, $storefrontIds);
+                    }
+
+                    $query->orWhere(function ($query) {
+                        $query->whereNull('data->store_id')->whereNull('data->network_id')->whereNull('data->storefront_id');
+                    });
+                });
+            });
+    }
+
+    /**
+     * Public ids of the storefront the request was made with (a store, or a network and its member stores).
+     *
+     * @return string[]
+     */
+    protected function storefrontPublicIds(): array
+    {
+        if ($storeUuid = session('storefront_store')) {
+            return Store::where('uuid', $storeUuid)->pluck('public_id')->all();
+        }
+
+        if ($networkUuid = session('storefront_network')) {
+            $network = Network::where('uuid', $networkUuid)->first(['uuid', 'public_id']);
+            if (!$network) {
+                return [];
+            }
+
+            $storeIds = Store::whereHas('networks', fn ($query) => $query->where('network_uuid', $networkUuid))->pluck('public_id')->all();
+
+            return array_values(array_unique(array_merge([$network->public_id], $storeIds)));
+        }
+
+        return [];
+    }
+}
diff --git a/server/src/Http/Resources/v1/CustomerNotification.php b/server/src/Http/Resources/v1/CustomerNotification.php
new file mode 100644
index 00000000..df6e2094
--- /dev/null
+++ b/server/src/Http/Resources/v1/CustomerNotification.php
@@ -0,0 +1,34 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Resources\v1;
+
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Storefront\Support\CustomerNotificationPresenter;
+
+class CustomerNotification extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $data = $this->data;
+        if (is_string($data)) {
+            $data = json_decode($data, true);
+        }
+
+        return array_merge(
+            ['id' => $this->id],
+            CustomerNotificationPresenter::present((array) $data, $this->type),
+            [
+                'is_read'    => $this->read_at !== null,
+                'read_at'    => $this->read_at,
+                'created_at' => $this->created_at,
+            ]
+        );
+    }
+}
diff --git a/server/src/Notifications/Channels/SafeBroadcastChannel.php b/server/src/Notifications/Channels/SafeBroadcastChannel.php
new file mode 100644
index 00000000..273e09b3
--- /dev/null
+++ b/server/src/Notifications/Channels/SafeBroadcastChannel.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Fleetbase\Storefront\Notifications\Channels;
+
+use Illuminate\Notifications\Channels\BroadcastChannel;
+use Illuminate\Notifications\Notification;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Broadcasts a notification in realtime without letting a socket failure fail the send.
+ *
+ * Broadcasting runs after push and database delivery. If it threw, a queued listener would be
+ * retried and the customer would receive the push again, so failures are only logged.
+ */
+class SafeBroadcastChannel extends BroadcastChannel
+{
+    public function send($notifiable, Notification $notification)
+    {
+        try {
+            return parent::send($notifiable, $notification);
+        } catch (\Throwable $e) {
+            try {
+                Log::warning('[Storefront] Unable to broadcast notification.', ['notification' => get_class($notification), 'error' => $e->getMessage()]);
+            } catch (\Throwable $logError) {
+                // Logging must never break delivery.
+            }
+
+            return null;
+        }
+    }
+}
diff --git a/server/src/Notifications/PromotionalPushNotification.php b/server/src/Notifications/PromotionalPushNotification.php
index d0a4c898..0bd5be64 100644
--- a/server/src/Notifications/PromotionalPushNotification.php
+++ b/server/src/Notifications/PromotionalPushNotification.php
@@ -3,10 +3,14 @@
 namespace Fleetbase\Storefront\Notifications;
 
 use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel;
 use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
 use Fleetbase\Storefront\Push\PushMessage;
 use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Support\CustomerNotificationPresenter;
+use Fleetbase\Storefront\Support\NotificationPreferences;
 use Illuminate\Bus\Queueable;
+use Illuminate\Notifications\Messages\BroadcastMessage;
 use Illuminate\Notifications\Notification;
 
 class PromotionalPushNotification extends Notification implements SendsPushNotification
@@ -57,7 +61,27 @@ public function __construct(string $title, string $body, Store $store)
      */
     public function via($notifiable): array
     {
-        return [StorefrontPushChannel::class, 'database'];
+        if (!NotificationPreferences::allows($notifiable, 'promotions')) {
+            return [];
+        }
+
+        return [StorefrontPushChannel::class, 'database', SafeBroadcastChannel::class];
+    }
+
+    /**
+     * Realtime payload sent to the customer's `contact.{uuid}` channel.
+     */
+    public function toBroadcast($notifiable): BroadcastMessage
+    {
+        return new BroadcastMessage(CustomerNotificationPresenter::present($this->toArray($notifiable), static::class));
+    }
+
+    /**
+     * The broadcast event uses this as the payload `type`, so keep it equal to the inbox item type.
+     */
+    public function broadcastType(): string
+    {
+        return 'promotional';
     }
 
     /**
diff --git a/server/src/Notifications/StorefrontOrderNotification.php b/server/src/Notifications/StorefrontOrderNotification.php
index 690a8265..22e2f6dd 100644
--- a/server/src/Notifications/StorefrontOrderNotification.php
+++ b/server/src/Notifications/StorefrontOrderNotification.php
@@ -5,12 +5,16 @@
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\Storefront\Models\Network;
 use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel;
 use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
 use Fleetbase\Storefront\Push\PushCredentialResolver;
 use Fleetbase\Storefront\Push\PushMessage;
 use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Support\CustomerNotificationPresenter;
+use Fleetbase\Storefront\Support\NotificationPreferences;
 use Fleetbase\Storefront\Support\Storefront;
 use Illuminate\Bus\Queueable;
+use Illuminate\Notifications\Messages\BroadcastMessage;
 use Illuminate\Notifications\Messages\MailMessage;
 use Illuminate\Notifications\Notification;
 
@@ -70,11 +74,34 @@ public function __construct(Order $order)
     /**
      * Get the notification's delivery channels.
      *
-     * Push is sent first and never throws, so mail or database failures cannot stop it.
+     * Push is sent first and never throws, so mail or database failures cannot stop it. The
+     * customer can turn order update pushes off; the inbox copy is always kept.
      */
     public function via($notifiable): array
     {
-        return [StorefrontPushChannel::class, 'database', 'mail'];
+        $channels = [];
+        if (NotificationPreferences::allows($notifiable, 'order_updates')) {
+            $channels[] = StorefrontPushChannel::class;
+        }
+
+        return [...$channels, 'database', 'mail', SafeBroadcastChannel::class];
+    }
+
+    /**
+     * Realtime payload sent to the customer's `contact.{uuid}` channel. Mirrors an inbox item,
+     * without the recipient details stored in the database copy.
+     */
+    public function toBroadcast($notifiable): BroadcastMessage
+    {
+        return new BroadcastMessage(CustomerNotificationPresenter::present($this->toArray($notifiable), static::class));
+    }
+
+    /**
+     * The broadcast event uses this as the payload `type`, so keep it equal to the inbox item type.
+     */
+    public function broadcastType(): string
+    {
+        return $this->status;
     }
 
     /**
diff --git a/server/src/Support/CustomerNotificationPresenter.php b/server/src/Support/CustomerNotificationPresenter.php
new file mode 100644
index 00000000..813b41b5
--- /dev/null
+++ b/server/src/Support/CustomerNotificationPresenter.php
@@ -0,0 +1,47 @@
+<?php
+
+namespace Fleetbase\Storefront\Support;
+
+use Illuminate\Support\Arr;
+use Illuminate\Support\Str;
+
+/**
+ * Normalizes stored storefront notification payloads into the customer inbox shape.
+ *
+ * Handles current payloads (type/title/body) as well as rows written before they existed,
+ * where order notifications stored the status code in `message` and the title in `subject`.
+ */
+class CustomerNotificationPresenter
+{
+    /**
+     * Payload keys that are presentation or recipient details rather than deep-link data.
+     */
+    protected const HIDDEN_KEYS = [
+        'notifiable', 'notification_id', 'sent_at', 'type', 'title', 'body', 'subject', 'message', 'image',
+        'id', 'email', 'phone', 'companyId', 'company', 'storefront', 'order', 'store',
+    ];
+
+    public static function present(array $data, ?string $notificationClass = null): array
+    {
+        $message      = $data['message'] ?? null;
+        $legacyStatus = is_string($message) && preg_match('/^order_[a-z_]+$/', $message) ? $message : null;
+
+        $type  = $data['type'] ?? $legacyStatus ?? ($notificationClass ? Str::snake(class_basename($notificationClass)) : 'notification');
+        $title = $data['title'] ?? $data['subject'] ?? null;
+        $body  = $data['body'] ?? ($legacyStatus ? null : $message);
+
+        if ($title && !$body) {
+            $body = $title;
+        }
+
+        $payload = Arr::except($data, static::HIDDEN_KEYS);
+
+        return [
+            'type'  => $type,
+            'title' => $title,
+            'body'  => $body,
+            'image' => $data['image'] ?? null,
+            'data'  => $payload,
+        ];
+    }
+}
diff --git a/server/src/Support/NotificationPreferences.php b/server/src/Support/NotificationPreferences.php
new file mode 100644
index 00000000..6ba1384e
--- /dev/null
+++ b/server/src/Support/NotificationPreferences.php
@@ -0,0 +1,57 @@
+<?php
+
+namespace Fleetbase\Storefront\Support;
+
+/**
+ * Customer notification preferences, stored on the customer contact's meta.
+ *
+ * - `order_updates`: push notifications about the customer's orders. Order updates are
+ *   always kept in the inbox, only the push can be turned off.
+ * - `promotions`: promotional notifications, both push and inbox.
+ */
+class NotificationPreferences
+{
+    public const META_KEY = 'notification_preferences';
+
+    public const DEFAULTS = [
+        'order_updates' => true,
+        'promotions'    => true,
+    ];
+
+    public static function for($notifiable): array
+    {
+        $stored = [];
+        if (is_object($notifiable) && method_exists($notifiable, 'getMeta')) {
+            $stored = (array) $notifiable->getMeta(static::META_KEY, []);
+        }
+
+        $preferences = [];
+        foreach (static::DEFAULTS as $key => $default) {
+            $preferences[$key] = array_key_exists($key, $stored) ? filter_var($stored[$key], FILTER_VALIDATE_BOOLEAN) : $default;
+        }
+
+        return $preferences;
+    }
+
+    public static function allows($notifiable, string $preference): bool
+    {
+        return static::for($notifiable)[$preference] ?? true;
+    }
+
+    /**
+     * Merge the known preference keys from the input into the notifiable's stored preferences.
+     */
+    public static function update($notifiable, array $input): array
+    {
+        $preferences = static::for($notifiable);
+        foreach (array_keys(static::DEFAULTS) as $key) {
+            if (array_key_exists($key, $input)) {
+                $preferences[$key] = filter_var($input[$key], FILTER_VALIDATE_BOOLEAN);
+            }
+        }
+
+        $notifiable->updateMeta(static::META_KEY, $preferences);
+
+        return $preferences;
+    }
+}
diff --git a/server/src/routes.php b/server/src/routes.php
index f762f4b1..47bf5a37 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -99,6 +99,18 @@ function ($router) {
                     $router->post('receipt', 'OrderController@getReceipt');
                 });
 
+                // storefront/v1/notifications
+                $router->group(['prefix' => 'notifications'], function () use ($router) {
+                    $router->get('/', 'NotificationController@query');
+                    $router->get('unread-count', 'NotificationController@unreadCount');
+                    $router->get('preferences', 'NotificationController@getPreferences');
+                    $router->put('preferences', 'NotificationController@updatePreferences');
+                    $router->put('read-all', 'NotificationController@markAllAsRead');
+                    $router->get('{id}', 'NotificationController@find');
+                    $router->put('{id}/read', 'NotificationController@markAsRead');
+                    $router->delete('{id}', 'NotificationController@delete');
+                });
+
                 // storefront/v1/customers
                 $router->group(['prefix' => 'customers'], function () use ($router) {
                     $router->put('{id}', 'CustomerController@update');
diff --git a/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php b/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php
new file mode 100644
index 00000000..389b9983
--- /dev/null
+++ b/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php
@@ -0,0 +1,323 @@
+<?php
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Storefront\Http\Controllers\v1\NotificationController;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel;
+use Fleetbase\Storefront\Notifications\PromotionalPushNotification;
+use Fleetbase\Storefront\Notifications\StorefrontOrderCompleted;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Support\CustomerNotificationPresenter;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Request;
+use Illuminate\Session\ArraySessionHandler;
+use Illuminate\Session\Store as SessionStore;
+
+const INBOX_CUSTOMER = '11111111-1111-4111-8111-111111111111';
+const INBOX_OTHER    = '22222222-2222-4222-8222-222222222222';
+
+function inboxConnection()
+{
+    return Model::getConnectionResolver()->connection('mysql');
+}
+
+function inboxRequest(?string $secret = 'inbox-secret', array $input = [], string $method = 'GET'): Request
+{
+    $request = Request::create('/notifications', $method, $input);
+    $request->setLaravelSession(new SessionStore('inbox-test', new ArraySessionHandler(120)));
+    if ($secret) {
+        $request->headers->set('Customer-Token', $secret);
+    }
+    app()->instance('request', $request);
+
+    return $request;
+}
+
+function inboxNotification(string $id, string $notifiable, array $data, array $attributes = []): array
+{
+    return array_merge([
+        'id'              => $id,
+        'type'            => StorefrontOrderCompleted::class,
+        'notifiable_type' => Contact::class,
+        'notifiable_id'   => $notifiable,
+        'data'            => json_encode($data),
+        'read_at'         => null,
+        'created_at'      => '2026-09-01 10:00:00',
+        'updated_at'      => '2026-09-01 10:00:00',
+    ], $attributes);
+}
+
+function inboxIds($collection): array
+{
+    return collect($collection->resolve())->pluck('id')->all();
+}
+
+beforeEach(function () {
+    $schema = inboxConnection()->getSchemaBuilder();
+    foreach (['contacts', 'personal_access_tokens', 'notifications', 'stores', 'networks', 'network_stores'] as $table) {
+        $schema->dropIfExists($table);
+    }
+
+    $schema->create('contacts', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('type')->nullable();
+        $table->text('meta')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('personal_access_tokens', function ($table) {
+        $table->increments('id');
+        $table->string('tokenable_type')->nullable();
+        $table->string('tokenable_id')->nullable();
+        $table->string('name');
+        $table->string('token', 64)->unique();
+        $table->text('abilities')->nullable();
+        $table->timestamp('last_used_at')->nullable();
+        $table->timestamp('expires_at')->nullable();
+        $table->timestamps();
+    });
+    $schema->create('notifications', function ($table) {
+        $table->string('id')->primary();
+        $table->string('type');
+        $table->string('notifiable_type');
+        $table->string('notifiable_id');
+        $table->text('data');
+        $table->timestamp('read_at')->nullable();
+        $table->timestamps();
+    });
+    foreach (['stores', 'networks'] as $name) {
+        $schema->create($name, function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('name')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+    }
+    $schema->create('network_stores', function ($table) {
+        $table->increments('id');
+        $table->string('network_uuid')->nullable();
+        $table->string('store_uuid')->nullable();
+        $table->string('category_uuid')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+
+    $db = inboxConnection();
+    $db->table('contacts')->insert([
+        ['uuid' => INBOX_CUSTOMER, 'public_id' => 'contact_inbox', 'user_uuid' => 'user_inbox', 'type' => 'customer', 'meta' => '{}'],
+        ['uuid' => INBOX_OTHER, 'public_id' => 'contact_other', 'user_uuid' => 'user_other', 'type' => 'customer', 'meta' => '{}'],
+    ]);
+    $db->table('personal_access_tokens')->insert([
+        ['name' => INBOX_CUSTOMER, 'token' => hash('sha256', 'inbox-secret'), 'abilities' => '["*"]'],
+        ['name' => INBOX_OTHER, 'token' => hash('sha256', 'other-secret'), 'abilities' => '["*"]'],
+    ]);
+    $db->table('stores')->insert([
+        ['uuid' => 'store_a_uuid', 'public_id' => 'store_a'],
+        ['uuid' => 'store_b_uuid', 'public_id' => 'store_b'],
+        ['uuid' => 'store_c_uuid', 'public_id' => 'store_c'],
+    ]);
+    $db->table('networks')->insert(['uuid' => 'network_uuid', 'public_id' => 'network_m']);
+    $db->table('network_stores')->insert([
+        ['network_uuid' => 'network_uuid', 'store_uuid' => 'store_a_uuid'],
+        ['network_uuid' => 'network_uuid', 'store_uuid' => 'store_b_uuid'],
+    ]);
+
+    $db->table('notifications')->insert([
+        inboxNotification('n_store_a', INBOX_CUSTOMER, [
+            'type' => 'order_completed', 'title' => 'Delivered', 'body' => 'Enjoy!', 'order_id' => 'order_a', 'store_id' => 'store_a', 'email' => 'me@example.test',
+        ], ['created_at' => '2026-09-05 10:00:00']),
+        inboxNotification('n_network', INBOX_CUSTOMER, [
+            'type' => 'order_enroute', 'title' => 'On the way', 'body' => 'Picked up', 'store_id' => 'store_b', 'network_id' => 'network_m',
+        ], ['created_at' => '2026-09-04 10:00:00']),
+        inboxNotification('n_store_c', INBOX_CUSTOMER, [
+            'type' => 'promotional', 'title' => 'Sale', 'body' => 'Store C sale', 'store_id' => 'store_c',
+        ], ['type' => PromotionalPushNotification::class, 'created_at' => '2026-09-03 10:00:00']),
+        inboxNotification('n_generic', INBOX_CUSTOMER, [
+            'title' => 'Welcome', 'body' => 'Hello there',
+        ], ['created_at' => '2026-09-02 10:00:00', 'read_at' => '2026-09-02 11:00:00']),
+        inboxNotification('n_legacy', INBOX_CUSTOMER, [
+            'subject' => 'Your order from Store A has been accepted.', 'message' => 'order_accepted', 'storefront_id' => 'store_a', 'id' => 'contact_inbox',
+        ], ['type' => 'Fleetbase\\Storefront\\Notifications\\StorefrontOrderAccepted', 'created_at' => '2026-09-01 10:00:00']),
+        inboxNotification('n_other_customer', INBOX_OTHER, [
+            'type' => 'order_completed', 'title' => 'Not yours', 'body' => 'Private', 'store_id' => 'store_a',
+        ]),
+    ]);
+
+    session(['storefront_store' => 'store_a_uuid', 'storefront_network' => null]);
+});
+
+test('inbox endpoints require an authenticated customer', function () {
+    $controller = new NotificationController();
+    inboxRequest(null);
+
+    foreach ([
+        $controller->query(request()),
+        $controller->unreadCount(),
+        $controller->find('n_store_a'),
+        $controller->markAsRead('n_store_a'),
+        $controller->markAllAsRead(),
+        $controller->delete('n_store_a'),
+        $controller->getPreferences(),
+        $controller->updatePreferences(request()),
+    ] as $response) {
+        expect($response->getStatusCode())->toBe(401);
+    }
+});
+
+test('a store app lists only the customer notifications for that store, newest first', function () {
+    $items = (new NotificationController())->query(inboxRequest())->resolve();
+
+    expect(collect($items)->pluck('id')->all())->toBe(['n_store_a', 'n_generic', 'n_legacy'])
+        ->and($items[0])->toMatchArray([
+            'type'    => 'order_completed',
+            'title'   => 'Delivered',
+            'body'    => 'Enjoy!',
+            'is_read' => false,
+            'data'    => ['order_id' => 'order_a', 'store_id' => 'store_a'],
+        ])
+        ->and($items[1]['is_read'])->toBeTrue()
+        ->and($items[2])->toMatchArray([
+            'type'  => 'order_accepted',
+            'title' => 'Your order from Store A has been accepted.',
+            'body'  => 'Your order from Store A has been accepted.',
+            'data'  => ['storefront_id' => 'store_a'],
+        ]);
+});
+
+test('a network app lists notifications for the network and its member stores', function () {
+    session(['storefront_store' => null, 'storefront_network' => 'network_uuid']);
+
+    expect(inboxIds((new NotificationController())->query(inboxRequest())))->toBe(['n_store_a', 'n_network', 'n_generic', 'n_legacy']);
+});
+
+test('the inbox supports unread, type and pagination filters', function () {
+    $controller = new NotificationController();
+
+    expect(inboxIds($controller->query(inboxRequest('inbox-secret', ['unread' => '1']))))->toBe(['n_store_a', 'n_legacy'])
+        ->and(inboxIds($controller->query(inboxRequest('inbox-secret', ['type' => 'order_completed']))))->toBe(['n_store_a'])
+        ->and(inboxIds($controller->query(inboxRequest('inbox-secret', ['limit' => 1, 'offset' => 1]))))->toBe(['n_generic']);
+});
+
+test('customers can read, count, mark and delete only their own notifications', function () {
+    $controller = new NotificationController();
+    inboxRequest();
+
+    expect($controller->unreadCount()->getData(true))->toBe(['count' => 2])
+        ->and($controller->find('n_other_customer')->getStatusCode())->toBe(404)
+        ->and($controller->find('n_store_c')->getStatusCode())->toBe(404)
+        ->and($controller->markAsRead('n_other_customer')->getStatusCode())->toBe(404)
+        ->and($controller->delete('n_other_customer')->getStatusCode())->toBe(404);
+
+    $read = $controller->markAsRead('n_store_a')->resolve();
+
+    expect($read['is_read'])->toBeTrue()
+        ->and($controller->unreadCount()->getData(true))->toBe(['count' => 1])
+        ->and($controller->markAllAsRead()->getData(true))->toBe(['status' => 'OK', 'updated' => 1])
+        ->and($controller->unreadCount()->getData(true))->toBe(['count' => 0])
+        ->and(inboxConnection()->table('notifications')->where('id', 'n_store_c')->value('read_at'))->toBeNull()
+        ->and(inboxConnection()->table('notifications')->where('id', 'n_other_customer')->value('read_at'))->toBeNull()
+        ->and($controller->delete('n_generic')->getData(true))->toBe(['status' => 'OK', 'id' => 'n_generic', 'deleted' => true])
+        ->and(inboxConnection()->table('notifications')->where('id', 'n_generic')->exists())->toBeFalse();
+});
+
+test('customers can read and update their notification preferences', function () {
+    $controller = new NotificationController();
+    inboxRequest();
+
+    expect($controller->getPreferences()->getData(true))->toBe(['order_updates' => true, 'promotions' => true]);
+
+    $invalid = $controller->updatePreferences(inboxRequest('inbox-secret', ['promotions' => 'sometimes'], 'PUT'));
+    $updated = $controller->updatePreferences(inboxRequest('inbox-secret', ['promotions' => false, 'ignored' => true], 'PUT'));
+
+    expect($invalid->getStatusCode())->toBe(400)
+        ->and($updated->getData(true))->toBe(['order_updates' => true, 'promotions' => false])
+        ->and(json_decode(inboxConnection()->table('contacts')->where('uuid', INBOX_CUSTOMER)->value('meta'), true))
+        ->toBe(['notification_preferences' => ['order_updates' => true, 'promotions' => false]]);
+});
+
+test('notification preferences control promotional delivery and order update pushes', function () {
+    $store = tap(new Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'name' => 'Store A']);
+    $store->setRelation('networks', collect());
+    $promotion = new PromotionalPushNotification('Sale', 'Save now', $store);
+
+    $optedOut = new Contact();
+    $optedOut->forceFill(['meta' => ['notification_preferences' => ['promotions' => false, 'order_updates' => false]]]);
+    $defaults = new Contact();
+    $defaults->forceFill(['meta' => []]);
+
+    $order = new Fleetbase\FleetOps\Models\Order();
+    $order->forceFill(['meta' => []]);
+    $orderNotification = (new ReflectionClass(StorefrontOrderCompleted::class))->newInstanceWithoutConstructor();
+
+    expect($promotion->via($optedOut))->toBe([])
+        ->and($promotion->via($defaults))->toBe([StorefrontPushChannel::class, 'database', SafeBroadcastChannel::class])
+        ->and($orderNotification->via($optedOut))->toBe(['database', 'mail', SafeBroadcastChannel::class])
+        ->and($orderNotification->via($defaults))->toBe([StorefrontPushChannel::class, 'database', 'mail', SafeBroadcastChannel::class]);
+});
+
+test('realtime payloads mirror inbox items without recipient details', function () {
+    $store     = tap(new Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'name' => 'Store A']);
+    $promotion = new PromotionalPushNotification('Sale', 'Save now', $store);
+
+    expect($promotion->toBroadcast(null)->data)->toBe([
+        'type'  => 'promotional',
+        'title' => 'Sale',
+        'body'  => 'Save now',
+        'image' => null,
+        'data'  => ['store_id' => 'store_a'],
+    ])->and($promotion->broadcastType())->toBe('promotional')
+        ->and(CustomerNotificationPresenter::present([], 'Fleetbase\\Storefront\\Notifications\\SomethingElse'))->toMatchArray(['type' => 'something_else', 'title' => null]);
+});
+
+test('broadcast failures never fail the notification send', function () {
+    $events = new class implements Illuminate\Contracts\Events\Dispatcher {
+        public function listen($events, $listener = null)
+        {
+        }
+
+        public function hasListeners($eventName)
+        {
+            return false;
+        }
+
+        public function subscribe($subscriber)
+        {
+        }
+
+        public function until($event, $payload = [])
+        {
+        }
+
+        public function dispatch($event, $payload = [], $halt = false)
+        {
+            throw new RuntimeException('socket unavailable');
+        }
+
+        public function push($event, $payload = [])
+        {
+        }
+
+        public function flush($event)
+        {
+        }
+
+        public function forget($event)
+        {
+        }
+
+        public function forgetPushed()
+        {
+        }
+    };
+    $store      = tap(new Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'name' => 'Store A']);
+    $notifiable = new Contact();
+    $notifiable->forceFill(['uuid' => INBOX_CUSTOMER]);
+
+    expect((new SafeBroadcastChannel($events))->send($notifiable, new PromotionalPushNotification('Sale', 'Save now', $store)))->toBeNull();
+});
diff --git a/server/tests/Unit/Notifications/NotificationContractsTest.php b/server/tests/Unit/Notifications/NotificationContractsTest.php
index 9e377f97..f7166f32 100644
--- a/server/tests/Unit/Notifications/NotificationContractsTest.php
+++ b/server/tests/Unit/Notifications/NotificationContractsTest.php
@@ -195,7 +195,7 @@ function notificationOrder(array $meta = []): Order
         ->and($notification->status)->toBe($expectedStatus)
         ->and($notification->subject)->not->toBeEmpty()
         ->and($notification->body)->not->toBeEmpty()
-        ->and($notification->via($notifiable))->toBe([StorefrontPushChannel::class, 'database', 'mail'])
+        ->and($notification->via($notifiable))->toBe([StorefrontPushChannel::class, 'database', 'mail', Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel::class])
         ->and($push)->toBeInstanceOf(PushMessage::class)
         ->and($push->title)->toBe($notification->subject)
         ->and($push->body)->toBe($notification->body)
@@ -361,7 +361,7 @@ function notificationOrder(array $meta = []): Order
     $notification = new PromotionalPushNotification('Weekend sale', 'Save now', $store);
     $push         = $notification->toPush(null);
 
-    expect($notification->via(null))->toBe([StorefrontPushChannel::class, 'database'])
+    expect($notification->via(null))->toBe([StorefrontPushChannel::class, 'database', Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel::class])
         ->and($push)->toBeInstanceOf(PushMessage::class)
         ->and($push->title)->toBe('Weekend sale')
         ->and($push->data)->toBe(['type' => 'promotional', 'store' => 'store_uuid', 'store_id' => 'store_public'])

From 1d49ebf7e789f51d185d20f416916d4fa8212043 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 16:16:22 +0800
Subject: [PATCH 4/8] test: cover the inbox lookup, storefront scoping
 fallbacks and broadcasts

Also drop null values from inbox item data, and read notification data
through the model's array cast.
---
 .../Resources/v1/CustomerNotification.php     |  7 +-
 .../Support/CustomerNotificationPresenter.php |  2 +-
 .../CustomerNotificationInboxTest.php         | 96 +++++++++++++++++++
 3 files changed, 98 insertions(+), 7 deletions(-)

diff --git a/server/src/Http/Resources/v1/CustomerNotification.php b/server/src/Http/Resources/v1/CustomerNotification.php
index df6e2094..d8c8bd8c 100644
--- a/server/src/Http/Resources/v1/CustomerNotification.php
+++ b/server/src/Http/Resources/v1/CustomerNotification.php
@@ -16,14 +16,9 @@ class CustomerNotification extends FleetbaseResource
      */
     public function toArray($request)
     {
-        $data = $this->data;
-        if (is_string($data)) {
-            $data = json_decode($data, true);
-        }
-
         return array_merge(
             ['id' => $this->id],
-            CustomerNotificationPresenter::present((array) $data, $this->type),
+            CustomerNotificationPresenter::present((array) $this->data, $this->type),
             [
                 'is_read'    => $this->read_at !== null,
                 'read_at'    => $this->read_at,
diff --git a/server/src/Support/CustomerNotificationPresenter.php b/server/src/Support/CustomerNotificationPresenter.php
index 813b41b5..9f2886de 100644
--- a/server/src/Support/CustomerNotificationPresenter.php
+++ b/server/src/Support/CustomerNotificationPresenter.php
@@ -34,7 +34,7 @@ public static function present(array $data, ?string $notificationClass = null):
             $body = $title;
         }
 
-        $payload = Arr::except($data, static::HIDDEN_KEYS);
+        $payload = array_filter(Arr::except($data, static::HIDDEN_KEYS), fn ($value) => $value !== null);
 
         return [
             'type'  => $type,
diff --git a/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php b/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php
index 389b9983..42d36ac3 100644
--- a/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php
+++ b/server/tests/Unit/Http/Controllers/CustomerNotificationInboxTest.php
@@ -321,3 +321,99 @@ public function forgetPushed()
 
     expect((new SafeBroadcastChannel($events))->send($notifiable, new PromotionalPushNotification('Sale', 'Save now', $store)))->toBeNull();
 });
+
+test('a single notification can be fetched by id', function () {
+    inboxRequest();
+
+    expect((new NotificationController())->find('n_store_a')->resolve())->toMatchArray([
+        'id'    => 'n_store_a',
+        'type'  => 'order_completed',
+        'title' => 'Delivered',
+    ]);
+});
+
+test('an unknown network app shows nothing but storefront-less notifications, and no storefront context shows everything', function () {
+    session(['storefront_store' => null, 'storefront_network' => 'missing_network']);
+    $controller = new NotificationController();
+
+    expect(inboxIds($controller->query(inboxRequest())))->toBe(['n_store_a', 'n_network', 'n_store_c', 'n_generic', 'n_legacy']);
+
+    session(['storefront_store' => null, 'storefront_network' => null]);
+
+    expect(inboxIds($controller->query(inboxRequest())))->toBe(['n_store_a', 'n_network', 'n_store_c', 'n_generic', 'n_legacy']);
+});
+
+test('order notifications broadcast their inbox item', function () {
+    $order = new Fleetbase\FleetOps\Models\Order();
+    $order->forceFill(['uuid' => 'order_uuid', 'public_id' => 'order_public', 'meta' => ['storefront_id' => 'store_a']]);
+    $order->setRelation('customer', null);
+    $order->setRelation('company', null);
+    $notification                 = (new ReflectionClass(StorefrontOrderCompleted::class))->newInstanceWithoutConstructor();
+    $notification->order          = $order;
+    $notification->storefront     = tap(new Store())->forceFill(['public_id' => 'store_a', 'name' => 'Store A']);
+    $notification->sentAt         = '2026-09-01 10:00:00';
+    $notification->notificationId = 'notification_test';
+    $notification->subject        = 'Delivered';
+    $notification->body           = 'Enjoy!';
+    $notification->status         = 'order_completed';
+
+    expect($notification->toBroadcast(null)->data)->toBe([
+        'type'  => 'order_completed',
+        'title' => 'Delivered',
+        'body'  => 'Enjoy!',
+        'image' => null,
+        'data'  => ['order_id' => 'order_public', 'storefront_id' => 'store_a', 'store_id' => 'store_a'],
+    ])->and($notification->broadcastType())->toBe('order_completed');
+});
+
+test('successful broadcasts are delegated to the framework broadcast channel', function () {
+    $dispatched = [];
+    $events     = new class($dispatched) extends Illuminate\Events\Dispatcher {
+        public function __construct(public array &$dispatched)
+        {
+        }
+
+        public function dispatch($event, $payload = [], $halt = false)
+        {
+            $this->dispatched[] = $event;
+
+            return [];
+        }
+    };
+    $store      = tap(new Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'name' => 'Store A']);
+    $notifiable = new Contact();
+    $notifiable->forceFill(['uuid' => INBOX_CUSTOMER]);
+
+    (new SafeBroadcastChannel($events))->send($notifiable, new PromotionalPushNotification('Sale', 'Save now', $store));
+
+    expect($dispatched)->toHaveCount(1)
+        ->and($dispatched[0])->toBeInstanceOf(Illuminate\Notifications\Events\BroadcastNotificationCreated::class);
+});
+
+test('broadcast failures are swallowed even when logging fails', function () {
+    $events = new class extends Illuminate\Events\Dispatcher {
+        public function dispatch($event, $payload = [], $halt = false)
+        {
+            throw new RuntimeException('socket unavailable');
+        }
+    };
+    $app      = Illuminate\Container\Container::getInstance();
+    $original = $app->make('log');
+    $app->instance('log', new class {
+        public function __call($method, $arguments)
+        {
+            throw new RuntimeException('logger unavailable');
+        }
+    });
+    Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+    $store = tap(new Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'name' => 'Store A']);
+
+    try {
+        $result = (new SafeBroadcastChannel($events))->send(new Contact(), new PromotionalPushNotification('Sale', 'Save now', $store));
+    } finally {
+        $app->instance('log', $original);
+        Illuminate\Support\Facades\Log::clearResolvedInstance('log');
+    }
+
+    expect($result)->toBeNull();
+});

From ff2c917298a05b4beb5a5cf6b87e574f154ca24b Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 17:59:35 +0800
Subject: [PATCH 5/8] feat: add a promotions engine with codes, stacking and
 checkout integration

Add promotions owned by a store or network: automatic or code based
percentage, fixed amount, free delivery and buy X get Y discounts, with
product/category/store targeting, minimum subtotal and item conditions,
first order only, date ranges and weekly schedule windows, usage limits
(total, per customer, per code), budgets, maximum discounts, stacking and
priorities.

Checkout prices the cart's promotions when a checkout is created, stores
them on the checkout options and reserves each use under a row lock, so
the amount charged (cash, Stripe, QPay) always matches the discount
shown. Capture records a discount transaction item and order meta and
redeems the reservations; multi-store orders split the discount per
store. Stale reservations are released by a scheduled command.

Cart endpoints apply, remove and preview codes; the public API lists the
storefront's live deals; the console API manages promotions and
generates codes.
---
 ..._09_26_100000_create_promotions_tables.php | 108 ++++++
 server/src/Auth/Schemas/Storefront.php        |  17 +
 .../Commands/ReleasePromotionReservations.php |  37 ++
 .../Controllers/PromotionCodeController.php   |  13 +
 .../Http/Controllers/PromotionController.php  |  81 ++++
 .../Http/Controllers/v1/CartController.php    |  85 ++++
 .../Controllers/v1/CheckoutController.php     | 144 ++++++-
 .../Controllers/v1/PromotionController.php    |  65 ++++
 .../src/Http/Filter/PromotionCodeFilter.php   |  18 +
 server/src/Http/Filter/PromotionFilter.php    |  31 ++
 server/src/Http/Requests/PromotionRequest.php |  59 +++
 server/src/Http/Resources/Cart.php            |   1 +
 server/src/Http/Resources/Promotion.php       |  71 ++++
 server/src/Http/Resources/PromotionCode.php   |  35 ++
 server/src/Models/Cart.php                    |  24 ++
 server/src/Models/Promotion.php               | 174 +++++++++
 server/src/Models/PromotionCode.php           |  67 ++++
 server/src/Models/PromotionRedemption.php     |  55 +++
 server/src/Promotions/PromotionCalculator.php | 206 ++++++++++
 server/src/Promotions/PromotionContext.php    |  72 ++++
 server/src/Promotions/PromotionEngine.php     | 331 ++++++++++++++++
 server/src/Promotions/PromotionLine.php       |  44 +++
 .../src/Promotions/PromotionRedemptions.php   | 128 +++++++
 server/src/Promotions/PromotionResult.php     |  97 +++++
 .../PromotionUnavailableException.php         |  11 +
 .../Providers/StorefrontServiceProvider.php   |   2 +
 server/src/Support/QPay.php                   |  21 +
 server/src/Support/Storefront.php             |   4 +
 server/src/routes.php                         |  16 +
 server/tests/Support/PromotionTestHelpers.php | 212 ++++++++++
 .../Promotions/PromotionCalculatorTest.php    | 121 ++++++
 .../Unit/Promotions/PromotionCheckoutTest.php | 362 ++++++++++++++++++
 .../Promotions/PromotionEndpointsTest.php     | 297 ++++++++++++++
 .../Unit/Promotions/PromotionEngineTest.php   | 296 ++++++++++++++
 .../StorefrontServiceProviderTest.php         |   6 +
 35 files changed, 3303 insertions(+), 8 deletions(-)
 create mode 100644 server/migrations/2026_09_26_100000_create_promotions_tables.php
 create mode 100644 server/src/Console/Commands/ReleasePromotionReservations.php
 create mode 100644 server/src/Http/Controllers/PromotionCodeController.php
 create mode 100644 server/src/Http/Controllers/PromotionController.php
 create mode 100644 server/src/Http/Controllers/v1/PromotionController.php
 create mode 100644 server/src/Http/Filter/PromotionCodeFilter.php
 create mode 100644 server/src/Http/Filter/PromotionFilter.php
 create mode 100644 server/src/Http/Requests/PromotionRequest.php
 create mode 100644 server/src/Http/Resources/Promotion.php
 create mode 100644 server/src/Http/Resources/PromotionCode.php
 create mode 100644 server/src/Models/Promotion.php
 create mode 100644 server/src/Models/PromotionCode.php
 create mode 100644 server/src/Models/PromotionRedemption.php
 create mode 100644 server/src/Promotions/PromotionCalculator.php
 create mode 100644 server/src/Promotions/PromotionContext.php
 create mode 100644 server/src/Promotions/PromotionEngine.php
 create mode 100644 server/src/Promotions/PromotionLine.php
 create mode 100644 server/src/Promotions/PromotionRedemptions.php
 create mode 100644 server/src/Promotions/PromotionResult.php
 create mode 100644 server/src/Promotions/PromotionUnavailableException.php
 create mode 100644 server/tests/Support/PromotionTestHelpers.php
 create mode 100644 server/tests/Unit/Promotions/PromotionCalculatorTest.php
 create mode 100644 server/tests/Unit/Promotions/PromotionCheckoutTest.php
 create mode 100644 server/tests/Unit/Promotions/PromotionEndpointsTest.php
 create mode 100644 server/tests/Unit/Promotions/PromotionEngineTest.php

diff --git a/server/migrations/2026_09_26_100000_create_promotions_tables.php b/server/migrations/2026_09_26_100000_create_promotions_tables.php
new file mode 100644
index 00000000..88facb88
--- /dev/null
+++ b/server/migrations/2026_09_26_100000_create_promotions_tables.php
@@ -0,0 +1,108 @@
+<?php
+
+use Fleetbase\Support\Utils;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Promotions: automatic and code-based discounts owned by a store or network.
+     *
+     * Money columns are integers in the storefront currency's minor unit, like cart
+     * subtotals. `promotion_redemptions` records every use: a checkout reserves the
+     * discount when it is created and the reservation is redeemed when the order is
+     * captured, so usage limits and budgets count both.
+     */
+    public function up(): void
+    {
+        $databaseName = Utils::getFleetbaseDatabaseName();
+        $schema       = Schema::connection(config('storefront.connection.db'));
+
+        $schema->create('promotions', function (Blueprint $table) use ($databaseName) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->string('public_id')->unique()->nullable();
+            $table->foreignUuid('company_uuid')->nullable()->index()->references('uuid')->on(new Expression($databaseName . '.companies'))->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->foreignUuid('created_by_uuid')->nullable()->references('uuid')->on(new Expression($databaseName . '.users'))->onUpdate('CASCADE')->onDelete('SET NULL');
+            $table->uuid('owner_uuid')->nullable();
+            $table->string('owner_type')->nullable();
+            $table->string('name');
+            $table->text('description')->nullable();
+            $table->string('status')->default('draft')->index();
+            $table->string('trigger')->default('automatic');
+            $table->string('type');
+            $table->decimal('value', 12, 2)->nullable();
+            $table->unsignedBigInteger('max_discount_amount')->nullable();
+            $table->string('currency', 3)->nullable();
+            $table->unsignedBigInteger('min_subtotal')->nullable();
+            $table->unsignedInteger('min_items')->nullable();
+            $table->json('applies_to')->nullable();
+            $table->json('bogo_config')->nullable();
+            $table->boolean('first_order_only')->default(false);
+            $table->unsignedInteger('usage_limit')->nullable();
+            $table->unsignedInteger('usage_limit_per_customer')->nullable();
+            $table->unsignedBigInteger('budget_amount')->nullable();
+            $table->boolean('stackable')->default(false);
+            $table->integer('priority')->default(0);
+            $table->boolean('is_public')->default(true);
+            $table->timestamp('starts_at')->nullable();
+            $table->timestamp('ends_at')->nullable();
+            $table->json('schedule')->nullable();
+            $table->string('timezone')->nullable();
+            $table->uuid('image_uuid')->nullable();
+            $table->json('translations')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->index(['owner_uuid', 'status']);
+        });
+
+        $schema->create('promotion_codes', function (Blueprint $table) use ($databaseName) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->string('public_id')->unique()->nullable();
+            $table->foreignUuid('company_uuid')->nullable()->references('uuid')->on(new Expression($databaseName . '.companies'))->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->foreignUuid('promotion_uuid')->references('uuid')->on('promotions')->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->string('code');
+            $table->string('status')->default('active');
+            $table->unsignedInteger('usage_limit')->nullable();
+            $table->uuid('customer_uuid')->nullable();
+            $table->timestamp('expires_at')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->unique(['company_uuid', 'code']);
+        });
+
+        $schema->create('promotion_redemptions', function (Blueprint $table) use ($databaseName) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->foreignUuid('company_uuid')->nullable()->references('uuid')->on(new Expression($databaseName . '.companies'))->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->foreignUuid('promotion_uuid')->references('uuid')->on('promotions')->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->uuid('promotion_code_uuid')->nullable()->index();
+            $table->uuid('customer_uuid')->nullable()->index();
+            $table->uuid('checkout_uuid')->nullable()->index();
+            $table->uuid('order_uuid')->nullable()->index();
+            $table->unsignedBigInteger('amount')->default(0);
+            $table->string('currency', 3)->nullable();
+            $table->string('status')->default('reserved');
+            $table->timestamp('redeemed_at')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->index(['promotion_uuid', 'status']);
+        });
+    }
+
+    public function down(): void
+    {
+        $schema = Schema::connection(config('storefront.connection.db'));
+        $schema->dropIfExists('promotion_redemptions');
+        $schema->dropIfExists('promotion_codes');
+        $schema->dropIfExists('promotions');
+    }
+};
diff --git a/server/src/Auth/Schemas/Storefront.php b/server/src/Auth/Schemas/Storefront.php
index 9f468567..a77cf6ff 100644
--- a/server/src/Auth/Schemas/Storefront.php
+++ b/server/src/Auth/Schemas/Storefront.php
@@ -111,6 +111,14 @@ class Storefront
             'name'    => 'food-truck',
             'actions' => [],
         ],
+        [
+            'name'    => 'promotion',
+            'actions' => ['generate-codes'],
+        ],
+        [
+            'name'    => 'promotion-code',
+            'actions' => [],
+        ],
         [
             'name'           => 'settings',
             'action'         => ['import'],
@@ -154,6 +162,15 @@ class Storefront
                 '* order',
             ],
         ],
+        [
+            'name'        => 'PromotionsManager',
+            'description' => 'Policy for managing promotions and promotion codes.',
+            'permissions' => [
+                'see extension',
+                '* promotion',
+                '* promotion-code',
+            ],
+        ],
         [
             'name'        => 'MarketplaceManager',
             'description' => 'Policy for managing networks.',
diff --git a/server/src/Console/Commands/ReleasePromotionReservations.php b/server/src/Console/Commands/ReleasePromotionReservations.php
new file mode 100644
index 00000000..d9133e2f
--- /dev/null
+++ b/server/src/Console/Commands/ReleasePromotionReservations.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\Storefront\Console\Commands;
+
+use Fleetbase\Storefront\Promotions\PromotionRedemptions;
+use Illuminate\Console\Command;
+
+class ReleasePromotionReservations extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'storefront:release-promotion-reservations';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Release promotion uses reserved by checkouts that were never captured';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle()
+    {
+        $released = PromotionRedemptions::releaseStale();
+
+        $this->info('Released ' . $released . ' stale promotion reservation(s).');
+
+        return 0;
+    }
+}
diff --git a/server/src/Http/Controllers/PromotionCodeController.php b/server/src/Http/Controllers/PromotionCodeController.php
new file mode 100644
index 00000000..f1f090ba
--- /dev/null
+++ b/server/src/Http/Controllers/PromotionCodeController.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers;
+
+class PromotionCodeController extends StorefrontController
+{
+    /**
+     * The resource to query.
+     *
+     * @var string
+     */
+    public $resource = 'promotion_code';
+}
diff --git a/server/src/Http/Controllers/PromotionController.php b/server/src/Http/Controllers/PromotionController.php
new file mode 100644
index 00000000..afb5bdc5
--- /dev/null
+++ b/server/src/Http/Controllers/PromotionController.php
@@ -0,0 +1,81 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers;
+
+use Fleetbase\Storefront\Http\Requests\PromotionRequest;
+use Fleetbase\Storefront\Http\Resources\PromotionCode as PromotionCodeResource;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Illuminate\Http\Request;
+
+class PromotionController extends StorefrontController
+{
+    /**
+     * The resource to query.
+     *
+     * @var string
+     */
+    public $resource = 'promotion';
+
+    /**
+     * Validates creates and updates.
+     *
+     * @var string
+     */
+    public $request = PromotionRequest::class;
+
+    /**
+     * Generate a batch of unique codes for a promotion.
+     *
+     * Body: `count` (1-1000, default 1), `length` (6-16, default 8), `prefix`, `usage_limit`
+     * (per code, e.g. 1 for single-use codes), `expires_at`, and `code` to create one specific code.
+     */
+    public function generateCodes(string $id, Request $request)
+    {
+        $promotion = Promotion::where('company_uuid', session('company'))
+            ->where(fn ($query) => $query->where('uuid', $id)->orWhere('public_id', $id))
+            ->first();
+
+        if (!$promotion) {
+            return response()->error('Promotion not found.', 404);
+        }
+
+        $count  = min(max((int) $request->input('count', 1), 1), 1000);
+        $length = min(max((int) $request->input('length', 8), 6), 16);
+        $prefix = PromotionCode::normalize($request->input('prefix', ''));
+        $exact  = $request->filled('code') ? PromotionCode::normalize($request->input('code')) : null;
+
+        if ($exact !== null && PromotionCode::where('company_uuid', $promotion->company_uuid)->where('code', $exact)->exists()) {
+            return response()->error('The code "' . $exact . '" is already in use.');
+        }
+
+        $codes    = [];
+        $attempts = 0;
+        while (count($codes) < ($exact ? 1 : $count) && $attempts++ < $count * 10) {
+            $code = $exact ?? $this->generateCode($length, $prefix);
+            if (isset($codes[$code]) || PromotionCode::where('company_uuid', $promotion->company_uuid)->where('code', $code)->exists()) {
+                continue;
+            }
+
+            $codes[$code] = PromotionCode::create([
+                'company_uuid'   => $promotion->company_uuid,
+                'promotion_uuid' => $promotion->uuid,
+                'code'           => $code,
+                'status'         => PromotionCode::STATUS_ACTIVE,
+                'usage_limit'    => $request->input('usage_limit'),
+                'expires_at'     => $request->input('expires_at'),
+            ]);
+        }
+
+        if ($promotion->trigger !== Promotion::TRIGGER_CODE) {
+            $promotion->update(['trigger' => Promotion::TRIGGER_CODE]);
+        }
+
+        return response()->json(['codes' => PromotionCodeResource::collection(array_values($codes))]);
+    }
+
+    protected function generateCode(int $length, string $prefix): string
+    {
+        return PromotionCode::generate($length, $prefix);
+    }
+}
diff --git a/server/src/Http/Controllers/v1/CartController.php b/server/src/Http/Controllers/v1/CartController.php
index af5aa9fb..165d767c 100644
--- a/server/src/Http/Controllers/v1/CartController.php
+++ b/server/src/Http/Controllers/v1/CartController.php
@@ -2,9 +2,16 @@
 
 namespace Fleetbase\Storefront\Http\Controllers\v1;
 
+use Fleetbase\FleetOps\Models\ServiceQuote;
+use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Storefront\Http\Resources\Cart as StorefrontCart;
 use Fleetbase\Storefront\Models\Cart;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Promotions\PromotionContext;
+use Fleetbase\Storefront\Promotions\PromotionEngine;
+use Fleetbase\Storefront\Promotions\PromotionResult;
+use Fleetbase\Storefront\Support\Storefront;
 use Illuminate\Http\Request;
 
 class CartController extends Controller
@@ -127,6 +134,84 @@ public function empty(string $cartId)
         return new StorefrontCart($cart);
     }
 
+    /**
+     * Applies a promotion code to the cart after checking that it can be used on it.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function applyPromotionCode(string $cartId, Request $request)
+    {
+        $code = PromotionCode::normalize($request->input('code'));
+        if ($code === '') {
+            return response()->apiError('A promotion code is required.');
+        }
+
+        $cart   = $this->retrieveCart($cartId);
+        $codes  = array_values(array_unique([...$cart->getPromotionCodes(), $code]));
+        $result = $this->evaluatePromotions($cart, $request, $codes);
+
+        $rejection = collect($result->rejected)->firstWhere('code', $code);
+        if ($rejection && $rejection['reason'] !== PromotionEngine::REASON_NOT_COMBINABLE) {
+            return response()->apiError('Promotion code "' . $code . '" cannot be applied (' . $rejection['reason'] . ').', 400, ['reason' => $rejection['reason']]);
+        }
+
+        $cart->setPromotionCodes($codes)->save();
+
+        return response()->json([
+            'cart'       => new StorefrontCart($cart),
+            'promotions' => $result->toPublicArray(),
+        ]);
+    }
+
+    /**
+     * Removes a promotion code from the cart.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function removePromotionCode(string $cartId, string $code, Request $request)
+    {
+        $cart  = $this->retrieveCart($cartId);
+        $codes = array_values(array_diff($cart->getPromotionCodes(), [PromotionCode::normalize($code)]));
+        $cart->setPromotionCodes($codes)->save();
+
+        return response()->json([
+            'cart'       => new StorefrontCart($cart),
+            'promotions' => $this->evaluatePromotions($cart, $request, $codes)->toPublicArray(),
+        ]);
+    }
+
+    /**
+     * Previews the discounts the cart currently qualifies for.
+     *
+     * Query params: `pickup` (bool) and `service_quote` (a quote id, for delivery discounts).
+     * Customer specific rules (first order, per-customer limits) are only checked when a
+     * customer token is sent, and are always enforced again at checkout.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function promotions(string $cartId, Request $request)
+    {
+        $cart = $this->retrieveCart($cartId);
+
+        return response()->json($this->evaluatePromotions($cart, $request, $cart->getPromotionCodes())->toPublicArray());
+    }
+
+    protected function evaluatePromotions(Cart $cart, Request $request, array $codes): PromotionResult
+    {
+        $isPickup     = $request->boolean('pickup');
+        $quoteId      = $request->or(['service_quote', 'serviceQuote']);
+        $serviceQuote = $isPickup || !$quoteId ? null : ServiceQuote::where('public_id', $quoteId)->first(['uuid', 'amount']);
+        $context      = PromotionContext::fromCart(
+            $cart,
+            Storefront::about(),
+            Storefront::getCustomerFromToken(),
+            $isPickup,
+            $serviceQuote ? (int) Utils::numbersOnly($serviceQuote->amount) : 0
+        );
+
+        return app(PromotionEngine::class)->evaluate($context, $codes);
+    }
+
     /**
      * Deletes a cart.
      *
diff --git a/server/src/Http/Controllers/v1/CheckoutController.php b/server/src/Http/Controllers/v1/CheckoutController.php
index c4090986..df5aeddb 100644
--- a/server/src/Http/Controllers/v1/CheckoutController.php
+++ b/server/src/Http/Controllers/v1/CheckoutController.php
@@ -25,6 +25,11 @@
 use Fleetbase\Storefront\Models\Product;
 use Fleetbase\Storefront\Models\Store;
 use Fleetbase\Storefront\Models\StoreLocation;
+use Fleetbase\Storefront\Promotions\PromotionContext;
+use Fleetbase\Storefront\Promotions\PromotionEngine;
+use Fleetbase\Storefront\Promotions\PromotionRedemptions;
+use Fleetbase\Storefront\Promotions\PromotionResult;
+use Fleetbase\Storefront\Promotions\PromotionUnavailableException;
 use Fleetbase\Storefront\Support\QPay;
 use Fleetbase\Storefront\Support\Storefront;
 use Fleetbase\Storefront\Support\StripeUtils;
@@ -304,6 +309,12 @@ public function beforeCheckout(InitializeCheckoutRequest $request)
         }
         $serviceQuote = ServiceQuote::select(['amount', 'meta', 'uuid', 'public_id'])->where('public_id', $serviceQuoteId)->first();
 
+        // price promotions onto the checkout
+        $promotionError = static::applyPromotions($cart, $serviceQuote, $checkoutOptions, $customer, $request);
+        if ($promotionError) {
+            return $promotionError;
+        }
+
         // handle cash orders
         if ($isCashOnDelivery) {
             return static::initializeCashCheckout($customer, $gateway, $serviceQuote, $cart, $checkoutOptions, $request);
@@ -373,7 +384,8 @@ public static function initializeCashCheckout(Contact $customer, Gateway $gatewa
         // `checkout` is the chkt_* public id and `token` is a separate checkout_* value.
         // GET /checkouts/status needs BOTH, and only initializeQPayCheckout was returning
         // the id — so a cash or card client could never reach its own checkout's status.
-        return response()->json([
+        // The checkout is discarded instead if one of its promotions ran out meanwhile.
+        return static::reservePromotions($checkout, $checkoutOptions, $customer) ?? response()->json([
             'checkout' => $checkout->public_id,
             'token'    => $checkout->token,
         ]);
@@ -474,7 +486,7 @@ public static function initializeStripeCheckout(Contact $customer, Gateway $gate
 
         // See initializeCheckout: `checkout` is the chkt_* public id GET /checkouts/status
         // requires alongside the token, and nothing but the QPay path used to return it.
-        return response()->json([
+        return static::reservePromotions($checkout, $checkoutOptions, $customer) ?? response()->json([
             'paymentIntent' => $paymentIntent->id,
             'clientSecret'  => $paymentIntent->client_secret,
             'ephemeralKey'  => $ephemeralKey->secret,
@@ -611,6 +623,12 @@ public function updateStripePaymentIntent(Request $request)
             ->where('public_id', $serviceQuoteId)
             ->first();
 
+        // Price promotions onto the new checkout
+        $promotionError = static::applyPromotions($cart, $serviceQuote, $checkoutOptions, $customer, $request);
+        if ($promotionError) {
+            return $promotionError;
+        }
+
         // Recalculate amount based on cart, serviceQuote, and checkoutOptions
         $amount   = static::calculateCheckoutAmount($cart, $serviceQuote, $checkoutOptions);
         $currency = $cart->getCurrency();
@@ -700,7 +718,7 @@ public function updateStripePaymentIntent(Request $request)
 
         // Return JSON response with updated PaymentIntent and ephemeral key. `checkout` is
         // the chkt_* public id GET /checkouts/status requires alongside the token.
-        return response()->json([
+        return static::reservePromotions($checkout, $checkoutOptions, $customer) ?? response()->json([
             'paymentIntent' => $paymentIntent->id,
             'clientSecret'  => $paymentIntent->client_secret,
             'ephemeralKey'  => $ephemeralKey->secret,
@@ -824,7 +842,7 @@ public static function initializeQPayCheckout(Contact $customer, Gateway $gatewa
         // Update checkout with invoice id
         $checkout->updateOption('qpay_invoice_id', data_get($invoice, 'invoice_id'));
 
-        return response()->json([
+        return static::reservePromotions($checkout, $checkoutOptions, $customer) ?? response()->json([
             'invoice'  => $invoice,
             'checkout' => $checkout->public_id,
             'token'    => $checkout->token,
@@ -1294,6 +1312,10 @@ public function captureOrder(CaptureOrderRequest $request)
             ]);
         }
 
+        // if promotions were applied create a (credit) transaction item for the discount
+        $promotions = PromotionResult::fromArray(data_get($checkout->options, 'promotions'));
+        static::createDiscountTransactionItem($transaction, $promotions, $checkout->currency);
+
         // if single cart checkout and origin is array get the first id
         if (is_array($origin)) {
             $origin = Arr::first($origin);
@@ -1356,6 +1378,8 @@ public function captureOrder(CaptureOrderRequest $request)
             'delivery_fee' => $checkout->is_pickup ? 0 : Utils::numbersOnly($serviceQuote->amount),
             'tip'          => $checkout->getOption('tip'),
             'delivery_tip' => $checkout->getOption('delivery_tip'),
+            'discount'     => $promotions->discount(),
+            'promotions'   => $promotions->toPublicArray()['applied'],
             'total'        => Utils::numbersOnly($amount),
             'currency'     => $currency,
             'gateway'      => $gateway->type,
@@ -1399,6 +1423,9 @@ public function captureOrder(CaptureOrderRequest $request)
         // create order
         $order = Order::create($orderInput);
 
+        // record the promotions as used by this order
+        PromotionRedemptions::redeem($checkout, $order);
+
         // notify driver if assigned
         $order->notifyDriverAssigned();
 
@@ -1660,6 +1687,11 @@ public function captureMultipleOrders(CaptureOrderRequest $request)
             ]);
         }
 
+        // if promotions were applied create a (credit) transaction item for the discount
+        $promotions          = PromotionResult::fromArray(data_get($checkout->options, 'promotions'));
+        $discountAllocations = $promotions->allocationsByStore();
+        static::createDiscountTransactionItem($transaction, $promotions, $checkout->currency);
+
         // convert payload destinations to Place
         $origins = collect($origins)->map(function ($publicId) {
             return Place::createFromMixed($publicId);
@@ -1689,8 +1721,9 @@ public function captureMultipleOrders(CaptureOrderRequest $request)
                 $this->processCartItem($cartItem, $payload, $customer);
             }
 
-            // get order subtotal
-            $subtotal = $cart->getSubtotalForStore($store);
+            // get order subtotal and this store's share of the item discount
+            $subtotal      = $cart->getSubtotalForStore($store);
+            $storeDiscount = min((int) ($discountAllocations[$store->public_id] ?? 0), (int) $subtotal);
 
             // prepare order meta
             $orderMeta = [
@@ -1704,7 +1737,8 @@ public function captureMultipleOrders(CaptureOrderRequest $request)
                 'delivery_fee'          => 0,
                 'tip'                   => 0,
                 'delivery_tip'          => 0,
-                'total'                 => $subtotal,
+                'discount'              => $storeDiscount,
+                'total'                 => $subtotal - $storeDiscount,
                 'currency'              => $currency,
                 'gateway'               => $gateway->type,
                 'require_pod'           => $about->getOption('require_pod'),
@@ -1791,6 +1825,8 @@ public function captureMultipleOrders(CaptureOrderRequest $request)
             'delivery_fee'          => $checkout->is_pickup ? 0 : Utils::numbersOnly($serviceQuote->amount),
             'tip'                   => $checkout->getOption('tip'),
             'delivery_tip'          => $checkout->getOption('delivery_tip'),
+            'discount'              => $promotions->discount(),
+            'promotions'            => $promotions->toPublicArray()['applied'],
             'total'                 => Utils::numbersOnly($amount),
             'currency'              => $currency,
             'gateway'               => $gateway->type,
@@ -1828,6 +1864,9 @@ public function captureMultipleOrders(CaptureOrderRequest $request)
         // create master order
         $order = Order::create($masterOrderInput);
 
+        // record the promotions as used by this checkout's master order
+        PromotionRedemptions::redeem($checkout, $order);
+
         // update child orders with master order id in meta
         foreach ($multipleOrders as $childOrder) {
             $childOrder->updateMeta('master_order_id', $order->public_id);
@@ -2028,7 +2067,96 @@ private static function calculateCheckoutAmount(Cart $cart, ?ServiceQuote $servi
             $total += Utils::numbersOnly($serviceQuote->amount);
         }
 
-        return $total;
+        // Promotions priced when the checkout was created. Tips are computed on the
+        // undiscounted subtotal, and discounts never exceed what they discount.
+        $promotions = data_get($checkoutOptions, 'promotions');
+        if ($promotions) {
+            $total -= min((int) data_get($promotions, 'discount_subtotal', 0), $subtotal);
+            if (!$isPickup) {
+                $total -= min((int) data_get($promotions, 'discount_delivery', 0), (int) Utils::numbersOnly($serviceQuote->amount));
+            }
+        }
+
+        return max($total, 0);
+    }
+
+    /**
+     * Record the promotions' discount as a transaction item.
+     *
+     * The amount is stored positive (the Money cast drops signs) and flagged as a credit with the
+     * `discount` code: the transaction amount is the items minus this line.
+     */
+    protected static function createDiscountTransactionItem(Transaction $transaction, PromotionResult $promotions, ?string $currency): void
+    {
+        if ($promotions->discount() <= 0) {
+            return;
+        }
+
+        TransactionItem::create([
+            'transaction_uuid' => $transaction->uuid,
+            'amount'           => $promotions->discount(),
+            'currency'         => $currency,
+            'details'          => 'Discount: ' . implode(', ', array_filter(array_column($promotions->applied, 'name'))),
+            'code'             => 'discount',
+            'meta'             => ['direction' => 'credit', 'promotions' => $promotions->toPublicArray()['applied']],
+        ]);
+    }
+
+    /**
+     * Price the cart's promotions and store them on the checkout options.
+     *
+     * Codes come from the request (`promo_codes`, `promo_code` or `discount_code`) and from codes
+     * applied to the cart. A code that cannot be applied fails the checkout, so the customer is
+     * never charged without a discount they expected. Codes that only lost to a better
+     * combination of promotions do not.
+     */
+    protected static function applyPromotions(Cart $cart, ?ServiceQuote $serviceQuote, $checkoutOptions, ?Contact $customer, Request $request): ?JsonResponse
+    {
+        $isPickup    = (bool) data_get($checkoutOptions, 'is_pickup', false);
+        $deliveryFee = $serviceQuote && !$isPickup ? (int) Utils::numbersOnly($serviceQuote->amount) : 0;
+        $context     = PromotionContext::fromCart($cart, Storefront::about(), $customer, $isPickup, $deliveryFee);
+        $result      = app(PromotionEngine::class)->evaluate($context, static::promotionCodesFor($cart, $request));
+
+        $blocking = array_values(array_filter($result->rejected, fn ($rejection) => $rejection['reason'] !== PromotionEngine::REASON_NOT_COMBINABLE));
+        if ($blocking) {
+            return response()->apiError(
+                'Promotion code "' . $blocking[0]['code'] . '" cannot be applied (' . $blocking[0]['reason'] . ').',
+                400,
+                ['promotions' => ['rejected' => $blocking]]
+            );
+        }
+
+        if (!$result->isEmpty()) {
+            $checkoutOptions->promotions = $result->toArray();
+        }
+
+        return null;
+    }
+
+    protected static function promotionCodesFor(Cart $cart, Request $request): array
+    {
+        $codes = $request->input('promo_codes', $request->or(['promo_code', 'promoCode', 'discount_code']));
+        if (is_string($codes)) {
+            $codes = explode(',', $codes);
+        }
+
+        return array_values(array_unique(array_filter(array_merge((array) $codes, $cart->getPromotionCodes()), 'is_string')));
+    }
+
+    /**
+     * Reserve a new checkout's promotions, discarding the checkout if one ran out meanwhile.
+     */
+    protected static function reservePromotions(Checkout $checkout, $checkoutOptions, ?Contact $customer): ?JsonResponse
+    {
+        try {
+            PromotionRedemptions::reserve($checkout, PromotionResult::fromArray(data_get($checkoutOptions, 'promotions')), $customer?->uuid);
+        } catch (PromotionUnavailableException $e) {
+            $checkout->delete();
+
+            return response()->apiError($e->getMessage());
+        }
+
+        return null;
     }
 
     private static function calculateTipAmount($tip, $subtotal)
diff --git a/server/src/Http/Controllers/v1/PromotionController.php b/server/src/Http/Controllers/v1/PromotionController.php
new file mode 100644
index 00000000..d9d106f0
--- /dev/null
+++ b/server/src/Http/Controllers/v1/PromotionController.php
@@ -0,0 +1,65 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers\v1;
+
+use Fleetbase\Http\Controllers\Controller;
+use Fleetbase\Storefront\Http\Resources\Promotion as PromotionResource;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Support\Storefront;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\Request;
+
+/**
+ * Public promotions ("deals") of the storefront the request is made with.
+ */
+class PromotionController extends Controller
+{
+    /**
+     * Live, public promotions of the storefront, and in a network of its member stores.
+     *
+     * Query params: `store` (a store public id, to only list that store's promotions in a network).
+     */
+    public function query(Request $request)
+    {
+        $promotions = $this->publicPromotions($request->input('store'))
+            ->orderByDesc('priority')
+            ->orderBy('ends_at')
+            ->get()
+            ->filter(fn (Promotion $promotion) => $promotion->isLiveAt())
+            ->values();
+
+        return PromotionResource::collection($promotions);
+    }
+
+    public function find(string $id)
+    {
+        $promotion = $this->publicPromotions()->where('public_id', $id)->first();
+
+        if (!$promotion || !$promotion->isLiveAt()) {
+            return response()->apiError('Promotion not found.', 404);
+        }
+
+        return new PromotionResource($promotion);
+    }
+
+    protected function publicPromotions(?string $storeId = null): Builder
+    {
+        $about  = Storefront::about();
+        $owners = [$about?->uuid];
+
+        if ($about?->is_network) {
+            $stores = Store::whereHas('networks', fn ($query) => $query->where('network_uuid', $about->uuid))
+                ->when($storeId, fn ($query) => $query->where('public_id', $storeId))
+                ->pluck('uuid')
+                ->all();
+            $owners = $storeId ? $stores : [...$owners, ...$stores];
+        }
+
+        return Promotion::query()
+            ->whereIn('owner_uuid', array_filter($owners))
+            ->where('status', Promotion::STATUS_ACTIVE)
+            ->where('is_public', true)
+            ->with('image');
+    }
+}
diff --git a/server/src/Http/Filter/PromotionCodeFilter.php b/server/src/Http/Filter/PromotionCodeFilter.php
new file mode 100644
index 00000000..00919eba
--- /dev/null
+++ b/server/src/Http/Filter/PromotionCodeFilter.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Filter;
+
+use Fleetbase\Http\Filter\Filter;
+
+class PromotionCodeFilter extends Filter
+{
+    public function queryForInternal()
+    {
+        $this->builder->where('company_uuid', $this->session->get('company'));
+    }
+
+    public function promotion(string $promotion)
+    {
+        $this->builder->where('promotion_uuid', $promotion);
+    }
+}
diff --git a/server/src/Http/Filter/PromotionFilter.php b/server/src/Http/Filter/PromotionFilter.php
new file mode 100644
index 00000000..069a5391
--- /dev/null
+++ b/server/src/Http/Filter/PromotionFilter.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Filter;
+
+use Fleetbase\Http\Filter\Filter;
+
+class PromotionFilter extends Filter
+{
+    public function queryForInternal()
+    {
+        $this->builder->where('company_uuid', $this->session->get('company'));
+    }
+
+    /**
+     * Promotions owned by a store or network (uuid).
+     */
+    public function owner(string $owner)
+    {
+        $this->builder->where('owner_uuid', $owner);
+    }
+
+    public function status(string $status)
+    {
+        $this->builder->where('status', $status);
+    }
+
+    public function type(string $type)
+    {
+        $this->builder->where('type', $type);
+    }
+}
diff --git a/server/src/Http/Requests/PromotionRequest.php b/server/src/Http/Requests/PromotionRequest.php
new file mode 100644
index 00000000..93db0c97
--- /dev/null
+++ b/server/src/Http/Requests/PromotionRequest.php
@@ -0,0 +1,59 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Requests;
+
+use Fleetbase\Http\Requests\FleetbaseRequest;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+
+class PromotionRequest extends FleetbaseRequest
+{
+    public function authorize()
+    {
+        return request()->session()->has('user');
+    }
+
+    public function rules()
+    {
+        $required = $this->isMethod('post') ? 'required' : 'sometimes';
+
+        return [
+            'name'                     => [$required, 'string', 'max:191'],
+            'type'                     => [$required, 'in:' . implode(',', Promotion::TYPES)],
+            'trigger'                  => ['sometimes', 'in:' . Promotion::TRIGGER_AUTOMATIC . ',' . Promotion::TRIGGER_CODE],
+            'status'                   => ['sometimes', 'in:' . implode(',', Promotion::STATUSES)],
+            'owner_uuid'               => [$required, 'string', function ($attribute, $value, $fail) {
+                $owned = fn ($model) => $model::where('uuid', $value)->where('company_uuid', session('company'))->exists();
+                if (!$owned(Store::class) && !$owned(Network::class)) {
+                    $fail('The promotion must belong to one of your stores or networks.');
+                }
+            }],
+            'value'                        => ['nullable', 'numeric', 'min:0', 'required_if:type,' . Promotion::TYPE_PERCENTAGE . ',' . Promotion::TYPE_FIXED_AMOUNT],
+            'max_discount_amount'          => ['nullable', 'integer', 'min:0'],
+            'currency'                     => ['nullable', 'string', 'size:3'],
+            'min_subtotal'                 => ['nullable', 'integer', 'min:0'],
+            'min_items'                    => ['nullable', 'integer', 'min:1'],
+            'applies_to'                   => ['nullable', 'array'],
+            'bogo_config'                  => ['nullable', 'array'],
+            'bogo_config.buy_quantity'     => ['nullable', 'integer', 'min:1'],
+            'bogo_config.get_quantity'     => ['nullable', 'integer', 'min:1'],
+            'bogo_config.discount_percent' => ['nullable', 'numeric', 'between:0,100'],
+            'first_order_only'             => ['sometimes', 'boolean'],
+            'usage_limit'                  => ['nullable', 'integer', 'min:1'],
+            'usage_limit_per_customer'     => ['nullable', 'integer', 'min:1'],
+            'budget_amount'                => ['nullable', 'integer', 'min:1'],
+            'stackable'                    => ['sometimes', 'boolean'],
+            'priority'                     => ['sometimes', 'integer'],
+            'is_public'                    => ['sometimes', 'boolean'],
+            'starts_at'                    => ['nullable', 'date'],
+            'ends_at'                      => ['nullable', 'date', 'after:starts_at'],
+            'schedule'                     => ['nullable', 'array'],
+            'schedule.*.days'              => ['sometimes', 'array'],
+            'schedule.*.days.*'            => ['integer', 'between:1,7'],
+            'schedule.*.start'             => ['sometimes', 'date_format:H:i'],
+            'schedule.*.end'               => ['sometimes', 'date_format:H:i'],
+            'timezone'                     => ['nullable', 'timezone'],
+        ];
+    }
+}
diff --git a/server/src/Http/Resources/Cart.php b/server/src/Http/Resources/Cart.php
index 840d80cf..0757572d 100644
--- a/server/src/Http/Resources/Cart.php
+++ b/server/src/Http/Resources/Cart.php
@@ -33,6 +33,7 @@ public function toArray($request)
             'items'              => $this->getCartItems(),
             'events'             => $this->events ?? [],
             'discount_code'      => $this->discount_code,
+            'promo_codes'        => array_values(array_filter(explode(',', (string) $this->discount_code))),
             'expires_at'         => $this->expires_at,
             'created_at'         => $this->created_at,
             'updated_at'         => $this->updated_at,
diff --git a/server/src/Http/Resources/Promotion.php b/server/src/Http/Resources/Promotion.php
new file mode 100644
index 00000000..e3d44d69
--- /dev/null
+++ b/server/src/Http/Resources/Promotion.php
@@ -0,0 +1,71 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Resources;
+
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Storefront\Models\PromotionRedemption;
+use Fleetbase\Support\Http;
+
+class Promotion extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        $internal = Http::isInternalRequest();
+
+        return [
+            'id'                       => $this->when($internal, $this->uuid, $this->public_id),
+            'uuid'                     => $this->when($internal, $this->uuid),
+            'public_id'                => $this->when($internal, $this->public_id),
+            'company_uuid'             => $this->when($internal, $this->company_uuid),
+            'owner_uuid'               => $this->when($internal, $this->owner_uuid),
+            'owner_type'               => $this->when($internal, $this->owner_type),
+            'name'                     => $this->name,
+            'description'              => $this->description,
+            'status'                   => $this->when($internal, $this->status),
+            'trigger'                  => $this->trigger,
+            'type'                     => $this->type,
+            'value'                    => $this->value,
+            'max_discount_amount'      => $this->max_discount_amount,
+            'currency'                 => $this->currency,
+            'min_subtotal'             => $this->min_subtotal,
+            'min_items'                => $this->min_items,
+            'applies_to'               => $this->applies_to,
+            'bogo_config'              => $this->bogo_config,
+            'first_order_only'         => $this->first_order_only,
+            'usage_limit'              => $this->when($internal, $this->usage_limit),
+            'usage_limit_per_customer' => $this->usage_limit_per_customer,
+            'budget_amount'            => $this->when($internal, $this->budget_amount),
+            'stackable'                => $this->stackable,
+            'priority'                 => $this->when($internal, $this->priority),
+            'is_public'                => $this->when($internal, $this->is_public),
+            'starts_at'                => $this->starts_at,
+            'ends_at'                  => $this->ends_at,
+            'schedule'                 => $this->schedule,
+            'timezone'                 => $this->timezone,
+            'image_uuid'               => $this->when($internal, $this->image_uuid),
+            'image_url'                => $this->image?->url,
+            'translations'             => $this->translations,
+            'stats'                    => $this->when($internal, fn () => $this->stats()),
+            'meta'                     => $this->when($internal, $this->meta),
+            'created_at'               => $this->created_at,
+            'updated_at'               => $this->updated_at,
+        ];
+    }
+
+    protected function stats(): array
+    {
+        $redeemed = PromotionRedemption::where('promotion_uuid', $this->uuid)->where('status', PromotionRedemption::STATUS_REDEEMED);
+
+        return [
+            'redemptions'    => (clone $redeemed)->count(),
+            'discount_given' => (int) (clone $redeemed)->sum('amount'),
+        ];
+    }
+}
diff --git a/server/src/Http/Resources/PromotionCode.php b/server/src/Http/Resources/PromotionCode.php
new file mode 100644
index 00000000..19f4269d
--- /dev/null
+++ b/server/src/Http/Resources/PromotionCode.php
@@ -0,0 +1,35 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Resources;
+
+use Fleetbase\Http\Resources\FleetbaseResource;
+use Fleetbase\Storefront\Models\PromotionRedemption;
+use Fleetbase\Support\Http;
+
+class PromotionCode extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        return [
+            'id'             => $this->when(Http::isInternalRequest(), $this->uuid, $this->public_id),
+            'uuid'           => $this->when(Http::isInternalRequest(), $this->uuid),
+            'public_id'      => $this->when(Http::isInternalRequest(), $this->public_id),
+            'promotion_uuid' => $this->when(Http::isInternalRequest(), $this->promotion_uuid),
+            'customer_uuid'  => $this->when(Http::isInternalRequest(), $this->customer_uuid),
+            'code'           => $this->code,
+            'status'         => $this->status,
+            'usage_limit'    => $this->usage_limit,
+            'times_used'     => PromotionRedemption::counting()->where('promotion_code_uuid', $this->uuid)->count(),
+            'expires_at'     => $this->expires_at,
+            'created_at'     => $this->created_at,
+            'updated_at'     => $this->updated_at,
+        ];
+    }
+}
diff --git a/server/src/Models/Cart.php b/server/src/Models/Cart.php
index 4e65bfe8..6e3ca0bf 100644
--- a/server/src/Models/Cart.php
+++ b/server/src/Models/Cart.php
@@ -147,6 +147,30 @@ public function getEventsAttribute($events)
         return (array) json_decode($events, false);
     }
 
+    /**
+     * Promotion codes applied to the cart, stored comma separated in `discount_code`.
+     *
+     * @return string[]
+     */
+    public function getPromotionCodes(): array
+    {
+        return array_values(array_filter(array_map(
+            [PromotionCode::class, 'normalize'],
+            explode(',', (string) $this->getAttribute('discount_code'))
+        )));
+    }
+
+    /**
+     * @param string[] $codes
+     */
+    public function setPromotionCodes(array $codes): self
+    {
+        $codes = array_values(array_unique(array_filter(array_map([PromotionCode::class, 'normalize'], $codes))));
+        $this->setAttribute('discount_code', $codes ? implode(',', $codes) : null);
+
+        return $this;
+    }
+
     /**
      * Computes subtotal of cart.
      *
diff --git a/server/src/Models/Promotion.php b/server/src/Models/Promotion.php
new file mode 100644
index 00000000..996d4b03
--- /dev/null
+++ b/server/src/Models/Promotion.php
@@ -0,0 +1,174 @@
+<?php
+
+namespace Fleetbase\Storefront\Models;
+
+use Fleetbase\Casts\Json;
+use Fleetbase\Casts\PolymorphicType;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Models\File;
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasPublicId;
+use Fleetbase\Traits\HasUuid;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Carbon;
+
+class Promotion extends StorefrontModel
+{
+    use HasUuid;
+    use HasPublicId;
+    use HasApiModelBehavior;
+    use SoftDeletes;
+
+    public const TYPE_PERCENTAGE    = 'percentage';
+    public const TYPE_FIXED_AMOUNT  = 'fixed_amount';
+    public const TYPE_FREE_DELIVERY = 'free_delivery';
+    public const TYPE_BOGO          = 'bogo';
+
+    public const TYPES = [self::TYPE_PERCENTAGE, self::TYPE_FIXED_AMOUNT, self::TYPE_FREE_DELIVERY, self::TYPE_BOGO];
+
+    public const TRIGGER_AUTOMATIC = 'automatic';
+    public const TRIGGER_CODE      = 'code';
+
+    public const STATUS_DRAFT  = 'draft';
+    public const STATUS_ACTIVE = 'active';
+    public const STATUS_PAUSED = 'paused';
+    public const STATUS_ENDED  = 'ended';
+
+    public const STATUSES = [self::STATUS_DRAFT, self::STATUS_ACTIVE, self::STATUS_PAUSED, self::STATUS_ENDED];
+
+    protected $publicIdType = 'promotion';
+
+    protected $table = 'promotions';
+
+    protected $searchableColumns = ['name', 'description'];
+
+    protected $fillable = [
+        'company_uuid', 'created_by_uuid', 'owner_uuid', 'owner_type', 'name', 'description', 'status', 'trigger', 'type', 'value',
+        'max_discount_amount', 'currency', 'min_subtotal', 'min_items', 'applies_to', 'bogo_config', 'first_order_only',
+        'usage_limit', 'usage_limit_per_customer', 'budget_amount', 'stackable', 'priority', 'is_public', 'starts_at', 'ends_at',
+        'schedule', 'timezone', 'image_uuid', 'translations', 'meta',
+    ];
+
+    protected $casts = [
+        'owner_type'               => PolymorphicType::class,
+        'value'                    => 'float',
+        'max_discount_amount'      => 'integer',
+        'min_subtotal'             => 'integer',
+        'min_items'                => 'integer',
+        'applies_to'               => Json::class,
+        'bogo_config'              => Json::class,
+        'first_order_only'         => 'boolean',
+        'usage_limit'              => 'integer',
+        'usage_limit_per_customer' => 'integer',
+        'budget_amount'            => 'integer',
+        'stackable'                => 'boolean',
+        'priority'                 => 'integer',
+        'is_public'                => 'boolean',
+        'starts_at'                => 'datetime',
+        'ends_at'                  => 'datetime',
+        'schedule'                 => Json::class,
+        'translations'             => Json::class,
+        'meta'                     => Json::class,
+    ];
+
+    public function owner()
+    {
+        return $this->morphTo(__FUNCTION__, 'owner_type', 'owner_uuid');
+    }
+
+    public function codes()
+    {
+        return $this->hasMany(PromotionCode::class, 'promotion_uuid', 'uuid');
+    }
+
+    public function redemptions()
+    {
+        return $this->hasMany(PromotionRedemption::class, 'promotion_uuid', 'uuid');
+    }
+
+    public function image()
+    {
+        return $this->setConnection(config('fleetbase.connection.db'))->belongsTo(File::class, 'image_uuid', 'uuid');
+    }
+
+    public function setOwnerTypeAttribute($type)
+    {
+        $this->attributes['owner_type'] = Utils::getMutationType($type);
+    }
+
+    protected static function boot()
+    {
+        parent::boot();
+
+        static::saving(fn (Promotion $promotion) => $promotion->inferOwnerType());
+    }
+
+    /**
+     * The owner is a store or a network; infer which from the uuid when no type is given.
+     */
+    public function inferOwnerType(): void
+    {
+        if ($this->owner_uuid && empty($this->attributes['owner_type'])) {
+            $this->attributes['owner_type'] = Store::where('uuid', $this->owner_uuid)->exists() ? Store::class : Network::class;
+        }
+    }
+
+    /**
+     * Whether the promotion can apply at the given moment: active, inside its date range and
+     * inside one of its weekly schedule windows (if any).
+     *
+     * `schedule` is a list of windows like `{"days": [1,2,3,4,5], "start": "15:00", "end": "18:00"}`
+     * where days are ISO weekdays (1 = Monday) in the promotion's timezone. A window whose end is
+     * before its start runs past midnight.
+     */
+    public function isLiveAt(?Carbon $moment = null): bool
+    {
+        $moment ??= Carbon::now();
+
+        if ($this->status !== self::STATUS_ACTIVE) {
+            return false;
+        }
+
+        if ($this->starts_at && $moment->lt($this->starts_at)) {
+            return false;
+        }
+
+        if ($this->ends_at && $moment->gte($this->ends_at)) {
+            return false;
+        }
+
+        $windows = array_values(array_filter((array) ($this->schedule ?? []), 'is_array'));
+        if (empty($windows)) {
+            return true;
+        }
+
+        $local   = $moment->copy()->setTimezone($this->timezone ?: config('app.timezone', 'UTC'));
+        $minutes = $local->hour * 60 + $local->minute;
+
+        foreach ($windows as $window) {
+            $days  = array_map('intval', (array) ($window['days'] ?? [1, 2, 3, 4, 5, 6, 7]));
+            $start = static::minutesOfDay($window['start'] ?? '00:00');
+            $end   = static::minutesOfDay($window['end'] ?? '24:00');
+
+            if ($start <= $end) {
+                if (in_array($local->dayOfWeekIso, $days, true) && $minutes >= $start && $minutes < $end) {
+                    return true;
+                }
+            } elseif (
+                (in_array($local->dayOfWeekIso, $days, true) && $minutes >= $start)
+                || (in_array($local->copy()->subDay()->dayOfWeekIso, $days, true) && $minutes < $end)
+            ) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    protected static function minutesOfDay(string $time): int
+    {
+        [$hours, $minutes] = array_pad(array_map('intval', explode(':', $time)), 2, 0);
+
+        return $hours * 60 + $minutes;
+    }
+}
diff --git a/server/src/Models/PromotionCode.php b/server/src/Models/PromotionCode.php
new file mode 100644
index 00000000..c3a413f6
--- /dev/null
+++ b/server/src/Models/PromotionCode.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace Fleetbase\Storefront\Models;
+
+use Fleetbase\Casts\Json;
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasPublicId;
+use Fleetbase\Traits\HasUuid;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Str;
+
+class PromotionCode extends StorefrontModel
+{
+    use HasUuid;
+    use HasPublicId;
+    use HasApiModelBehavior;
+    use SoftDeletes;
+
+    public const STATUS_ACTIVE   = 'active';
+    public const STATUS_DISABLED = 'disabled';
+
+    protected $publicIdType = 'promo_code';
+
+    protected $table = 'promotion_codes';
+
+    protected $searchableColumns = ['code'];
+
+    protected $fillable = ['company_uuid', 'promotion_uuid', 'code', 'status', 'usage_limit', 'customer_uuid', 'expires_at', 'meta'];
+
+    protected $casts = [
+        'usage_limit' => 'integer',
+        'expires_at'  => 'datetime',
+        'meta'        => Json::class,
+    ];
+
+    public function promotion()
+    {
+        return $this->belongsTo(Promotion::class, 'promotion_uuid', 'uuid');
+    }
+
+    public function setCodeAttribute($code)
+    {
+        $this->attributes['code'] = static::normalize($code);
+    }
+
+    /**
+     * Codes are matched case-insensitively and without surrounding whitespace.
+     */
+    public static function normalize($code): string
+    {
+        return Str::upper(trim((string) $code));
+    }
+
+    /**
+     * Generate a random, unambiguous code (no 0/O/1/I).
+     */
+    public static function generate(int $length = 8, string $prefix = ''): string
+    {
+        $alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+        $code     = '';
+        for ($i = 0; $i < $length; $i++) {
+            $code .= $alphabet[random_int(0, strlen($alphabet) - 1)];
+        }
+
+        return static::normalize($prefix . $code);
+    }
+}
diff --git a/server/src/Models/PromotionRedemption.php b/server/src/Models/PromotionRedemption.php
new file mode 100644
index 00000000..693a89aa
--- /dev/null
+++ b/server/src/Models/PromotionRedemption.php
@@ -0,0 +1,55 @@
+<?php
+
+namespace Fleetbase\Storefront\Models;
+
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasUuid;
+
+class PromotionRedemption extends StorefrontModel
+{
+    use HasUuid;
+    use HasApiModelBehavior;
+
+    public const STATUS_RESERVED = 'reserved';
+    public const STATUS_REDEEMED = 'redeemed';
+    public const STATUS_RELEASED = 'released';
+
+    /**
+     * How long an uncaptured checkout holds its promotion before the use is released.
+     */
+    public const RESERVATION_MINUTES = 60;
+
+    protected $table = 'promotion_redemptions';
+
+    protected $fillable = ['company_uuid', 'promotion_uuid', 'promotion_code_uuid', 'customer_uuid', 'checkout_uuid', 'order_uuid', 'amount', 'currency', 'status', 'redeemed_at'];
+
+    protected $casts = [
+        'amount'      => 'integer',
+        'redeemed_at' => 'datetime',
+    ];
+
+    public function promotion()
+    {
+        return $this->belongsTo(Promotion::class, 'promotion_uuid', 'uuid');
+    }
+
+    public function code()
+    {
+        return $this->belongsTo(PromotionCode::class, 'promotion_code_uuid', 'uuid');
+    }
+
+    /**
+     * Redemptions that count towards limits and budgets: redeemed ones, and reservations
+     * that have not expired yet.
+     */
+    public function scopeCounting($query)
+    {
+        return $query->where(function ($query) {
+            $query->where('status', self::STATUS_REDEEMED)
+                ->orWhere(function ($query) {
+                    $query->where('status', self::STATUS_RESERVED)
+                        ->where('created_at', '>=', now()->subMinutes(self::RESERVATION_MINUTES));
+                });
+        });
+    }
+}
diff --git a/server/src/Promotions/PromotionCalculator.php b/server/src/Promotions/PromotionCalculator.php
new file mode 100644
index 00000000..2740bb4b
--- /dev/null
+++ b/server/src/Promotions/PromotionCalculator.php
@@ -0,0 +1,206 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+
+/**
+ * Computes the discount one promotion gives on a cart.
+ *
+ * Works on the amounts still payable per line (so stacked promotions apply to what earlier
+ * promotions left) and never discounts a line or the delivery fee below zero.
+ */
+class PromotionCalculator
+{
+    public const REASON_NO_ELIGIBLE_ITEMS = 'no_eligible_items';
+    public const REASON_MIN_SUBTOTAL      = 'min_subtotal';
+    public const REASON_MIN_ITEMS         = 'min_items';
+    public const REASON_PICKUP_ORDER      = 'pickup_order';
+    public const REASON_NO_DISCOUNT       = 'no_discount';
+
+    /**
+     * @param array<string, int> $remaining         amount still payable per line id
+     * @param int                $remainingDelivery delivery fee still payable
+     *
+     * @return array{lines: array<string, int>, delivery: int}|string the discount, or the reason it does not apply
+     */
+    public function calculate(Promotion $promotion, PromotionContext $context, array $remaining, int $remainingDelivery): array|string
+    {
+        $lines = $this->eligibleLines($promotion, $context);
+        if (empty($lines)) {
+            return self::REASON_NO_ELIGIBLE_ITEMS;
+        }
+
+        $eligibleSubtotal = array_sum(array_map(fn (PromotionLine $line) => $line->subtotal, $lines));
+        $eligibleQuantity = array_sum(array_map(fn (PromotionLine $line) => $line->quantity, $lines));
+
+        if ($promotion->min_subtotal && $eligibleSubtotal < $promotion->min_subtotal) {
+            return self::REASON_MIN_SUBTOTAL;
+        }
+
+        if ($promotion->min_items && $eligibleQuantity < $promotion->min_items) {
+            return self::REASON_MIN_ITEMS;
+        }
+
+        $available = [];
+        foreach ($lines as $line) {
+            $available[$line->id] = max(0, (int) ($remaining[$line->id] ?? $line->subtotal));
+        }
+
+        $discount = match ($promotion->type) {
+            Promotion::TYPE_PERCENTAGE    => ['lines' => $this->percentageOf($available, (float) $promotion->value), 'delivery' => 0],
+            Promotion::TYPE_FIXED_AMOUNT  => ['lines' => static::allocate((int) round((float) $promotion->value), $available), 'delivery' => 0],
+            Promotion::TYPE_FREE_DELIVERY => $context->isPickup ? self::REASON_PICKUP_ORDER : ['lines' => [], 'delivery' => max(0, $remainingDelivery)],
+            Promotion::TYPE_BOGO          => ['lines' => $this->buyXGetY($promotion, $lines, $available), 'delivery' => 0],
+            default                       => ['lines' => [], 'delivery' => 0],
+        };
+
+        if (is_string($discount)) {
+            return $discount;
+        }
+
+        $discount['lines'] = array_filter($discount['lines']);
+        if (array_sum($discount['lines']) + $discount['delivery'] <= 0) {
+            return self::REASON_NO_DISCOUNT;
+        }
+
+        return $discount;
+    }
+
+    /**
+     * Lines the promotion targets: limited to the owning store for store promotions, then
+     * filtered by the promotion's `applies_to` include and exclude lists.
+     *
+     * @return PromotionLine[]
+     */
+    public function eligibleLines(Promotion $promotion, PromotionContext $context): array
+    {
+        $appliesTo         = (array) ($promotion->applies_to ?? []);
+        $products          = (array) ($appliesTo['products'] ?? []);
+        $categories        = (array) ($appliesTo['categories'] ?? []);
+        $stores            = (array) ($appliesTo['stores'] ?? []);
+        $excludeProducts   = (array) ($appliesTo['exclude_products'] ?? []);
+        $excludeCategories = (array) ($appliesTo['exclude_categories'] ?? []);
+        $ownerStore        = static::ownerIsStore($promotion) ? $promotion->owner_uuid : null;
+
+        return array_values(array_filter($context->lines, function (PromotionLine $line) use ($ownerStore, $products, $categories, $stores, $excludeProducts, $excludeCategories) {
+            if ($ownerStore && $line->storeUuid !== $ownerStore) {
+                return false;
+            }
+
+            if ($line->matchesProduct($excludeProducts) || $line->matchesCategory($excludeCategories)) {
+                return false;
+            }
+
+            if ($stores && !$line->matchesStore($stores)) {
+                return false;
+            }
+
+            if ($products || $categories) {
+                return $line->matchesProduct($products) || $line->matchesCategory($categories);
+            }
+
+            return true;
+        }));
+    }
+
+    public static function ownerIsStore(Promotion $promotion): bool
+    {
+        return in_array($promotion->owner_type, [Store::class, 'storefront:store'], true);
+    }
+
+    /**
+     * @param array<string, int> $available
+     *
+     * @return array<string, int>
+     */
+    protected function percentageOf(array $available, float $percent): array
+    {
+        $percent = min(max($percent, 0), 100);
+
+        return static::allocate((int) round(array_sum($available) * $percent / 100), $available);
+    }
+
+    /**
+     * Buy X get Y: for every group of `buy_quantity + get_quantity` eligible units, the cheapest
+     * `get_quantity` units are discounted by `discount_percent` (100 = free).
+     *
+     * @param PromotionLine[]    $lines
+     * @param array<string, int> $available
+     *
+     * @return array<string, int>
+     */
+    protected function buyXGetY(Promotion $promotion, array $lines, array $available): array
+    {
+        $config  = (array) ($promotion->bogo_config ?? []);
+        $buy     = max((int) ($config['buy_quantity'] ?? 1), 1);
+        $get     = max((int) ($config['get_quantity'] ?? 1), 1);
+        $percent = min(max((float) ($config['discount_percent'] ?? 100), 0), 100);
+
+        $units = [];
+        foreach ($lines as $line) {
+            for ($i = 0; $i < $line->quantity; $i++) {
+                $units[] = ['line' => $line->id, 'price' => $line->unitPrice()];
+            }
+        }
+
+        $freeUnits = intdiv(count($units), $buy + $get) * $get;
+        if ($freeUnits === 0) {
+            return [];
+        }
+
+        usort($units, fn ($a, $b) => $a['price'] <=> $b['price']);
+
+        $discounts = [];
+        foreach (array_slice($units, 0, $freeUnits) as $unit) {
+            $discounts[$unit['line']] = ($discounts[$unit['line']] ?? 0) + $unit['price'] * $percent / 100;
+        }
+
+        $result = [];
+        foreach ($discounts as $lineId => $amount) {
+            $result[$lineId] = min((int) round($amount), $available[$lineId] ?? 0);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Split an amount across lines in proportion to their available amounts, using the largest
+     * remainder method so the parts add up exactly, and never exceeding a line's amount.
+     *
+     * @param array<string, int> $available
+     *
+     * @return array<string, int>
+     */
+    public static function allocate(int $amount, array $available): array
+    {
+        $total  = array_sum($available);
+        $amount = min(max($amount, 0), $total);
+        if ($amount === 0) {
+            return array_map(fn () => 0, $available);
+        }
+
+        $parts      = [];
+        $remainders = [];
+        foreach ($available as $key => $value) {
+            $exact            = $amount * $value / $total;
+            $parts[$key]      = (int) floor($exact);
+            $remainders[$key] = $exact - $parts[$key];
+        }
+
+        arsort($remainders);
+        $left = $amount - array_sum($parts);
+        foreach (array_keys($remainders) as $key) {
+            if ($left <= 0) {
+                break;
+            }
+            if ($parts[$key] < $available[$key]) {
+                $parts[$key]++;
+                $left--;
+            }
+        }
+
+        return $parts;
+    }
+}
diff --git a/server/src/Promotions/PromotionContext.php b/server/src/Promotions/PromotionContext.php
new file mode 100644
index 00000000..65d5860b
--- /dev/null
+++ b/server/src/Promotions/PromotionContext.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Storefront\Models\Cart;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Product;
+use Fleetbase\Storefront\Models\Store;
+use Illuminate\Support\Carbon;
+
+/**
+ * Everything the promotion engine needs to price a cart.
+ */
+class PromotionContext
+{
+    /**
+     * @param PromotionLine[] $lines
+     */
+    public function __construct(
+        public Store|Network|null $storefront,
+        public array $lines,
+        public ?string $currency = null,
+        public ?Contact $customer = null,
+        public bool $isPickup = false,
+        public int $deliveryFee = 0,
+        public ?Carbon $now = null,
+    ) {
+        $this->now ??= Carbon::now();
+    }
+
+    public static function fromCart(Cart $cart, Store|Network|null $storefront, ?Contact $customer = null, bool $isPickup = false, int $deliveryFee = 0): self
+    {
+        $items      = collect($cart->items ?? []);
+        $products   = Product::whereIn('public_id', $items->pluck('product_id')->filter()->unique()->values()->all())
+            ->get(['uuid', 'public_id', 'category_uuid', 'store_uuid'])
+            ->keyBy('public_id');
+        $storeUuids = Store::whereIn('public_id', $items->pluck('store_id')->filter()->unique()->values()->all())
+            ->pluck('uuid', 'public_id');
+
+        $lines = $items->map(function ($item) use ($products, $storeUuids) {
+            $product = $products->get(data_get($item, 'product_id'));
+
+            return new PromotionLine(
+                (string) data_get($item, 'id'),
+                (int) Utils::numbersOnly(data_get($item, 'subtotal', 0)),
+                max((int) data_get($item, 'quantity', 1), 1),
+                data_get($item, 'product_id'),
+                $product?->uuid,
+                $product?->category_uuid,
+                data_get($item, 'store_id'),
+                $storeUuids->get(data_get($item, 'store_id')) ?? $product?->store_uuid,
+            );
+        })->values()->all();
+
+        return new static($storefront, $lines, $cart->currency, $customer, $isPickup, $isPickup ? 0 : $deliveryFee);
+    }
+
+    public function subtotal(): int
+    {
+        return array_sum(array_map(fn (PromotionLine $line) => $line->subtotal, $this->lines));
+    }
+
+    /**
+     * Uuids of the stores whose items are in the cart.
+     */
+    public function storeUuids(): array
+    {
+        return array_values(array_unique(array_filter(array_map(fn (PromotionLine $line) => $line->storeUuid, $this->lines))));
+    }
+}
diff --git a/server/src/Promotions/PromotionEngine.php b/server/src/Promotions/PromotionEngine.php
new file mode 100644
index 00000000..38bdb52b
--- /dev/null
+++ b/server/src/Promotions/PromotionEngine.php
@@ -0,0 +1,331 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Models\PromotionRedemption;
+use Illuminate\Support\Collection;
+
+/**
+ * Prices a cart against the storefront's promotions.
+ *
+ * Candidates are the live automatic promotions of the storefront (and, in a network, of the
+ * stores in the cart) plus the promotions of any codes the customer entered. Each candidate is
+ * checked for eligibility and limits, then stacking is resolved: stackable promotions combine
+ * (each on what the previous ones left), a non-stackable promotion applies alone, and whichever
+ * option saves the customer more wins.
+ */
+class PromotionEngine
+{
+    public const REASON_INVALID_CODE           = 'invalid_code';
+    public const REASON_NOT_ACTIVE             = 'not_active';
+    public const REASON_NOT_APPLICABLE         = 'not_applicable';
+    public const REASON_CURRENCY_MISMATCH      = 'currency_mismatch';
+    public const REASON_FIRST_ORDER_ONLY       = 'first_order_only';
+    public const REASON_USAGE_LIMIT            = 'usage_limit_reached';
+    public const REASON_CUSTOMER_USAGE_LIMIT   = 'customer_usage_limit_reached';
+    public const REASON_BUDGET_EXHAUSTED       = 'budget_exhausted';
+    public const REASON_NOT_COMBINABLE         = 'not_combinable';
+
+    public function __construct(protected PromotionCalculator $calculator)
+    {
+    }
+
+    /**
+     * @param string[] $codes promotion codes entered by the customer
+     */
+    public function evaluate(PromotionContext $context, array $codes = []): PromotionResult
+    {
+        $rejected = [];
+        $codes    = array_values(array_unique(array_filter(array_map([PromotionCode::class, 'normalize'], $codes))));
+
+        // Resolve entered codes to their promotions.
+        $codeModels = $this->findCodes($context, $codes);
+        foreach ($codes as $code) {
+            $model  = $codeModels->get($code);
+            $reason = $model ? $this->codeRejection($model, $context) : self::REASON_INVALID_CODE;
+            if ($reason) {
+                $rejected[] = ['code' => $code, 'reason' => $reason];
+                $codeModels->forget($code);
+            }
+        }
+
+        $codeByPromotion = $codeModels->keyBy('promotion_uuid');
+        $candidates      = $this->candidates($context, $codeByPromotion->keys()->all());
+        $usage           = $this->usage($candidates->pluck('uuid')->all(), $context);
+
+        // Check each candidate on its own, at full prices.
+        $eligible = [];
+        foreach ($candidates as $promotion) {
+            $code   = $codeByPromotion->get($promotion->uuid);
+            $reason = $this->promotionRejection($promotion, $context, $usage[$promotion->uuid] ?? []);
+            $single = $reason ?? $this->discountFor($promotion, $context, $this->fullAmounts($context), $context->deliveryFee, $usage[$promotion->uuid] ?? []);
+
+            if (is_string($single)) {
+                if ($code) {
+                    $rejected[] = ['code' => $code->code, 'reason' => $single];
+                }
+                continue;
+            }
+
+            $eligible[] = ['promotion' => $promotion, 'code' => $code, 'total' => $single['total']];
+        }
+
+        usort($eligible, fn ($a, $b) => [$b['promotion']->priority, $b['total']] <=> [$a['promotion']->priority, $a['total']]);
+
+        // Option A: every stackable promotion, applied in priority order on the remaining amounts.
+        $remaining = $this->fullAmounts($context);
+        $delivery  = $context->deliveryFee;
+        $stacked   = [];
+        foreach (array_filter($eligible, fn ($candidate) => $candidate['promotion']->stackable) as $candidate) {
+            $discount = $this->discountFor($candidate['promotion'], $context, $remaining, $delivery, $usage[$candidate['promotion']->uuid] ?? []);
+            if (is_string($discount)) {
+                continue;
+            }
+
+            foreach ($discount['lines'] as $lineId => $amount) {
+                $remaining[$lineId] -= $amount;
+            }
+            $delivery -= $discount['delivery'];
+            $stacked[] = $this->appliedEntry($candidate, $discount, $context);
+        }
+        $stackedTotal = array_sum(array_map(fn ($entry) => $entry['amount'] + $entry['delivery_amount'], $stacked));
+
+        // Option B: the best single non-stackable promotion.
+        $exclusive = null;
+        foreach ($eligible as $candidate) {
+            if (!$candidate['promotion']->stackable && (!$exclusive || $candidate['total'] > $exclusive['total'])) {
+                $exclusive = $candidate;
+            }
+        }
+
+        if ($exclusive && $exclusive['total'] > $stackedTotal) {
+            $discount = $this->discountFor($exclusive['promotion'], $context, $this->fullAmounts($context), $context->deliveryFee, $usage[$exclusive['promotion']->uuid] ?? []);
+            $applied  = [$this->appliedEntry($exclusive, $discount, $context)];
+        } else {
+            $applied = $stacked;
+        }
+
+        // Codes the customer entered that lost out to a better combination.
+        $appliedUuids = array_column($applied, 'promotion_uuid');
+        foreach ($eligible as $candidate) {
+            if ($candidate['code'] && !in_array($candidate['promotion']->uuid, $appliedUuids, true)) {
+                $rejected[] = ['code' => $candidate['code']->code, 'reason' => self::REASON_NOT_COMBINABLE];
+            }
+        }
+
+        return new PromotionResult($applied, $rejected);
+    }
+
+    /**
+     * Discount for one promotion on the given amounts, capped by its maximum and remaining budget.
+     *
+     * @return array{lines: array<string, int>, delivery: int, total: int}|string
+     */
+    protected function discountFor(Promotion $promotion, PromotionContext $context, array $remaining, int $delivery, array $usage): array|string
+    {
+        $discount = $this->calculator->calculate($promotion, $context, $remaining, $delivery);
+        if (is_string($discount)) {
+            return $discount;
+        }
+
+        $caps = array_filter([
+            $promotion->max_discount_amount,
+            $promotion->budget_amount !== null ? max(0, $promotion->budget_amount - ($usage['spent'] ?? 0)) : null,
+        ], fn ($cap) => $cap !== null);
+
+        $total = array_sum($discount['lines']) + $discount['delivery'];
+        if ($caps && $total > min($caps)) {
+            // Cap the delivery discount first, then scale the item discounts into what is left.
+            $cap                  = min($caps);
+            $discount['delivery'] = min($discount['delivery'], $cap);
+            $discount['lines']    = array_filter(PromotionCalculator::allocate($cap - $discount['delivery'], $discount['lines']));
+            $total                = array_sum($discount['lines']) + $discount['delivery'];
+        }
+
+        return [...$discount, 'total' => $total];
+    }
+
+    protected function appliedEntry(array $candidate, array $discount, PromotionContext $context): array
+    {
+        $promotion = $candidate['promotion'];
+        $code      = $candidate['code'];
+        $lines     = collect($context->lines)->keyBy('id');
+
+        $storeAmounts = [];
+        foreach ($discount['lines'] as $lineId => $amount) {
+            $storeId                = $lines->get($lineId)?->storeId ?? 'unknown';
+            $storeAmounts[$storeId] = ($storeAmounts[$storeId] ?? 0) + $amount;
+        }
+
+        return [
+            'promotion_uuid'  => $promotion->uuid,
+            'promotion_id'    => $promotion->public_id,
+            'name'            => $promotion->name,
+            'type'            => $promotion->type,
+            'code'            => $code?->code,
+            'code_uuid'       => $code?->uuid,
+            'amount'          => array_sum($discount['lines']),
+            'delivery_amount' => $discount['delivery'],
+            'line_amounts'    => $discount['lines'],
+            'store_amounts'   => $storeAmounts,
+        ];
+    }
+
+    /**
+     * Why a promotion cannot apply to this context, if it cannot.
+     */
+    protected function promotionRejection(Promotion $promotion, PromotionContext $context, array $usage): ?string
+    {
+        if (!$promotion->isLiveAt($context->now)) {
+            return self::REASON_NOT_ACTIVE;
+        }
+
+        if ($promotion->type === Promotion::TYPE_FIXED_AMOUNT && $promotion->currency && $context->currency && strcasecmp($promotion->currency, $context->currency) !== 0) {
+            return self::REASON_CURRENCY_MISMATCH;
+        }
+
+        if ($promotion->usage_limit !== null && ($usage['count'] ?? 0) >= $promotion->usage_limit) {
+            return self::REASON_USAGE_LIMIT;
+        }
+
+        if ($promotion->budget_amount !== null && ($usage['spent'] ?? 0) >= $promotion->budget_amount) {
+            return self::REASON_BUDGET_EXHAUSTED;
+        }
+
+        // Customer checks run once the customer is known (at checkout); cart previews skip them.
+        if ($context->customer) {
+            if ($promotion->usage_limit_per_customer !== null && ($usage['customer_count'] ?? 0) >= $promotion->usage_limit_per_customer) {
+                return self::REASON_CUSTOMER_USAGE_LIMIT;
+            }
+
+            if ($promotion->first_order_only && $this->customerHasOrdered($context)) {
+                return self::REASON_FIRST_ORDER_ONLY;
+            }
+        }
+
+        return null;
+    }
+
+    protected function codeRejection(PromotionCode $code, PromotionContext $context): ?string
+    {
+        if ($code->status !== PromotionCode::STATUS_ACTIVE || ($code->expires_at && $context->now->gte($code->expires_at))) {
+            return self::REASON_INVALID_CODE;
+        }
+
+        if ($code->customer_uuid && $context->customer && $code->customer_uuid !== $context->customer->uuid) {
+            return self::REASON_INVALID_CODE;
+        }
+
+        if ($code->usage_limit !== null && PromotionRedemption::counting()->where('promotion_code_uuid', $code->uuid)->count() >= $code->usage_limit) {
+            return self::REASON_USAGE_LIMIT;
+        }
+
+        $promotion = $code->promotion;
+        if (!$promotion || !in_array($promotion->owner_uuid, $this->ownerUuids($context), true)) {
+            return self::REASON_NOT_APPLICABLE;
+        }
+
+        return null;
+    }
+
+    /**
+     * @return Collection<string, PromotionCode> keyed by code
+     */
+    protected function findCodes(PromotionContext $context, array $codes): Collection
+    {
+        if (empty($codes)) {
+            return collect();
+        }
+
+        return PromotionCode::with('promotion')
+            ->whereIn('code', $codes)
+            ->when($context->storefront?->company_uuid, fn ($query, $company) => $query->where('company_uuid', $company))
+            ->get()
+            ->keyBy('code');
+    }
+
+    /**
+     * @return Collection<int, Promotion>
+     */
+    protected function candidates(PromotionContext $context, array $codePromotionUuids): Collection
+    {
+        $owners = $this->ownerUuids($context);
+        if (empty($owners)) {
+            return collect();
+        }
+
+        return Promotion::query()
+            ->whereIn('owner_uuid', $owners)
+            ->where('status', Promotion::STATUS_ACTIVE)
+            ->where(function ($query) use ($codePromotionUuids) {
+                $query->where('trigger', Promotion::TRIGGER_AUTOMATIC);
+                if ($codePromotionUuids) {
+                    $query->orWhereIn('uuid', $codePromotionUuids);
+                }
+            })
+            ->get();
+    }
+
+    /**
+     * The storefront the customer is shopping in, plus the stores in the cart (network carts
+     * can use each store's own promotions on that store's items).
+     */
+    protected function ownerUuids(PromotionContext $context): array
+    {
+        return array_values(array_unique(array_filter([$context->storefront?->uuid, ...$context->storeUuids()])));
+    }
+
+    /**
+     * Counting uses per promotion: total, per customer, and amount spent from the budget.
+     *
+     * @return array<string, array{count: int, spent: int, customer_count: int}>
+     */
+    protected function usage(array $promotionUuids, PromotionContext $context): array
+    {
+        if (empty($promotionUuids)) {
+            return [];
+        }
+
+        $rows = PromotionRedemption::counting()
+            ->whereIn('promotion_uuid', $promotionUuids)
+            ->groupBy('promotion_uuid')
+            ->selectRaw('promotion_uuid, COUNT(*) as uses, COALESCE(SUM(amount), 0) as spent, SUM(CASE WHEN customer_uuid = ? THEN 1 ELSE 0 END) as customer_uses', [$context->customer?->uuid])
+            ->toBase()
+            ->get();
+
+        $usage = [];
+        foreach ($rows as $row) {
+            $usage[$row->promotion_uuid] = [
+                'count'          => (int) $row->uses,
+                'spent'          => (int) $row->spent,
+                'customer_count' => (int) $row->customer_uses,
+            ];
+        }
+
+        return $usage;
+    }
+
+    protected function customerHasOrdered(PromotionContext $context): bool
+    {
+        return Order::where('customer_uuid', $context->customer->uuid)
+            ->where('type', 'storefront')
+            ->where('status', '!=', 'canceled')
+            ->exists();
+    }
+
+    /**
+     * @return array<string, int>
+     */
+    protected function fullAmounts(PromotionContext $context): array
+    {
+        $amounts = [];
+        foreach ($context->lines as $line) {
+            $amounts[$line->id] = $line->subtotal;
+        }
+
+        return $amounts;
+    }
+}
diff --git a/server/src/Promotions/PromotionLine.php b/server/src/Promotions/PromotionLine.php
new file mode 100644
index 00000000..59dac1a4
--- /dev/null
+++ b/server/src/Promotions/PromotionLine.php
@@ -0,0 +1,44 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+/**
+ * A cart item as seen by the promotion engine.
+ */
+class PromotionLine
+{
+    public function __construct(
+        public string $id,
+        public int $subtotal,
+        public int $quantity,
+        public ?string $productId = null,
+        public ?string $productUuid = null,
+        public ?string $categoryUuid = null,
+        public ?string $storeId = null,
+        public ?string $storeUuid = null,
+    ) {
+    }
+
+    public function unitPrice(): float
+    {
+        return $this->quantity > 0 ? $this->subtotal / $this->quantity : 0.0;
+    }
+
+    /**
+     * Whether any of the given identifiers (uuids or public ids) refers to this line's product.
+     */
+    public function matchesProduct(array $ids): bool
+    {
+        return !empty(array_intersect($ids, array_filter([$this->productId, $this->productUuid])));
+    }
+
+    public function matchesCategory(array $ids): bool
+    {
+        return $this->categoryUuid !== null && in_array($this->categoryUuid, $ids, true);
+    }
+
+    public function matchesStore(array $ids): bool
+    {
+        return !empty(array_intersect($ids, array_filter([$this->storeId, $this->storeUuid])));
+    }
+}
diff --git a/server/src/Promotions/PromotionRedemptions.php b/server/src/Promotions/PromotionRedemptions.php
new file mode 100644
index 00000000..e0be01d1
--- /dev/null
+++ b/server/src/Promotions/PromotionRedemptions.php
@@ -0,0 +1,128 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\Storefront\Models\Checkout;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Models\PromotionRedemption;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Records promotion uses: reserved when a checkout is created, redeemed when its order is
+ * captured, released when the checkout is abandoned.
+ */
+class PromotionRedemptions
+{
+    /**
+     * Reserve the promotions applied to a checkout. Limits and budgets are re-checked under a
+     * row lock so concurrent checkouts cannot overspend a promotion.
+     *
+     * @throws PromotionUnavailableException when a promotion ran out since the cart was priced
+     */
+    public static function reserve(Checkout $checkout, PromotionResult $result, ?string $customerUuid): void
+    {
+        if ($result->isEmpty()) {
+            return;
+        }
+
+        DB::connection((new PromotionRedemption())->getConnectionName())->transaction(function () use ($checkout, $result, $customerUuid) {
+            foreach ($result->applied as $applied) {
+                $promotion = Promotion::where('uuid', $applied['promotion_uuid'])->lockForUpdate()->first();
+                $amount    = (int) ($applied['amount'] ?? 0) + (int) ($applied['delivery_amount'] ?? 0);
+
+                if (!$promotion || !static::hasCapacity($promotion, $applied['code_uuid'] ?? null, $customerUuid, $amount)) {
+                    throw new PromotionUnavailableException($applied['name'] ?? 'promotion');
+                }
+
+                PromotionRedemption::create([
+                    'company_uuid'        => $promotion->company_uuid,
+                    'promotion_uuid'      => $promotion->uuid,
+                    'promotion_code_uuid' => $applied['code_uuid'] ?? null,
+                    'customer_uuid'       => $customerUuid,
+                    'checkout_uuid'       => $checkout->uuid,
+                    'amount'              => $amount,
+                    'currency'            => $checkout->currency,
+                    'status'              => PromotionRedemption::STATUS_RESERVED,
+                ]);
+            }
+        });
+    }
+
+    /**
+     * Mark a checkout's promotion uses as redeemed by the captured order. The customer already
+     * paid the discounted amount, so a reservation that expired meanwhile is redeemed anyway.
+     */
+    public static function redeem(Checkout $checkout, Order $order): void
+    {
+        $result = PromotionResult::fromArray(data_get($checkout->options, 'promotions'));
+        if ($result->isEmpty()) {
+            return;
+        }
+
+        $updated = PromotionRedemption::where('checkout_uuid', $checkout->uuid)
+            ->whereIn('status', [PromotionRedemption::STATUS_RESERVED, PromotionRedemption::STATUS_RELEASED])
+            ->update([
+                'status'      => PromotionRedemption::STATUS_REDEEMED,
+                'order_uuid'  => $order->uuid,
+                'redeemed_at' => now(),
+            ]);
+
+        if ($updated > 0) {
+            return;
+        }
+
+        foreach ($result->applied as $applied) {
+            $redemption = new PromotionRedemption([
+                'company_uuid'        => $order->company_uuid,
+                'promotion_uuid'      => $applied['promotion_uuid'],
+                'promotion_code_uuid' => $applied['code_uuid'] ?? null,
+                'customer_uuid'       => $order->customer_uuid,
+                'checkout_uuid'       => $checkout->uuid,
+                'order_uuid'          => $order->uuid,
+                'amount'              => (int) ($applied['amount'] ?? 0) + (int) ($applied['delivery_amount'] ?? 0),
+                'currency'            => $checkout->currency,
+                'status'              => PromotionRedemption::STATUS_REDEEMED,
+                'redeemed_at'         => now(),
+            ]);
+            $redemption->save();
+        }
+    }
+
+    /**
+     * Release reservations of checkouts that were never captured.
+     */
+    public static function releaseStale(): int
+    {
+        return PromotionRedemption::where('status', PromotionRedemption::STATUS_RESERVED)
+            ->where('created_at', '<', now()->subMinutes(PromotionRedemption::RESERVATION_MINUTES))
+            ->update(['status' => PromotionRedemption::STATUS_RELEASED]);
+    }
+
+    protected static function hasCapacity(Promotion $promotion, ?string $codeUuid, ?string $customerUuid, int $amount): bool
+    {
+        $counting = PromotionRedemption::counting()->where('promotion_uuid', $promotion->uuid);
+
+        if ($promotion->usage_limit !== null && (clone $counting)->count() >= $promotion->usage_limit) {
+            return false;
+        }
+
+        if ($promotion->budget_amount !== null && (int) (clone $counting)->sum('amount') + $amount > $promotion->budget_amount) {
+            return false;
+        }
+
+        if ($customerUuid && $promotion->usage_limit_per_customer !== null && (clone $counting)->where('customer_uuid', $customerUuid)->count() >= $promotion->usage_limit_per_customer) {
+            return false;
+        }
+
+        if ($codeUuid) {
+            $code = PromotionCode::where('uuid', $codeUuid)->first();
+            if ($code && $code->usage_limit !== null && PromotionRedemption::counting()->where('promotion_code_uuid', $codeUuid)->count() >= $code->usage_limit) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}
diff --git a/server/src/Promotions/PromotionResult.php b/server/src/Promotions/PromotionResult.php
new file mode 100644
index 00000000..567ee8db
--- /dev/null
+++ b/server/src/Promotions/PromotionResult.php
@@ -0,0 +1,97 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+/**
+ * The discounts applied to a cart, serializable onto a checkout's options.
+ */
+class PromotionResult
+{
+    /**
+     * @param array<int, array> $applied  applied promotions with their amounts
+     * @param array<int, array> $rejected codes that could not be applied, with a reason
+     */
+    public function __construct(
+        public array $applied = [],
+        public array $rejected = [],
+    ) {
+    }
+
+    public function discountSubtotal(): int
+    {
+        return array_sum(array_column($this->applied, 'amount'));
+    }
+
+    public function discountDelivery(): int
+    {
+        return array_sum(array_column($this->applied, 'delivery_amount'));
+    }
+
+    public function discount(): int
+    {
+        return $this->discountSubtotal() + $this->discountDelivery();
+    }
+
+    public function isEmpty(): bool
+    {
+        return empty($this->applied);
+    }
+
+    /**
+     * Item discount per store public id, used to split multi-store orders.
+     */
+    public function allocationsByStore(): array
+    {
+        $allocations = [];
+        foreach ($this->applied as $applied) {
+            foreach ($applied['store_amounts'] ?? [] as $storeId => $amount) {
+                $allocations[$storeId] = ($allocations[$storeId] ?? 0) + $amount;
+            }
+        }
+
+        return $allocations;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'discount'          => $this->discount(),
+            'discount_subtotal' => $this->discountSubtotal(),
+            'discount_delivery' => $this->discountDelivery(),
+            'applied'           => $this->applied,
+            'rejected'          => $this->rejected,
+            'allocations'       => $this->allocationsByStore(),
+        ];
+    }
+
+    /**
+     * Rebuild a result from the array stored on a checkout (arrays or decoded objects).
+     */
+    public static function fromArray($data): self
+    {
+        $data = json_decode(json_encode($data ?? []), true) ?: [];
+
+        return new static((array) ($data['applied'] ?? []), (array) ($data['rejected'] ?? []));
+    }
+
+    /**
+     * Public representation for API responses (no internal uuids or per-line details).
+     */
+    public function toPublicArray(): array
+    {
+        return [
+            'discount'          => $this->discount(),
+            'discount_subtotal' => $this->discountSubtotal(),
+            'discount_delivery' => $this->discountDelivery(),
+            'applied'           => array_map(fn ($applied) => [
+                'promotion'       => $applied['promotion_id'] ?? null,
+                'name'            => $applied['name'] ?? null,
+                'type'            => $applied['type'] ?? null,
+                'code'            => $applied['code'] ?? null,
+                'amount'          => $applied['amount'] ?? 0,
+                'delivery_amount' => $applied['delivery_amount'] ?? 0,
+            ], $this->applied),
+            'rejected' => $this->rejected,
+        ];
+    }
+}
diff --git a/server/src/Promotions/PromotionUnavailableException.php b/server/src/Promotions/PromotionUnavailableException.php
new file mode 100644
index 00000000..5bc0f910
--- /dev/null
+++ b/server/src/Promotions/PromotionUnavailableException.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+class PromotionUnavailableException extends \RuntimeException
+{
+    public function __construct(public string $promotionName)
+    {
+        parent::__construct('The promotion "' . $promotionName . '" is no longer available. Please review your cart and try again.');
+    }
+}
diff --git a/server/src/Providers/StorefrontServiceProvider.php b/server/src/Providers/StorefrontServiceProvider.php
index 80d85aba..9b49c044 100644
--- a/server/src/Providers/StorefrontServiceProvider.php
+++ b/server/src/Providers/StorefrontServiceProvider.php
@@ -63,6 +63,7 @@ class StorefrontServiceProvider extends CoreServiceProvider
         \Fleetbase\Storefront\Console\Commands\SendOrderNotification::class,
         \Fleetbase\Storefront\Console\Commands\PurgeExpiredCarts::class,
         \Fleetbase\Storefront\Console\Commands\MigrateStripeSandboxCustomers::class,
+        \Fleetbase\Storefront\Console\Commands\ReleasePromotionReservations::class,
     ];
 
     /**
@@ -98,6 +99,7 @@ public function boot()
         $this->scheduleCommands(function ($schedule) {
             $schedule->command('storefront:notify-order-nearby')->everyMinute()->storeOutputInDb();
             $schedule->command('storefront:purge-carts')->daily()->storeOutputInDb();
+            $schedule->command('storefront:release-promotion-reservations')->everyFifteenMinutes()->storeOutputInDb();
         });
         $this->registerObservers();
         $this->registerMiddleware();
diff --git a/server/src/Support/QPay.php b/server/src/Support/QPay.php
index fb3e0170..bb38d4b9 100644
--- a/server/src/Support/QPay.php
+++ b/server/src/Support/QPay.php
@@ -735,6 +735,27 @@ public static function createQpayInitialLines(Cart $cart, ?ServiceQuote $service
             ];
         }
 
+        // Promotions: one negative line so the invoice total matches the discounted amount.
+        $discount = (int) data_get($checkoutOptions, 'promotions.discount_subtotal', 0) + ($isPickup ? 0 : (int) data_get($checkoutOptions, 'promotions.discount_delivery', 0));
+        if ($discount > 0) {
+            $lines[] = [
+                'line_description'    => 'Discount',
+                'line_quantity'       => number_format(1, 2, '.', ''),
+                'line_unit_price'     => number_format(-$discount, 2, '.', ''),
+                'note'                => 'Discount',
+                'classification_code' => '6511100',
+                'tax_product_code'    => '319',
+                'taxes'               => [
+                    [
+                        'tax_code'    => 'VAT',
+                        'description' => 'VAT',
+                        'amount'      => -QPay::calculateTax($discount),
+                        'note'        => 'Discount',
+                    ],
+                ],
+            ];
+        }
+
         return $lines;
     }
 
diff --git a/server/src/Support/Storefront.php b/server/src/Support/Storefront.php
index 6ef091ef..126ec063 100644
--- a/server/src/Support/Storefront.php
+++ b/server/src/Support/Storefront.php
@@ -58,6 +58,10 @@ public static function about($columns = [], $with = []): Store|Network|null
             $about = Network::select($columns)->where('key', $key)->with($with)->first();
         }
 
+        if (!$about) {
+            return null;
+        }
+
         $about->is_store   = Str::startsWith($key, 'store');
         $about->is_network = Str::startsWith($key, 'network');
 
diff --git a/server/src/routes.php b/server/src/routes.php
index 52adcd83..eb8a1be2 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -99,6 +99,12 @@ function ($router) {
                     $router->post('receipt', 'OrderController@getReceipt');
                 });
 
+                // storefront/v1/promotions
+                $router->group(['prefix' => 'promotions'], function () use ($router) {
+                    $router->get('/', 'PromotionController@query');
+                    $router->get('{id}', 'PromotionController@find');
+                });
+
                 // storefront/v1/customers
                 $router->group(['prefix' => 'customers'], function () use ($router) {
                     $router->put('{id}', 'CustomerController@update');
@@ -131,6 +137,9 @@ function ($router) {
                     $router->get('/', 'CartController@retrieve');
                     $router->get('{uniqueId}', 'CartController@retrieve');
                     $router->put('{cartId}/empty', 'CartController@empty');
+                    $router->get('{cartId}/promotions', 'CartController@promotions');
+                    $router->post('{cartId}/promo-code', 'CartController@applyPromotionCode');
+                    $router->delete('{cartId}/promo-code/{code}', 'CartController@removePromotionCode');
                     $router->post('{cartId}/{productId}', 'CartController@add');
                     $router->put('{cartId}/{lineItemId}', 'CartController@update');
                     $router->delete('{cartId}/{lineItemId}', 'CartController@remove');
@@ -214,6 +223,13 @@ function ($router, $controller) {
                         $router->fleetbaseRoutes('addon-categories');
                         $router->fleetbaseRoutes('gateways');
                         $router->fleetbaseRoutes('notification-channels');
+                        $router->fleetbaseRoutes(
+                            'promotions',
+                            function ($router, $controller) {
+                                $router->post('{id}/generate-codes', $controller('generateCodes'));
+                            }
+                        );
+                        $router->fleetbaseRoutes('promotion-codes');
                         $router->fleetbaseRoutes('reviews');
                         $router->fleetbaseRoutes('votes');
                         $router->fleetbaseRoutes('food-trucks');
diff --git a/server/tests/Support/PromotionTestHelpers.php b/server/tests/Support/PromotionTestHelpers.php
new file mode 100644
index 00000000..cfb91eed
--- /dev/null
+++ b/server/tests/Support/PromotionTestHelpers.php
@@ -0,0 +1,212 @@
+<?php
+
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Promotions\PromotionContext;
+use Fleetbase\Storefront\Promotions\PromotionLine;
+use Illuminate\Database\Eloquent\Model;
+
+if (!function_exists('promotionDb')) {
+    function promotionDb()
+    {
+        return Model::getConnectionResolver()->connection('mysql');
+    }
+
+    /**
+     * Create the tables the promotion engine reads, dropping previous copies.
+     */
+    function createPromotionSchema(): void
+    {
+        $schema = promotionDb()->getSchemaBuilder();
+        foreach (['promotion_redemptions', 'promotion_codes', 'promotions', 'products', 'stores', 'networks', 'network_stores', 'orders'] as $table) {
+            $schema->dropIfExists($table);
+        }
+
+        $schema->create('promotions', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('created_by_uuid')->nullable();
+            $table->string('owner_uuid')->nullable();
+            $table->string('owner_type')->nullable();
+            $table->string('name')->nullable();
+            $table->text('description')->nullable();
+            $table->string('status')->default('draft');
+            $table->string('trigger')->default('automatic');
+            $table->string('type')->nullable();
+            $table->decimal('value', 12, 2)->nullable();
+            $table->integer('max_discount_amount')->nullable();
+            $table->string('currency')->nullable();
+            $table->integer('min_subtotal')->nullable();
+            $table->integer('min_items')->nullable();
+            $table->text('applies_to')->nullable();
+            $table->text('bogo_config')->nullable();
+            $table->boolean('first_order_only')->default(false);
+            $table->integer('usage_limit')->nullable();
+            $table->integer('usage_limit_per_customer')->nullable();
+            $table->integer('budget_amount')->nullable();
+            $table->boolean('stackable')->default(false);
+            $table->integer('priority')->default(0);
+            $table->boolean('is_public')->default(true);
+            $table->timestamp('starts_at')->nullable();
+            $table->timestamp('ends_at')->nullable();
+            $table->text('schedule')->nullable();
+            $table->string('timezone')->nullable();
+            $table->string('image_uuid')->nullable();
+            $table->text('translations')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('promotion_codes', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('promotion_uuid')->nullable();
+            $table->string('code');
+            $table->string('status')->default('active');
+            $table->integer('usage_limit')->nullable();
+            $table->string('customer_uuid')->nullable();
+            $table->timestamp('expires_at')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('promotion_redemptions', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('promotion_uuid')->nullable();
+            $table->string('promotion_code_uuid')->nullable();
+            $table->string('customer_uuid')->nullable();
+            $table->string('checkout_uuid')->nullable();
+            $table->string('order_uuid')->nullable();
+            $table->integer('amount')->default(0);
+            $table->string('currency')->nullable();
+            $table->string('status')->default('reserved');
+            $table->timestamp('redeemed_at')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('products', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('store_uuid')->nullable();
+            $table->string('category_uuid')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        foreach (['stores', 'networks'] as $name) {
+            $schema->create($name, function ($table) {
+                $table->increments('id');
+                $table->string('uuid')->nullable();
+                $table->string('public_id')->nullable();
+                $table->string('company_uuid')->nullable();
+                $table->string('key')->nullable();
+                $table->string('name')->nullable();
+                $table->text('options')->nullable();
+                $table->timestamps();
+                $table->timestamp('deleted_at')->nullable();
+            });
+        }
+        $schema->create('network_stores', function ($table) {
+            $table->increments('id');
+            $table->string('network_uuid')->nullable();
+            $table->string('store_uuid')->nullable();
+            $table->string('category_uuid')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('orders', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('customer_uuid')->nullable();
+            $table->string('type')->nullable();
+            $table->string('status')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+    }
+
+    /**
+     * Persist a promotion. Model events do not run in the test harness, so identifiers are explicit.
+     */
+    function makePromotion(array $attributes = []): Promotion
+    {
+        static $sequence = 0;
+        $sequence++;
+
+        $promotion = new Promotion();
+        $promotion->forceFill(array_merge([
+            'uuid'         => 'promo_uuid_' . $sequence,
+            'public_id'    => 'promotion_' . $sequence,
+            'company_uuid' => 'company_uuid',
+            'owner_uuid'   => 'store_a_uuid',
+            'owner_type'   => Fleetbase\Storefront\Models\Store::class,
+            'name'         => 'Promotion ' . $sequence,
+            'status'       => Promotion::STATUS_ACTIVE,
+            'trigger'      => Promotion::TRIGGER_AUTOMATIC,
+            'type'         => Promotion::TYPE_PERCENTAGE,
+            'value'        => 10,
+        ], $attributes));
+        $promotion->save();
+
+        return $promotion;
+    }
+
+    function makePromotionCode(Promotion $promotion, string $code, array $attributes = []): PromotionCode
+    {
+        $model = new PromotionCode();
+        $model->forceFill(array_merge([
+            'uuid'           => 'code_uuid_' . strtolower($code),
+            'public_id'      => 'promo_code_' . strtolower($code),
+            'company_uuid'   => 'company_uuid',
+            'promotion_uuid' => $promotion->uuid,
+            'code'           => $code,
+            'status'         => PromotionCode::STATUS_ACTIVE,
+        ], $attributes));
+        $model->save();
+
+        return $model;
+    }
+
+    function seedPromotionStores(): void
+    {
+        promotionDb()->table('stores')->insert([
+            ['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'company_uuid' => 'company_uuid', 'key' => 'store_key_a', 'name' => 'Store A'],
+            ['uuid' => 'store_b_uuid', 'public_id' => 'store_b', 'company_uuid' => 'company_uuid', 'key' => 'store_key_b', 'name' => 'Store B'],
+        ]);
+        promotionDb()->table('networks')->insert(['uuid' => 'network_uuid', 'public_id' => 'network_m', 'company_uuid' => 'company_uuid', 'key' => 'network_key', 'name' => 'Market']);
+        promotionDb()->table('network_stores')->insert([
+            ['network_uuid' => 'network_uuid', 'store_uuid' => 'store_a_uuid'],
+            ['network_uuid' => 'network_uuid', 'store_uuid' => 'store_b_uuid'],
+        ]);
+    }
+
+    /**
+     * A context with two store A lines and one store B line (subtotal 10000).
+     */
+    function promotionContext(array $overrides = []): PromotionContext
+    {
+        $storefront = $overrides['storefront'] ?? tap(new Fleetbase\Storefront\Models\Store())->forceFill(['uuid' => 'store_a_uuid', 'public_id' => 'store_a', 'company_uuid' => 'company_uuid']);
+
+        return new PromotionContext(
+            $storefront,
+            $overrides['lines'] ?? [
+                new PromotionLine('line_1', 6000, 2, 'product_1', 'product_1_uuid', 'category_food', 'store_a', 'store_a_uuid'),
+                new PromotionLine('line_2', 1000, 1, 'product_2', 'product_2_uuid', 'category_drinks', 'store_a', 'store_a_uuid'),
+                new PromotionLine('line_3', 3000, 3, 'product_3', 'product_3_uuid', 'category_food', 'store_b', 'store_b_uuid'),
+            ],
+            $overrides['currency'] ?? 'USD',
+            $overrides['customer'] ?? null,
+            $overrides['is_pickup'] ?? false,
+            $overrides['delivery_fee'] ?? 500,
+            $overrides['now'] ?? null,
+        );
+    }
+}
diff --git a/server/tests/Unit/Promotions/PromotionCalculatorTest.php b/server/tests/Unit/Promotions/PromotionCalculatorTest.php
new file mode 100644
index 00000000..92a665eb
--- /dev/null
+++ b/server/tests/Unit/Promotions/PromotionCalculatorTest.php
@@ -0,0 +1,121 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Promotions\PromotionCalculator;
+use Fleetbase\Storefront\Promotions\PromotionLine;
+
+function calculatorPromotion(array $attributes): Promotion
+{
+    $promotion = new Promotion();
+    $promotion->forceFill(array_merge([
+        'owner_uuid' => 'network_uuid',
+        'owner_type' => Network::class,
+        'type'       => Promotion::TYPE_PERCENTAGE,
+        'value'      => 10,
+    ], $attributes));
+
+    return $promotion;
+}
+
+function calculateDiscount(array $attributes, array $context = [], ?array $remaining = null, ?int $delivery = null): array|string
+{
+    $context = promotionContext($context);
+    $full    = [];
+    foreach ($context->lines as $line) {
+        $full[$line->id] = $line->subtotal;
+    }
+
+    return (new PromotionCalculator())->calculate(calculatorPromotion($attributes), $context, $remaining ?? $full, $delivery ?? $context->deliveryFee);
+}
+
+test('allocation splits an amount proportionally, exactly and within each line', function () {
+    expect(PromotionCalculator::allocate(100, ['a' => 100, 'b' => 100, 'c' => 100]))->toBe(['a' => 34, 'b' => 33, 'c' => 33])
+        ->and(PromotionCalculator::allocate(1000, ['a' => 300, 'b' => 200]))->toBe(['a' => 300, 'b' => 200])
+        ->and(PromotionCalculator::allocate(0, ['a' => 300]))->toBe(['a' => 0])
+        ->and(PromotionCalculator::allocate(50, ['a' => 0, 'b' => 100]))->toBe(['a' => 0, 'b' => 50])
+        ->and(PromotionCalculator::allocate(10, []))->toBe([]);
+});
+
+test('percentage and fixed amount promotions discount every eligible line', function () {
+    expect(calculateDiscount(['value' => 10]))->toBe(['lines' => ['line_1' => 600, 'line_2' => 100, 'line_3' => 300], 'delivery' => 0])
+        ->and(calculateDiscount(['value' => 250]))->toBe(['lines' => ['line_1' => 6000, 'line_2' => 1000, 'line_3' => 3000], 'delivery' => 0])
+        ->and(calculateDiscount(['type' => Promotion::TYPE_FIXED_AMOUNT, 'value' => 1000]))->toBe(['lines' => ['line_1' => 600, 'line_2' => 100, 'line_3' => 300], 'delivery' => 0])
+        ->and(calculateDiscount(['type' => Promotion::TYPE_FIXED_AMOUNT, 'value' => 99999]))->toBe(['lines' => ['line_1' => 6000, 'line_2' => 1000, 'line_3' => 3000], 'delivery' => 0]);
+});
+
+test('stacked promotions only discount what previous promotions left', function () {
+    expect(calculateDiscount(['value' => 50], [], ['line_1' => 1000, 'line_2' => 0, 'line_3' => 3000]))
+        ->toBe(['lines' => ['line_1' => 500, 'line_3' => 1500], 'delivery' => 0]);
+});
+
+test('free delivery promotions cover the remaining delivery fee and never apply to pickups', function () {
+    expect(calculateDiscount(['type' => Promotion::TYPE_FREE_DELIVERY]))->toBe(['lines' => [], 'delivery' => 500])
+        ->and(calculateDiscount(['type' => Promotion::TYPE_FREE_DELIVERY], [], null, 200))->toBe(['lines' => [], 'delivery' => 200])
+        ->and(calculateDiscount(['type' => Promotion::TYPE_FREE_DELIVERY], ['is_pickup' => true, 'delivery_fee' => 0]))->toBe(PromotionCalculator::REASON_PICKUP_ORDER)
+        ->and(calculateDiscount(['type' => Promotion::TYPE_FREE_DELIVERY], [], null, 0))->toBe(PromotionCalculator::REASON_NO_DISCOUNT);
+});
+
+test('buy X get Y discounts the cheapest units of every complete group', function () {
+    // Units: 2 x 3000 (line_1), 1 x 1000 (line_2), 3 x 1000 (line_3) = 6 units -> 3 free with buy 1 get 1.
+    expect(calculateDiscount(['type' => Promotion::TYPE_BOGO, 'bogo_config' => ['buy_quantity' => 1, 'get_quantity' => 1]]))
+        ->toBe(['lines' => ['line_2' => 1000, 'line_3' => 2000], 'delivery' => 0])
+        // Buy 2 get 1 at 50% off: 6 units -> 2 discounted units.
+        ->and(calculateDiscount(['type' => Promotion::TYPE_BOGO, 'bogo_config' => ['buy_quantity' => 2, 'get_quantity' => 1, 'discount_percent' => 50]]))
+        ->toBe(['lines' => ['line_2' => 500, 'line_3' => 500], 'delivery' => 0])
+        // Not enough units for a group.
+        ->and(calculateDiscount(['type' => Promotion::TYPE_BOGO, 'bogo_config' => ['buy_quantity' => 5, 'get_quantity' => 2]]))
+        ->toBe(PromotionCalculator::REASON_NO_DISCOUNT)
+        // A free unit never exceeds what is left on its line.
+        ->and(calculateDiscount(['type' => Promotion::TYPE_BOGO, 'bogo_config' => []], [], ['line_1' => 6000, 'line_2' => 200, 'line_3' => 3000]))
+        ->toBe(['lines' => ['line_2' => 200, 'line_3' => 2000], 'delivery' => 0]);
+});
+
+test('store promotions only apply to their own store items', function () {
+    expect(calculateDiscount(['owner_uuid' => 'store_b_uuid', 'owner_type' => Store::class]))->toBe(['lines' => ['line_3' => 300], 'delivery' => 0])
+        ->and(calculateDiscount(['owner_uuid' => 'store_b_uuid', 'owner_type' => 'storefront:store']))->toBe(['lines' => ['line_3' => 300], 'delivery' => 0])
+        ->and(calculateDiscount(['owner_uuid' => 'store_c_uuid', 'owner_type' => Store::class]))->toBe(PromotionCalculator::REASON_NO_ELIGIBLE_ITEMS);
+});
+
+test('applies_to targets and excludes products categories and stores', function ($appliesTo, $expectedLines) {
+    $discount = calculateDiscount(['value' => 10, 'applies_to' => $appliesTo]);
+
+    expect(is_array($discount) ? array_keys($discount['lines']) : $discount)->toBe($expectedLines);
+})->with([
+    'products by public id'  => [['products' => ['product_2']], ['line_2']],
+    'products by uuid'       => [['products' => ['product_1_uuid']], ['line_1']],
+    'categories'             => [['categories' => ['category_food']], ['line_1', 'line_3']],
+    'products or categories' => [['products' => ['product_2'], 'categories' => ['category_food']], ['line_1', 'line_2', 'line_3']],
+    'stores'                 => [['stores' => ['store_b']], ['line_3']],
+    'excluded products'      => [['exclude_products' => ['product_1']], ['line_2', 'line_3']],
+    'excluded categories'    => [['exclude_categories' => ['category_food']], ['line_2']],
+    'nothing eligible'       => [['products' => ['unknown']], PromotionCalculator::REASON_NO_ELIGIBLE_ITEMS],
+]);
+
+test('minimum subtotal and item conditions use the eligible items only', function () {
+    expect(calculateDiscount(['min_subtotal' => 10000]))->toBeArray()
+        ->and(calculateDiscount(['min_subtotal' => 10001]))->toBe(PromotionCalculator::REASON_MIN_SUBTOTAL)
+        ->and(calculateDiscount(['min_subtotal' => 5000, 'applies_to' => ['stores' => ['store_b']]]))->toBe(PromotionCalculator::REASON_MIN_SUBTOTAL)
+        ->and(calculateDiscount(['min_items' => 6]))->toBeArray()
+        ->and(calculateDiscount(['min_items' => 7]))->toBe(PromotionCalculator::REASON_MIN_ITEMS);
+});
+
+test('unknown promotion types and zero discounts do not apply', function () {
+    expect(calculateDiscount(['type' => 'mystery']))->toBe(PromotionCalculator::REASON_NO_DISCOUNT)
+        ->and(calculateDiscount(['value' => 0]))->toBe(PromotionCalculator::REASON_NO_DISCOUNT)
+        ->and(calculateDiscount(['value' => -5]))->toBe(PromotionCalculator::REASON_NO_DISCOUNT);
+});
+
+test('promotion lines expose unit prices and match identifiers', function () {
+    $line  = new PromotionLine('line', 900, 3, 'product', 'product_uuid', null, 'store', 'store_uuid');
+    $empty = new PromotionLine('empty', 900, 0);
+
+    expect($line->unitPrice())->toBe(300.0)
+        ->and($empty->unitPrice())->toBe(0.0)
+        ->and($line->matchesCategory(['anything']))->toBeFalse()
+        ->and($line->matchesStore(['store_uuid']))->toBeTrue()
+        ->and($line->matchesProduct([]))->toBeFalse();
+});
diff --git a/server/tests/Unit/Promotions/PromotionCheckoutTest.php b/server/tests/Unit/Promotions/PromotionCheckoutTest.php
new file mode 100644
index 00000000..85b6c15e
--- /dev/null
+++ b/server/tests/Unit/Promotions/PromotionCheckoutTest.php
@@ -0,0 +1,362 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\ServiceQuote;
+use Fleetbase\Storefront\Console\Commands\ReleasePromotionReservations;
+use Fleetbase\Storefront\Http\Controllers\v1\CheckoutController;
+use Fleetbase\Storefront\Models\Cart;
+use Fleetbase\Storefront\Models\Checkout;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionRedemption;
+use Fleetbase\Storefront\Promotions\PromotionContext;
+use Fleetbase\Storefront\Promotions\PromotionRedemptions;
+use Fleetbase\Storefront\Promotions\PromotionResult;
+use Fleetbase\Storefront\Promotions\PromotionUnavailableException;
+use Fleetbase\Storefront\Support\QPay;
+use Illuminate\Http\Request;
+
+function promotionCheckout(array $attributes = []): Checkout
+{
+    $checkout = new Checkout();
+    $checkout->forceFill(array_merge(['uuid' => 'checkout_uuid', 'public_id' => 'chkt_1', 'currency' => 'USD'], $attributes));
+
+    return $checkout;
+}
+
+function appliedResult(Promotion $promotion, int $amount = 700, int $delivery = 0, ?string $codeUuid = null): PromotionResult
+{
+    return new PromotionResult([[
+        'promotion_uuid'  => $promotion->uuid,
+        'promotion_id'    => $promotion->public_id,
+        'name'            => $promotion->name,
+        'type'            => $promotion->type,
+        'code'            => $codeUuid ? 'CODE' : null,
+        'code_uuid'       => $codeUuid,
+        'amount'          => $amount,
+        'delivery_amount' => $delivery,
+        'line_amounts'    => ['line_1' => $amount],
+        'store_amounts'   => ['store_a' => $amount],
+    ]]);
+}
+
+function invokeCheckout(string $method, mixed ...$arguments): mixed
+{
+    return (new ReflectionMethod(CheckoutController::class, $method))->invoke(null, ...$arguments);
+}
+
+function promotionCart(array $items, ?string $codes = null): Cart
+{
+    $cart = new Cart();
+    $cart->forceFill(['uuid' => 'cart_uuid', 'currency' => 'USD', 'items' => $items, 'discount_code' => $codes]);
+
+    return $cart;
+}
+
+beforeEach(function () {
+    createPromotionSchema();
+    seedPromotionStores();
+    promotionDb()->table('products')->insert([
+        ['uuid' => 'product_1_uuid', 'public_id' => 'product_1', 'store_uuid' => 'store_a_uuid', 'category_uuid' => 'category_food'],
+    ]);
+    session(['storefront_key' => 'store_key_a', 'company' => 'company_uuid']);
+});
+
+test('carts become promotion contexts with product categories and store uuids', function () {
+    $cart = promotionCart([
+        (object) ['id' => 'line_1', 'product_id' => 'product_1', 'store_id' => 'store_a', 'quantity' => 2, 'subtotal' => '6,000'],
+        (object) ['id' => 'line_2', 'product_id' => 'deleted_product', 'store_id' => 'store_b', 'quantity' => 0, 'subtotal' => 1000],
+    ]);
+
+    $context = PromotionContext::fromCart($cart, null, null, true, 500);
+
+    expect($context->subtotal())->toBe(7000)
+        ->and($context->deliveryFee)->toBe(0)
+        ->and($context->isPickup)->toBeTrue()
+        ->and($context->currency)->toBe('USD')
+        ->and($context->storeUuids())->toBe(['store_a_uuid', 'store_b_uuid'])
+        ->and($context->lines[0]->categoryUuid)->toBe('category_food')
+        ->and($context->lines[1]->quantity)->toBe(1)
+        ->and($context->lines[1]->productUuid)->toBeNull();
+});
+
+test('checkout amounts subtract stored item and delivery discounts without going negative', function () {
+    $quote = tap(new ServiceQuote())->forceFill(['amount' => 500]);
+    $cart  = promotionCart([(object) ['subtotal' => 10000, 'quantity' => 1]]);
+
+    expect(invokeCheckout('calculateCheckoutAmount', $cart, $quote, ['promotions' => ['discount_subtotal' => 1000, 'discount_delivery' => 500]]))->toBe(9000)
+        ->and(invokeCheckout('calculateCheckoutAmount', $cart, $quote, ['tip' => '10%', 'promotions' => ['discount_subtotal' => 1000]]))->toBe(10500)
+        ->and(invokeCheckout('calculateCheckoutAmount', $cart, null, ['is_pickup' => true, 'promotions' => ['discount_subtotal' => 99999, 'discount_delivery' => 500]]))->toBe(0)
+        ->and(invokeCheckout('calculateCheckoutAmount', $cart, $quote, (object) ['promotions' => (object) ['discount_subtotal' => 0, 'discount_delivery' => 9999]]))->toBe(10000);
+});
+
+test('checkout pricing stores applied promotions and fails for codes that cannot be used', function () {
+    makePromotion(['value' => 10]);
+    $coded = makePromotion(['trigger' => Promotion::TRIGGER_CODE, 'value' => 5]);
+    makePromotionCode($coded, 'SMALL');
+    $cart = promotionCart([(object) ['id' => 'line_1', 'product_id' => 'product_1', 'store_id' => 'store_a', 'quantity' => 1, 'subtotal' => 10000]]);
+
+    $options = (object) ['is_pickup' => false];
+    $quote   = tap(new ServiceQuote())->forceFill(['amount' => 500]);
+    $ok      = invokeCheckout('applyPromotions', $cart, $quote, $options, null, Request::create('/', 'POST', ['promo_code' => 'small']));
+
+    expect($ok)->toBeNull()
+        ->and($options->promotions['discount'])->toBe(1000)
+        ->and($options->promotions['rejected'])->toBe([['code' => 'SMALL', 'reason' => 'not_combinable']]);
+
+    $invalid = invokeCheckout('applyPromotions', promotionCart($cart->items, 'NOPE'), null, (object) ['is_pickup' => true], null, Request::create('/', 'POST'));
+
+    expect($invalid->getStatusCode())->toBe(400)
+        ->and($invalid->getData(true)['error'])->toBe('Promotion code "NOPE" cannot be applied (invalid_code).');
+
+    $none = (object) ['is_pickup' => true];
+    promotionDb()->table('promotions')->delete();
+
+    expect(invokeCheckout('applyPromotions', $cart, null, $none, null, Request::create('/', 'POST')))->toBeNull()
+        ->and(property_exists($none, 'promotions'))->toBeFalse();
+});
+
+test('checkout promotion codes merge request and cart codes', function () {
+    $cart = promotionCart([], 'CART1');
+
+    expect(invokeCheckout('promotionCodesFor', $cart, Request::create('/', 'POST', ['promo_codes' => ['A', 'CART1']])))->toBe(['A', 'CART1'])
+        ->and(invokeCheckout('promotionCodesFor', $cart, Request::create('/', 'POST', ['promo_codes' => 'B,C'])))->toBe(['B', 'C', 'CART1'])
+        ->and(invokeCheckout('promotionCodesFor', $cart, Request::create('/', 'POST', ['discount_code' => 'D'])))->toBe(['D', 'CART1'])
+        ->and(invokeCheckout('promotionCodesFor', promotionCart([]), Request::create('/', 'POST')))->toBe([]);
+});
+
+test('checkouts reserve their promotions and are discarded when a promotion ran out', function () {
+    $schema = promotionDb()->getSchemaBuilder();
+    $schema->dropIfExists('checkouts');
+    $schema->create('checkouts', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $promotion = makePromotion(['usage_limit' => 1]);
+    promotionDb()->table('checkouts')->insert(['uuid' => 'checkout_uuid', 'public_id' => 'chkt_1']);
+    $options = (object) ['promotions' => appliedResult($promotion)->toArray()];
+
+    expect(invokeCheckout('reservePromotions', promotionCheckout(), $options, tap(new Contact())->forceFill(['uuid' => 'customer_uuid'])))->toBeNull()
+        ->and(PromotionRedemption::query()->first()->only(['promotion_uuid', 'customer_uuid', 'checkout_uuid', 'amount', 'status']))->toBe([
+            'promotion_uuid' => $promotion->uuid,
+            'customer_uuid'  => 'customer_uuid',
+            'checkout_uuid'  => 'checkout_uuid',
+            'amount'         => 700,
+            'status'         => 'reserved',
+        ]);
+
+    $second = promotionCheckout(['uuid' => 'checkout_2']);
+    promotionDb()->table('checkouts')->insert(['uuid' => 'checkout_2', 'public_id' => 'chkt_2']);
+    $second->exists = true;
+    $error          = invokeCheckout('reservePromotions', $second, $options, null);
+
+    expect($error->getData(true)['error'])->toContain('is no longer available')
+        ->and(promotionDb()->table('checkouts')->where('uuid', 'checkout_2')->value('deleted_at'))->not->toBeNull()
+        ->and(invokeCheckout('reservePromotions', promotionCheckout(), (object) [], null))->toBeNull();
+});
+
+test('reservations respect budgets, per customer limits and code limits under lock', function ($attributes, $codeLimit, $setup) {
+    $promotion = makePromotion($attributes);
+    $code      = makePromotionCode($promotion, 'CODE', ['usage_limit' => $codeLimit]);
+    $setup($promotion);
+
+    expect(fn () => PromotionRedemptions::reserve(promotionCheckout(), appliedResult($promotion, 700, 0, $code->uuid), 'customer_uuid'))
+        ->toThrow(PromotionUnavailableException::class);
+})->with([
+    'budget'       => [['budget_amount' => 1000], null, fn ($promotion) => promotionDb()->table('promotion_redemptions')->insert(['uuid' => 'r', 'promotion_uuid' => $promotion->uuid, 'amount' => 400, 'status' => 'redeemed'])],
+    'per customer' => [['usage_limit_per_customer' => 1], null, fn ($promotion) => promotionDb()->table('promotion_redemptions')->insert(['uuid' => 'r', 'promotion_uuid' => $promotion->uuid, 'customer_uuid' => 'customer_uuid', 'status' => 'redeemed'])],
+    'code limit'   => [[], 1, fn ($promotion) => promotionDb()->table('promotion_redemptions')->insert(['uuid' => 'r', 'promotion_uuid' => $promotion->uuid, 'promotion_code_uuid' => 'code_uuid_code', 'status' => 'redeemed'])],
+    'deleted'      => [[], null, fn ($promotion) => promotionDb()->table('promotions')->where('uuid', $promotion->uuid)->delete()],
+]);
+
+test('reservations succeed while capacity remains', function () {
+    $promotion = makePromotion(['budget_amount' => 2000, 'usage_limit' => 5, 'usage_limit_per_customer' => 2]);
+    $code      = makePromotionCode($promotion, 'CODE', ['usage_limit' => 3]);
+
+    PromotionRedemptions::reserve(promotionCheckout(), appliedResult($promotion, 700, 300, $code->uuid), 'customer_uuid');
+    PromotionRedemptions::reserve(promotionCheckout(), new PromotionResult(), 'customer_uuid');
+
+    expect(PromotionRedemption::query()->pluck('amount')->all())->toBe([1000]);
+});
+
+test('captured orders redeem reservations, or record the use when the reservation is gone', function () {
+    $promotion = makePromotion();
+    $checkout  = promotionCheckout(['options' => ['promotions' => appliedResult($promotion, 700, 200)->toArray()]]);
+    $order     = tap(new Order())->forceFill(['uuid' => 'order_uuid', 'company_uuid' => 'company_uuid', 'customer_uuid' => 'customer_uuid']);
+
+    PromotionRedemptions::reserve($checkout, appliedResult($promotion, 700, 200), 'customer_uuid');
+    promotionDb()->table('promotion_redemptions')->update(['uuid' => 'reserved_uuid']);
+    PromotionRedemptions::redeem($checkout, $order);
+
+    expect(PromotionRedemption::query()->get(['status', 'order_uuid', 'amount'])->toArray())->toBe([
+        ['status' => 'redeemed', 'order_uuid' => 'order_uuid', 'amount' => 900],
+    ]);
+
+    promotionDb()->table('promotion_redemptions')->delete();
+    PromotionRedemptions::redeem($checkout, $order);
+    PromotionRedemptions::redeem(promotionCheckout(), $order);
+
+    expect(PromotionRedemption::query()->get(['status', 'order_uuid', 'customer_uuid', 'amount'])->toArray())->toBe([
+        ['status' => 'redeemed', 'order_uuid' => 'order_uuid', 'customer_uuid' => 'customer_uuid', 'amount' => 900],
+    ]);
+});
+
+test('stale reservations are released by the scheduled command', function () {
+    $promotion = makePromotion();
+    promotionDb()->table('promotion_redemptions')->insert([
+        ['uuid' => 'old', 'promotion_uuid' => $promotion->uuid, 'status' => 'reserved', 'created_at' => now()->subHours(2)],
+        ['uuid' => 'new', 'promotion_uuid' => $promotion->uuid, 'status' => 'reserved', 'created_at' => now()],
+        ['uuid' => 'done', 'promotion_uuid' => $promotion->uuid, 'status' => 'redeemed', 'created_at' => now()->subHours(2)],
+    ]);
+    $command = new class extends ReleasePromotionReservations {
+        public array $lines = [];
+
+        public function info($string, $verbosity = null)
+        {
+            $this->lines[] = $string;
+        }
+    };
+
+    expect($command->handle())->toBe(0)
+        ->and($command->lines)->toBe(['Released 1 stale promotion reservation(s).'])
+        ->and(promotionDb()->table('promotion_redemptions')->orderBy('uuid')->pluck('status', 'uuid')->all())->toBe(['done' => 'redeemed', 'new' => 'reserved', 'old' => 'released']);
+});
+
+test('captures record the discount as a credit transaction item', function () {
+    $schema = promotionDb()->getSchemaBuilder();
+    $schema->dropIfExists('transaction_items');
+    $schema->create('transaction_items', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('transaction_uuid')->nullable();
+        $table->integer('amount')->nullable();
+        $table->string('currency')->nullable();
+        $table->string('details')->nullable();
+        $table->string('code')->nullable();
+        $table->text('meta')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $promotion   = makePromotion(['name' => 'Fall sale']);
+    $transaction = tap(new Fleetbase\Models\Transaction())->forceFill(['uuid' => 'transaction_uuid']);
+
+    invokeCheckout('createDiscountTransactionItem', $transaction, appliedResult($promotion, 700, 300), 'USD');
+    invokeCheckout('createDiscountTransactionItem', $transaction, new PromotionResult(), 'USD');
+
+    $item = promotionDb()->table('transaction_items')->first();
+
+    expect(promotionDb()->table('transaction_items')->count())->toBe(1)
+        ->and((int) $item->amount)->toBe(1000)
+        ->and(json_decode($item->meta, true)['direction'])->toBe('credit')
+        ->and($item->code)->toBe('discount')
+        ->and($item->details)->toBe('Discount: Fall sale')
+        ->and(json_decode($item->meta, true)['promotions'][0]['amount'])->toBe(700);
+});
+
+test('QPay invoices include a negative discount line', function () {
+    $cart  = promotionCart([(object) ['subtotal' => 10000, 'quantity' => 1]]);
+    $quote = tap(new ServiceQuote())->forceFill(['amount' => 500]);
+
+    $delivery = collect(QPay::createQpayInitialLines($cart, $quote, ['promotions' => ['discount_subtotal' => 1000, 'discount_delivery' => 500]]))->firstWhere('line_description', 'Discount');
+    $pickup   = collect(QPay::createQpayInitialLines($cart, null, ['is_pickup' => true, 'promotions' => ['discount_subtotal' => 1000, 'discount_delivery' => 500]]))->firstWhere('line_description', 'Discount');
+    $none     = collect(QPay::createQpayInitialLines($cart, $quote, []))->firstWhere('line_description', 'Discount');
+
+    expect($delivery['line_unit_price'])->toBe('-1500.00')
+        ->and($delivery['taxes'][0]['amount'])->toBe(-QPay::calculateTax(1500))
+        ->and($pickup['line_unit_price'])->toBe('-1000.00')
+        ->and($none)->toBeNull();
+});
+
+function createCheckoutPromotionTables(): void
+{
+    $schema = promotionDb()->getSchemaBuilder();
+    foreach (['carts', 'gateways', 'contacts', 'service_quotes'] as $table) {
+        $schema->dropIfExists($table);
+    }
+    $schema->create('carts', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('checkout_uuid')->nullable();
+        $table->string('customer_id')->nullable();
+        $table->string('unique_identifier')->nullable();
+        $table->string('currency')->nullable();
+        $table->string('discount_code')->nullable();
+        $table->text('items')->nullable();
+        $table->text('events')->nullable();
+        $table->timestamp('expires_at')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('gateways', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('code')->nullable();
+        $table->string('owner_uuid')->nullable();
+        $table->string('type')->nullable();
+        $table->text('config')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('contacts', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('type')->nullable();
+        $table->text('meta')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    $schema->create('service_quotes', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->integer('amount')->nullable();
+        $table->text('meta')->nullable();
+        $table->timestamp('expired_at')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    promotionDb()->table('carts')->insert([
+        'uuid'              => 'cart_uuid',
+        'public_id'         => 'cart_public',
+        'company_uuid'      => 'company_uuid',
+        'unique_identifier' => 'browser-cart',
+        'currency'          => 'USD',
+        'items'             => json_encode([['id' => 'line_1', 'store_id' => 'store_a', 'quantity' => 1, 'subtotal' => 2000]]),
+        'events'            => '[]',
+    ]);
+}
+
+test('checkout initialization and stripe updates refuse promotion codes that cannot be applied', function () {
+    createCheckoutPromotionTables();
+    promotionDb()->table('contacts')->insert(['uuid' => 'customer_uuid', 'public_id' => 'contact_abcdefgh', 'company_uuid' => 'company_uuid', 'type' => 'customer']);
+    promotionDb()->table('gateways')->insert(['uuid' => 'stripe_uuid', 'code' => 'stripe', 'owner_uuid' => 'store_a_uuid', 'type' => 'stripe', 'config' => '{}']);
+    session(['storefront_store' => 'store_a_uuid', 'storefront_network' => null]);
+
+    $before = (new CheckoutController())->beforeCheckout(Fleetbase\Storefront\Http\Requests\InitializeCheckoutRequest::create('/', 'POST', [
+        'gateway'    => 'cash',
+        'cash'       => true,
+        'cart'       => 'browser-cart',
+        'pickup'     => true,
+        'promo_code' => 'nope',
+    ]));
+    $update = (new CheckoutController())->updateStripePaymentIntent(Request::create('/', 'POST', [
+        'customer'   => 'contact_abcdefgh',
+        'cart'       => 'browser-cart',
+        'pickup'     => true,
+        'promo_code' => 'nope',
+    ]));
+
+    expect($before->getData(true)['error'])->toBe('Promotion code "NOPE" cannot be applied (invalid_code).')
+        ->and($update->getData(true)['error'])->toBe('Promotion code "NOPE" cannot be applied (invalid_code).');
+});
diff --git a/server/tests/Unit/Promotions/PromotionEndpointsTest.php b/server/tests/Unit/Promotions/PromotionEndpointsTest.php
new file mode 100644
index 00000000..5ea1db72
--- /dev/null
+++ b/server/tests/Unit/Promotions/PromotionEndpointsTest.php
@@ -0,0 +1,297 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\Storefront\Http\Controllers\PromotionController as InternalPromotionController;
+use Fleetbase\Storefront\Http\Controllers\v1\CartController;
+use Fleetbase\Storefront\Http\Controllers\v1\PromotionController;
+use Fleetbase\Storefront\Http\Filter\PromotionCodeFilter;
+use Fleetbase\Storefront\Http\Filter\PromotionFilter;
+use Fleetbase\Storefront\Http\Requests\PromotionRequest;
+use Fleetbase\Storefront\Http\Resources\Promotion as PromotionResource;
+use Fleetbase\Storefront\Http\Resources\PromotionCode as PromotionCodeResource;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Support\Storefront;
+use Illuminate\Http\Request;
+
+function promotionRequest(array $input = [], string $method = 'GET'): Request
+{
+    $request = Request::create('/', $method, $input);
+    $request->setLaravelSession(new Illuminate\Session\Store('promotions', new Illuminate\Session\ArraySessionHandler(120)));
+    app()->instance('request', $request);
+
+    return $request;
+}
+
+function seedPromotionCart(?string $codes = null): void
+{
+    $schema = promotionDb()->getSchemaBuilder();
+    $schema->dropIfExists('carts');
+    $schema->create('carts', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid')->nullable();
+        $table->string('user_uuid')->nullable();
+        $table->string('checkout_uuid')->nullable();
+        $table->string('customer_id')->nullable();
+        $table->string('unique_identifier')->nullable();
+        $table->string('currency')->nullable();
+        $table->string('discount_code')->nullable();
+        $table->text('items')->nullable();
+        $table->text('events')->nullable();
+        $table->timestamp('expires_at')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    promotionDb()->table('carts')->insert([
+        'uuid'              => 'cart_uuid',
+        'public_id'         => 'cart_public',
+        'unique_identifier' => 'cart_public',
+        'currency'          => 'USD',
+        'discount_code'     => $codes,
+        'items'             => json_encode([['id' => 'line_1', 'product_id' => 'product_unlisted', 'store_id' => 'store_a', 'quantity' => 1, 'subtotal' => 10000]]),
+        'events'            => '[]',
+        'expires_at'        => now()->addDay(),
+    ]);
+    $schema->dropIfExists('service_quotes');
+    $schema->create('service_quotes', function ($table) {
+        $table->increments('id');
+        $table->string('uuid')->nullable();
+        $table->string('public_id')->nullable();
+        $table->integer('amount')->nullable();
+        $table->timestamp('expired_at')->nullable();
+        $table->timestamps();
+        $table->timestamp('deleted_at')->nullable();
+    });
+    promotionDb()->table('service_quotes')->insert(['uuid' => 'quote_uuid', 'public_id' => 'quote_public', 'amount' => 500]);
+}
+
+function cartController(): CartController
+{
+    return new class extends CartController {
+        protected function retrieveCart(?string $uniqueId): Fleetbase\Storefront\Models\Cart
+        {
+            return Fleetbase\Storefront\Models\Cart::where('public_id', $uniqueId)->firstOrFail();
+        }
+    };
+}
+
+beforeEach(function () {
+    createPromotionSchema();
+    seedPromotionStores();
+    promotionDb()->table('products')->insert(['uuid' => 'product_1_uuid', 'public_id' => 'product_1', 'store_uuid' => 'store_a_uuid']);
+    session(['storefront_key' => 'store_key_a', 'storefront_store' => 'store_a_uuid', 'storefront_network' => null, 'company' => 'company_uuid']);
+});
+
+test('customers apply, preview and remove promotion codes on a cart', function () {
+    seedPromotionCart();
+    $coded = makePromotion(['trigger' => Promotion::TRIGGER_CODE, 'value' => 20]);
+    makePromotionCode($coded, 'TWENTY');
+    makePromotion(['type' => Promotion::TYPE_FREE_DELIVERY, 'stackable' => true]);
+
+    $invalid = cartController()->applyPromotionCode('cart_public', promotionRequest(['code' => 'nope'], 'POST'));
+    $empty   = cartController()->applyPromotionCode('cart_public', promotionRequest([], 'POST'));
+    $applied = cartController()->applyPromotionCode('cart_public', promotionRequest(['code' => ' twenty ', 'service_quote' => 'quote_public'], 'POST'))->getData(true);
+
+    expect($invalid->getData(true))->toBe(['error' => 'Promotion code "NOPE" cannot be applied (invalid_code).'])
+        ->and($empty->getData(true))->toBe(['error' => 'A promotion code is required.'])
+        ->and($applied['promotions']['discount'])->toBe(2000)
+        ->and(array_column($applied['promotions']['applied'], 'code'))->toBe(['TWENTY'])
+        ->and(promotionDb()->table('carts')->value('discount_code'))->toBe('TWENTY');
+
+    $preview       = cartController()->promotions('cart_public', promotionRequest(['service_quote' => 'quote_public']))->getData(true);
+    $pickupPreview = cartController()->promotions('cart_public', promotionRequest(['pickup' => true]))->getData(true);
+    $removed       = cartController()->removePromotionCode('cart_public', 'twenty', promotionRequest(['service_quote' => 'quote_public'], 'DELETE'))->getData(true);
+
+    expect($preview['discount'])->toBe(2000)
+        ->and($pickupPreview['discount_delivery'])->toBe(0)
+        ->and($removed['promotions']['applied'])->toHaveCount(1)
+        ->and($removed['promotions']['discount'])->toBe(500)
+        ->and(promotionDb()->table('carts')->value('discount_code'))->toBeNull();
+});
+
+test('codes that only lose to a better promotion stay on the cart', function () {
+    seedPromotionCart();
+    $coded = makePromotion(['trigger' => Promotion::TRIGGER_CODE, 'value' => 5]);
+    makePromotionCode($coded, 'FIVE');
+    makePromotion(['value' => 30]);
+
+    $response = cartController()->applyPromotionCode('cart_public', promotionRequest(['code' => 'FIVE'], 'POST'))->getData(true);
+
+    expect($response['promotions']['rejected'])->toBe([['code' => 'FIVE', 'reason' => 'not_combinable']])
+        ->and(promotionDb()->table('carts')->value('discount_code'))->toBe('FIVE');
+});
+
+test('the storefront lists its live public promotions, and network apps include member stores', function () {
+    $live    = makePromotion(['name' => 'Live', 'priority' => 1]);
+    $network = makePromotion(['name' => 'Network', 'owner_uuid' => 'network_uuid', 'owner_type' => Fleetbase\Storefront\Models\Network::class]);
+    $storeB  = makePromotion(['name' => 'Store B', 'owner_uuid' => 'store_b_uuid']);
+    makePromotion(['name' => 'Hidden', 'is_public' => false]);
+    makePromotion(['name' => 'Draft', 'status' => Promotion::STATUS_DRAFT]);
+    makePromotion(['name' => 'Expired', 'ends_at' => now()->subDay()]);
+    promotionRequest();
+    $controller = new PromotionController();
+
+    expect(collect($controller->query(promotionRequest())->resolve())->pluck('name')->all())->toBe(['Live'])
+        ->and($controller->find($live->public_id)->resolve()['name'])->toBe('Live')
+        ->and($controller->find($storeB->public_id)->getStatusCode())->toBe(404);
+
+    session(['storefront_key' => 'network_key', 'storefront_store' => null, 'storefront_network' => 'network_uuid']);
+
+    expect(collect($controller->query(promotionRequest())->resolve())->pluck('name')->sort()->values()->all())->toBe(['Live', 'Network', 'Store B'])
+        ->and(collect($controller->query(promotionRequest(['store' => 'store_b']))->resolve())->pluck('name')->all())->toBe(['Store B'])
+        ->and($controller->find($network->public_id)->resolve()['id'])->toBe($network->public_id);
+});
+
+test('admins generate unique promotion codes', function () {
+    $promotion  = makePromotion(['trigger' => Promotion::TRIGGER_AUTOMATIC]);
+    $controller = new InternalPromotionController();
+
+    $batch = $controller->generateCodes($promotion->uuid, promotionRequest(['count' => 3, 'length' => 6, 'prefix' => 'fall-', 'usage_limit' => 1], 'POST'))->getData(true);
+    $named = $controller->generateCodes($promotion->public_id, promotionRequest(['code' => 'welcome'], 'POST'))->getData(true);
+    $dupe  = $controller->generateCodes($promotion->uuid, promotionRequest(['code' => 'WELCOME'], 'POST'));
+    $none  = $controller->generateCodes('missing', promotionRequest([], 'POST'));
+
+    expect($batch['codes'])->toHaveCount(3)
+        ->and(collect($batch['codes'])->every(fn ($code) => str_starts_with($code['code'], 'FALL-') && strlen($code['code']) === 11 && $code['usage_limit'] === 1))->toBeTrue()
+        ->and(array_column($named['codes'], 'code'))->toBe(['WELCOME'])
+        ->and($dupe->getStatusCode())->toBe(400)
+        ->and($none->getStatusCode())->toBe(404)
+        ->and(PromotionCode::query()->count())->toBe(4)
+        ->and(promotionDb()->table('promotions')->where('uuid', $promotion->uuid)->value('trigger'))->toBe(Promotion::TRIGGER_CODE);
+});
+
+test('code generation skips collisions and gives up after too many attempts', function () {
+    $promotion = makePromotion(['trigger' => Promotion::TRIGGER_CODE]);
+    makePromotionCode($promotion, 'TAKEN');
+    $controller = new class extends InternalPromotionController {
+        public array $sequence = ['TAKEN', 'FRESH1', 'FRESH1', 'FRESH2'];
+
+        protected function generateCode(int $length, string $prefix): string
+        {
+            return array_shift($this->sequence) ?? 'TAKEN';
+        }
+    };
+
+    $generated = $controller->generateCodes($promotion->uuid, promotionRequest(['count' => 2], 'POST'))->getData(true);
+    $exhausted = $controller->generateCodes($promotion->uuid, promotionRequest(['count' => 1], 'POST'))->getData(true);
+
+    expect(array_column($generated['codes'], 'code'))->toBe(['FRESH1', 'FRESH2'])
+        ->and($exhausted['codes'])->toBe([]);
+});
+
+test('promotion validation requires an owner from the company and valid discount settings', function () {
+    session(['company' => 'company_uuid']);
+    $request  = PromotionRequest::createFrom(promotionRequest([], 'POST'));
+    $rules    = $request->rules();
+    $owner    = $rules['owner_uuid'][2];
+    $failures = [];
+
+    $owner('owner_uuid', 'store_a_uuid', function ($message) use (&$failures) {
+        $failures[] = $message;
+    });
+    $owner('owner_uuid', 'network_uuid', function ($message) use (&$failures) {
+        $failures[] = $message;
+    });
+    $owner('owner_uuid', 'someone_elses_store', function ($message) use (&$failures) {
+        $failures[] = $message;
+    });
+
+    expect($rules['name'][0])->toBe('required')
+        ->and($rules['type'][1])->toBe('in:percentage,fixed_amount,free_delivery,bogo')
+        ->and($rules['value'][3])->toBe('required_if:type,percentage,fixed_amount')
+        ->and($failures)->toBe(['The promotion must belong to one of your stores or networks.'])
+        ->and(PromotionRequest::createFrom(promotionRequest([], 'PUT'))->rules()['name'][0])->toBe('sometimes')
+        ->and($request->authorize())->toBeFalse();
+});
+
+test('promotion filters scope to the company and support owner, status, type and promotion', function () {
+    makePromotion(['name' => 'A', 'status' => Promotion::STATUS_ACTIVE]);
+    $other = makePromotion(['name' => 'B', 'owner_uuid' => 'store_b_uuid', 'type' => Promotion::TYPE_BOGO, 'status' => Promotion::STATUS_PAUSED]);
+    makePromotion(['name' => 'C', 'company_uuid' => 'other_company']);
+    makePromotionCode($other, 'BCODE');
+
+    $filter = function (string $class, $builder, array $calls) {
+        $instance = (new ReflectionClass($class))->newInstanceWithoutConstructor();
+        $session  = new Illuminate\Session\Store('filter', new Illuminate\Session\ArraySessionHandler(1));
+        $session->put('company', 'company_uuid');
+        foreach (['builder' => $builder, 'session' => $session] as $property => $value) {
+            $reflection = new ReflectionProperty(Fleetbase\Http\Filter\Filter::class, $property);
+            $reflection->setValue($instance, $value);
+        }
+        $instance->queryForInternal();
+        foreach ($calls as $method => $argument) {
+            $instance->{$method}($argument);
+        }
+
+        return $builder->pluck('name')->all();
+    };
+
+    expect($filter(PromotionFilter::class, Promotion::query(), []))->toBe(['A', 'B'])
+        ->and($filter(PromotionFilter::class, Promotion::query(), ['owner' => 'store_b_uuid']))->toBe(['B'])
+        ->and($filter(PromotionFilter::class, Promotion::query(), ['status' => 'active']))->toBe(['A'])
+        ->and($filter(PromotionFilter::class, Promotion::query(), ['type' => Promotion::TYPE_BOGO]))->toBe(['B'])
+        ->and(PromotionCode::query()->count())->toBe(1);
+
+    $codes   = (new ReflectionClass(PromotionCodeFilter::class))->newInstanceWithoutConstructor();
+    $builder = PromotionCode::query();
+    (new ReflectionProperty(Fleetbase\Http\Filter\Filter::class, 'builder'))->setValue($codes, $builder);
+    $session = new Illuminate\Session\Store('filter', new Illuminate\Session\ArraySessionHandler(1));
+    $session->put('company', 'company_uuid');
+    (new ReflectionProperty(Fleetbase\Http\Filter\Filter::class, 'session'))->setValue($codes, $session);
+    $codes->queryForInternal();
+    $codes->promotion($other->uuid);
+
+    expect($builder->pluck('code')->all())->toBe(['BCODE']);
+});
+
+test('promotion resources expose usage stats internally and hide internals publicly', function () {
+    $promotion = makePromotion(['name' => 'Stats', 'usage_limit' => 10, 'budget_amount' => 5000]);
+    $code      = makePromotionCode($promotion, 'STATS');
+    promotionDb()->table('promotion_redemptions')->insert([
+        ['uuid' => 'r1', 'promotion_uuid' => $promotion->uuid, 'promotion_code_uuid' => $code->uuid, 'amount' => 300, 'status' => 'redeemed', 'created_at' => now()],
+        ['uuid' => 'r2', 'promotion_uuid' => $promotion->uuid, 'promotion_code_uuid' => $code->uuid, 'amount' => 200, 'status' => 'reserved', 'created_at' => now()],
+    ]);
+
+    $public = (new PromotionResource($promotion))->resolve(promotionRequest());
+
+    expect($public['id'])->toBe($promotion->public_id)
+        ->and($public)->not->toHaveKey('budget_amount')
+        ->and((new PromotionCodeResource($code))->resolve(promotionRequest()))->toMatchArray(['id' => $code->public_id, 'code' => 'STATS', 'times_used' => 2]);
+
+    $internal = promotionRequest();
+    $internal->setRouteResolver(fn () => new class {
+        public array $action = [];
+
+        public function uri(): string
+        {
+            return 'int/v1/storefront/promotions';
+        }
+    });
+    $resource = (new PromotionResource($promotion))->resolve($internal);
+
+    expect($resource['id'])->toBe($promotion->uuid)
+        ->and($resource['stats'])->toBe(['redemptions' => 1, 'discount_given' => 300])
+        ->and($resource['budget_amount'])->toBe(5000);
+});
+
+test('storefront lookup returns null for an unknown storefront key', function () {
+    session(['storefront_key' => 'store_missing']);
+
+    expect(Storefront::about())->toBeNull();
+});
+
+test('promotion models expose their owner, codes and redemptions', function () {
+    $promotion = makePromotion(['owner_uuid' => 'store_a_uuid']);
+    $code      = makePromotionCode($promotion, 'REL');
+    promotionDb()->table('promotion_redemptions')->insert(['uuid' => 'rel', 'promotion_uuid' => $promotion->uuid, 'promotion_code_uuid' => $code->uuid, 'status' => 'redeemed']);
+    $redemption = Fleetbase\Storefront\Models\PromotionRedemption::query()->first();
+
+    expect($promotion->codes()->pluck('code')->all())->toBe(['REL'])
+        ->and($promotion->redemptions()->count())->toBe(1)
+        ->and($promotion->owner()->getRelated())->toBeInstanceOf(Fleetbase\Storefront\Models\Store::class)
+        ->and($redemption->promotion->uuid)->toBe($promotion->uuid)
+        ->and($redemption->code->code)->toBe('REL');
+});
diff --git a/server/tests/Unit/Promotions/PromotionEngineTest.php b/server/tests/Unit/Promotions/PromotionEngineTest.php
new file mode 100644
index 00000000..30cbb2c1
--- /dev/null
+++ b/server/tests/Unit/Promotions/PromotionEngineTest.php
@@ -0,0 +1,296 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Promotions\PromotionCalculator;
+use Fleetbase\Storefront\Promotions\PromotionEngine;
+use Fleetbase\Storefront\Promotions\PromotionResult;
+use Illuminate\Support\Carbon;
+
+function promotionEngine(): PromotionEngine
+{
+    return new PromotionEngine(new PromotionCalculator());
+}
+
+function networkStorefront(): Network
+{
+    return tap(new Network())->forceFill(['uuid' => 'network_uuid', 'public_id' => 'network_m', 'company_uuid' => 'company_uuid']);
+}
+
+function promotionCustomer(string $uuid = 'customer_uuid'): Contact
+{
+    return tap(new Contact())->forceFill(['uuid' => $uuid]);
+}
+
+function redemption(Promotion $promotion, array $attributes = []): void
+{
+    promotionDb()->table('promotion_redemptions')->insert(array_merge([
+        'uuid'           => uniqid('redemption_'),
+        'promotion_uuid' => $promotion->uuid,
+        'amount'         => 100,
+        'status'         => 'redeemed',
+        'created_at'     => now(),
+        'updated_at'     => now(),
+    ], $attributes));
+}
+
+beforeEach(function () {
+    createPromotionSchema();
+});
+
+test('automatic promotions of the storefront apply without a code', function () {
+    $promotion = makePromotion(['value' => 10, 'owner_uuid' => 'store_a_uuid']);
+    makePromotion(['value' => 50, 'trigger' => Promotion::TRIGGER_CODE]);
+    makePromotion(['value' => 50, 'status' => Promotion::STATUS_DRAFT]);
+    makePromotion(['value' => 50, 'owner_uuid' => 'someone_else']);
+
+    $result = promotionEngine()->evaluate(promotionContext());
+
+    expect(array_column($result->applied, 'promotion_uuid'))->toBe([$promotion->uuid])
+        // Store A promotion: only store A items (7000).
+        ->and($result->discountSubtotal())->toBe(700)
+        ->and($result->discountDelivery())->toBe(0)
+        ->and($result->allocationsByStore())->toBe(['store_a' => 700])
+        ->and($result->rejected)->toBe([]);
+});
+
+test('network carts can use the network and each store promotions', function () {
+    makePromotion(['owner_uuid' => 'network_uuid', 'owner_type' => Network::class, 'type' => Promotion::TYPE_FREE_DELIVERY, 'stackable' => true]);
+    makePromotion(['owner_uuid' => 'store_b_uuid', 'value' => 20, 'stackable' => true]);
+
+    $result = promotionEngine()->evaluate(promotionContext(['storefront' => networkStorefront()]));
+
+    expect($result->discountDelivery())->toBe(500)
+        ->and($result->discountSubtotal())->toBe(600)
+        ->and($result->allocationsByStore())->toBe(['store_b' => 600])
+        ->and($result->discount())->toBe(1100);
+});
+
+test('codes unlock code promotions and report why other codes cannot be used', function () {
+    $coded   = makePromotion(['trigger' => Promotion::TRIGGER_CODE, 'value' => 25]);
+    $foreign = makePromotion(['trigger' => Promotion::TRIGGER_CODE, 'owner_uuid' => 'other_store']);
+    makePromotionCode($coded, 'SAVE25');
+    makePromotionCode($coded, 'OFF', ['status' => PromotionCode::STATUS_DISABLED]);
+    makePromotionCode($coded, 'OLD', ['expires_at' => now()->subDay()]);
+    makePromotionCode($coded, 'VIP', ['customer_uuid' => 'someone_else']);
+    makePromotionCode($coded, 'ONCE', ['usage_limit' => 1]);
+    makePromotionCode($foreign, 'ELSEWHERE');
+    redemption($coded, ['promotion_code_uuid' => 'code_uuid_once']);
+
+    $result = promotionEngine()->evaluate(
+        promotionContext(['customer' => promotionCustomer()]),
+        [' save25 ', 'off', 'OLD', 'vip', 'ONCE', 'ELSEWHERE', 'MISSING', '']
+    );
+
+    expect(array_column($result->applied, 'code'))->toBe(['SAVE25'])
+        ->and($result->discountSubtotal())->toBe(1750)
+        ->and($result->rejected)->toBe([
+            ['code' => 'OFF', 'reason' => PromotionEngine::REASON_INVALID_CODE],
+            ['code' => 'OLD', 'reason' => PromotionEngine::REASON_INVALID_CODE],
+            ['code' => 'VIP', 'reason' => PromotionEngine::REASON_INVALID_CODE],
+            ['code' => 'ONCE', 'reason' => PromotionEngine::REASON_USAGE_LIMIT],
+            ['code' => 'ELSEWHERE', 'reason' => PromotionEngine::REASON_NOT_APPLICABLE],
+            ['code' => 'MISSING', 'reason' => PromotionEngine::REASON_INVALID_CODE],
+        ]);
+});
+
+test('promotion rules reject codes with the reason they do not apply', function ($attributes, $context, $reason, $setup = null) {
+    $promotion = makePromotion(array_merge(['trigger' => Promotion::TRIGGER_CODE], $attributes));
+    makePromotionCode($promotion, 'CODE');
+    if ($setup) {
+        $setup($promotion);
+    }
+
+    $result = promotionEngine()->evaluate(promotionContext($context), ['CODE']);
+
+    expect($result->applied)->toBe([])
+        ->and($result->rejected)->toBe([['code' => 'CODE', 'reason' => $reason]]);
+})->with([
+    'not started'           => [['starts_at' => '2999-01-01 00:00:00'], [], PromotionEngine::REASON_NOT_ACTIVE],
+    'currency mismatch'     => [['type' => Promotion::TYPE_FIXED_AMOUNT, 'value' => 500, 'currency' => 'EUR'], [], PromotionEngine::REASON_CURRENCY_MISMATCH],
+    'usage limit reached'   => [['usage_limit' => 1], [], PromotionEngine::REASON_USAGE_LIMIT, fn ($promotion) => redemption($promotion)],
+    'budget exhausted'      => [['budget_amount' => 100], [], PromotionEngine::REASON_BUDGET_EXHAUSTED, fn ($promotion) => redemption($promotion)],
+    'customer limit'        => [['usage_limit_per_customer' => 1], ['customer' => promotionCustomer()], PromotionEngine::REASON_CUSTOMER_USAGE_LIMIT, fn ($promotion) => redemption($promotion, ['customer_uuid' => 'customer_uuid'])],
+    'first order only'      => [['first_order_only' => true], ['customer' => promotionCustomer()], PromotionEngine::REASON_FIRST_ORDER_ONLY, fn () => promotionDb()->table('orders')->insert(['uuid' => 'o1', 'customer_uuid' => 'customer_uuid', 'type' => 'storefront', 'status' => 'completed'])],
+    'minimum subtotal'      => [['min_subtotal' => 50000], [], PromotionCalculator::REASON_MIN_SUBTOTAL],
+    'pickup free delivery'  => [['type' => Promotion::TYPE_FREE_DELIVERY], ['is_pickup' => true, 'delivery_fee' => 0], PromotionCalculator::REASON_PICKUP_ORDER],
+]);
+
+test('customer rules are skipped until the customer is known and honor other customers usage', function () {
+    $promotion = makePromotion(['usage_limit_per_customer' => 1, 'first_order_only' => true]);
+    redemption($promotion, ['customer_uuid' => 'someone_else']);
+    redemption($promotion, ['customer_uuid' => 'customer_uuid', 'status' => 'released']);
+    redemption($promotion, ['customer_uuid' => 'customer_uuid', 'status' => 'reserved', 'created_at' => now()->subHours(3)]);
+    promotionDb()->table('orders')->insert([
+        ['uuid' => 'canceled', 'customer_uuid' => 'customer_uuid', 'type' => 'storefront', 'status' => 'canceled'],
+        ['uuid' => 'fleet', 'customer_uuid' => 'customer_uuid', 'type' => 'default', 'status' => 'completed'],
+    ]);
+
+    expect(promotionEngine()->evaluate(promotionContext())->applied)->toHaveCount(1)
+        ->and(promotionEngine()->evaluate(promotionContext(['customer' => promotionCustomer()]))->applied)->toHaveCount(1);
+});
+
+test('the best non stackable promotion wins over a smaller stack, and a larger stack wins over it', function () {
+    $exclusive = makePromotion(['value' => 30, 'trigger' => Promotion::TRIGGER_CODE]);
+    makePromotionCode($exclusive, 'BIG');
+    makePromotion(['value' => 10, 'stackable' => true, 'priority' => 2]);
+    makePromotion(['type' => Promotion::TYPE_FIXED_AMOUNT, 'value' => 300, 'stackable' => true, 'priority' => 1]);
+
+    $withCode = promotionEngine()->evaluate(promotionContext(), ['BIG']);
+
+    // 30% of store A's 7000 = 2100, versus 10% (700) then 300 off the rest = 1000.
+    expect(array_column($withCode->applied, 'code'))->toBe(['BIG'])
+        ->and($withCode->discountSubtotal())->toBe(2100);
+
+    $withoutCode = promotionEngine()->evaluate(promotionContext());
+
+    expect($withoutCode->applied)->toHaveCount(2)
+        ->and(array_column($withoutCode->applied, 'amount'))->toBe([700, 300])
+        ->and($withoutCode->discountSubtotal())->toBe(1000);
+});
+
+test('a code that loses to a better combination is reported as not combinable', function () {
+    $small = makePromotion(['value' => 5, 'trigger' => Promotion::TRIGGER_CODE]);
+    makePromotionCode($small, 'SMALL');
+    makePromotion(['value' => 40]);
+
+    $result = promotionEngine()->evaluate(promotionContext(), ['SMALL']);
+
+    expect(array_column($result->applied, 'code'))->toBe([null])
+        ->and($result->rejected)->toBe([['code' => 'SMALL', 'reason' => PromotionEngine::REASON_NOT_COMBINABLE]]);
+});
+
+test('stackable promotions that no longer discount anything are skipped', function () {
+    makePromotion(['type' => Promotion::TYPE_FREE_DELIVERY, 'stackable' => true, 'priority' => 2, 'owner_uuid' => 'network_uuid', 'owner_type' => Network::class]);
+    makePromotion(['type' => Promotion::TYPE_FREE_DELIVERY, 'stackable' => true, 'priority' => 1, 'owner_uuid' => 'network_uuid', 'owner_type' => Network::class]);
+
+    $result = promotionEngine()->evaluate(promotionContext(['storefront' => networkStorefront()]));
+
+    expect($result->applied)->toHaveCount(1)
+        ->and($result->discountDelivery())->toBe(500);
+});
+
+test('maximum discounts and remaining budgets cap a promotion', function () {
+    $capped = makePromotion(['value' => 50, 'max_discount_amount' => 1000, 'stackable' => true]);
+    $budget = makePromotion(['owner_uuid' => 'network_uuid', 'owner_type' => Network::class, 'type' => Promotion::TYPE_FREE_DELIVERY, 'budget_amount' => 1000, 'stackable' => true]);
+    redemption($budget, ['amount' => 800]);
+
+    $result  = promotionEngine()->evaluate(promotionContext(['storefront' => networkStorefront()]));
+    $applied = collect($result->applied)->keyBy('promotion_uuid');
+
+    expect($applied[$capped->uuid]['amount'])->toBe(1000)
+        ->and(array_sum($applied[$capped->uuid]['line_amounts']))->toBe(1000)
+        ->and($applied[$budget->uuid]['delivery_amount'])->toBe(200)
+        ->and($applied[$budget->uuid]['amount'])->toBe(0);
+});
+
+test('a capped delivery and item promotion keeps the delivery discount first', function () {
+    makePromotion(['owner_uuid' => 'network_uuid', 'owner_type' => Network::class, 'type' => Promotion::TYPE_FREE_DELIVERY, 'max_discount_amount' => 300]);
+
+    $result = promotionEngine()->evaluate(promotionContext(['storefront' => networkStorefront()]));
+
+    expect($result->discountDelivery())->toBe(300)
+        ->and($result->discountSubtotal())->toBe(0);
+});
+
+test('an empty storefront has no promotions', function () {
+    makePromotion();
+
+    $context             = promotionContext(['lines' => []]);
+    $context->storefront = null;
+
+    expect(promotionEngine()->evaluate($context)->isEmpty())->toBeTrue()
+        ->and(promotionEngine()->evaluate($context)->toArray())->toBe([
+            'discount'          => 0,
+            'discount_subtotal' => 0,
+            'discount_delivery' => 0,
+            'applied'           => [],
+            'rejected'          => [],
+            'allocations'       => [],
+        ]);
+});
+
+test('promotion results round trip through checkout options and hide internals publicly', function () {
+    makePromotion(['name' => 'Tenner', 'value' => 10]);
+    $result   = promotionEngine()->evaluate(promotionContext());
+    $restored = PromotionResult::fromArray(json_decode(json_encode($result->toArray())));
+
+    expect($restored->discount())->toBe(700)
+        ->and($restored->allocationsByStore())->toBe(['store_a' => 700])
+        ->and($restored->toPublicArray())->toBe([
+            'discount'          => 700,
+            'discount_subtotal' => 700,
+            'discount_delivery' => 0,
+            'applied'           => [[
+                'promotion'       => 'promotion_' . substr($result->applied[0]['promotion_uuid'], strlen('promo_uuid_')),
+                'name'            => 'Tenner',
+                'type'            => Promotion::TYPE_PERCENTAGE,
+                'code'            => null,
+                'amount'          => 700,
+                'delivery_amount' => 0,
+            ]],
+            'rejected' => [],
+        ])
+        ->and(PromotionResult::fromArray(null)->isEmpty())->toBeTrue();
+});
+
+test('promotions honor their date range and weekly schedule windows', function () {
+    $promotion = new Promotion();
+    $promotion->forceFill([
+        'status'   => Promotion::STATUS_ACTIVE,
+        'schedule' => [['days' => [1, 2, 3, 4, 5], 'start' => '15:00', 'end' => '18:00'], ['days' => [6], 'start' => '22:00', 'end' => '02:00'], 'junk'],
+        'timezone' => 'UTC',
+    ]);
+
+    // 2026-09-28 is a Monday.
+    expect($promotion->isLiveAt(Carbon::parse('2026-09-28 16:00', 'UTC')))->toBeTrue()
+        ->and($promotion->isLiveAt(Carbon::parse('2026-09-28 18:00', 'UTC')))->toBeFalse()
+        ->and($promotion->isLiveAt(Carbon::parse('2026-09-27 16:00', 'UTC')))->toBeFalse()
+        // Saturday night window runs into Sunday morning.
+        ->and($promotion->isLiveAt(Carbon::parse('2026-10-03 23:30', 'UTC')))->toBeTrue()
+        ->and($promotion->isLiveAt(Carbon::parse('2026-10-04 01:30', 'UTC')))->toBeTrue()
+        ->and($promotion->isLiveAt(Carbon::parse('2026-10-04 03:00', 'UTC')))->toBeFalse();
+
+    $dated = tap(new Promotion())->forceFill(['status' => Promotion::STATUS_ACTIVE, 'starts_at' => '2026-01-01 00:00:00', 'ends_at' => '2026-02-01 00:00:00']);
+
+    expect($dated->isLiveAt(Carbon::parse('2025-12-31 23:59')))->toBeFalse()
+        ->and($dated->isLiveAt(Carbon::parse('2026-01-15')))->toBeTrue()
+        ->and($dated->isLiveAt(Carbon::parse('2026-02-01 00:00')))->toBeFalse()
+        ->and(tap(new Promotion())->forceFill(['status' => Promotion::STATUS_PAUSED])->isLiveAt())->toBeFalse()
+        ->and(tap(new Promotion())->forceFill(['status' => Promotion::STATUS_ACTIVE])->isLiveAt())->toBeTrue();
+});
+
+test('promotion owners are inferred from the owning store or network', function () {
+    seedPromotionStores();
+
+    $store   = tap(new Promotion())->forceFill(['owner_uuid' => 'store_a_uuid']);
+    $network = tap(new Promotion())->forceFill(['owner_uuid' => 'network_uuid']);
+    $typed   = tap(new Promotion())->forceFill(['owner_uuid' => 'store_a_uuid', 'owner_type' => 'storefront:network']);
+    foreach ([$store, $network, $typed] as $promotion) {
+        $promotion->inferOwnerType();
+    }
+
+    expect($store->getAttributes()['owner_type'])->toBe(Store::class)
+        ->and($network->getAttributes()['owner_type'])->toBe(Network::class)
+        ->and($typed->getAttributes()['owner_type'])->toBe(Network::class);
+});
+
+test('promotion codes are normalized, generated without ambiguous characters and parsed from carts', function () {
+    $code = PromotionCode::generate(10, 'vip-');
+    $cart = new Fleetbase\Storefront\Models\Cart();
+    $cart->setPromotionCodes([' save10', 'SAVE10', 'fall ', '']);
+
+    expect(PromotionCode::normalize('  summer25 '))->toBe('SUMMER25')
+        ->and($code)->toStartWith('VIP-')
+        ->and(strlen($code))->toBe(14)
+        ->and(preg_match('/[01IO]/', substr($code, 4)))->toBe(0)
+        ->and($cart->discount_code)->toBe('SAVE10,FALL')
+        ->and($cart->getPromotionCodes())->toBe(['SAVE10', 'FALL'])
+        ->and($cart->setPromotionCodes([])->discount_code)->toBeNull()
+        ->and($cart->getPromotionCodes())->toBe([]);
+});
diff --git a/server/tests/Unit/Providers/StorefrontServiceProviderTest.php b/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
index 3f154d48..1975fa63 100644
--- a/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
+++ b/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
@@ -57,6 +57,11 @@ public function daily(): self
                     return $this;
                 }
 
+                public function everyFifteenMinutes(): self
+                {
+                    return $this;
+                }
+
                 public function storeOutputInDb(): self
                 {
                     return $this;
@@ -104,6 +109,7 @@ protected function mergeConfigFrom($path, $key)
         'schedule',
         'storefront:notify-order-nearby',
         'storefront:purge-carts',
+        'storefront:release-promotion-reservations',
         'observers',
         'middleware',
         'expansions',

From db015df19565d1358505a7877f7a266f3238c7cf Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 18:16:02 +0800
Subject: [PATCH 6/8] feat: add customer segments and campaigns

Customer segments are rule based audiences of a store's or network's
customers (order count bounds, ordered or lapsed within N days, joined
within N days, minimum spend, reachable by push, explicit customers).

Campaigns send a title/body with an optional image and deep link to a
segment (or explicit recipients, or everyone) by push and/or inbox, now
or at a scheduled time. storefront:dispatch-campaigns claims due
campaigns atomically and queues delivery in batches; customers who
turned promotions off are skipped. Promotions can be announced with a
campaign that goes out when the promotion starts, and announcements for
promotions that stopped running are canceled.

The console API manages segments (with live audience previews) and
campaigns (send now, cancel, audience count). The existing promotional
push action now sends a tracked campaign.
---
 ...customer_segments_and_campaigns_tables.php |  69 ++++
 server/src/Auth/Schemas/Storefront.php        |  14 +-
 .../Console/Commands/DispatchCampaigns.php    |  37 +++
 .../src/Http/Controllers/ActionController.php |  61 ++--
 .../Http/Controllers/CampaignController.php   |  84 +++++
 .../Controllers/CustomerSegmentController.php |  80 +++++
 .../Http/Controllers/PromotionController.php  |  58 ++++
 server/src/Http/Filter/CampaignFilter.php     |  28 ++
 .../src/Http/Filter/CustomerSegmentFilter.php |  18 ++
 server/src/Http/Requests/CampaignRequest.php  |  36 +++
 .../Http/Requests/CustomerSegmentRequest.php  |  47 +++
 server/src/Http/Resources/Campaign.php        |  46 +++
 server/src/Http/Resources/CustomerSegment.php |  32 ++
 server/src/Jobs/SendCampaignBatch.php         |  46 +++
 server/src/Models/Campaign.php                |  98 ++++++
 server/src/Models/CustomerSegment.php         |  48 +++
 .../Notifications/CampaignNotification.php    | 125 ++++++++
 .../PromotionalPushNotification.php           |   4 +
 server/src/Promotions/CampaignDispatcher.php  | 102 ++++++
 server/src/Promotions/SegmentResolver.php     |  94 ++++++
 .../Providers/StorefrontServiceProvider.php   |   2 +
 server/src/routes.php                         |  16 +
 server/tests/Support/PromotionTestHelpers.php | 152 +++++++++
 .../SmallControllerContractsTest.php          |  70 ----
 .../Unit/Promotions/CampaignDeliveryTest.php  | 301 ++++++++++++++++++
 .../Unit/Promotions/CampaignEndpointsTest.php | 281 ++++++++++++++++
 .../StorefrontServiceProviderTest.php         |   1 +
 27 files changed, 1853 insertions(+), 97 deletions(-)
 create mode 100644 server/migrations/2026_09_27_100000_create_customer_segments_and_campaigns_tables.php
 create mode 100644 server/src/Console/Commands/DispatchCampaigns.php
 create mode 100644 server/src/Http/Controllers/CampaignController.php
 create mode 100644 server/src/Http/Controllers/CustomerSegmentController.php
 create mode 100644 server/src/Http/Filter/CampaignFilter.php
 create mode 100644 server/src/Http/Filter/CustomerSegmentFilter.php
 create mode 100644 server/src/Http/Requests/CampaignRequest.php
 create mode 100644 server/src/Http/Requests/CustomerSegmentRequest.php
 create mode 100644 server/src/Http/Resources/Campaign.php
 create mode 100644 server/src/Http/Resources/CustomerSegment.php
 create mode 100644 server/src/Jobs/SendCampaignBatch.php
 create mode 100644 server/src/Models/Campaign.php
 create mode 100644 server/src/Models/CustomerSegment.php
 create mode 100644 server/src/Notifications/CampaignNotification.php
 create mode 100644 server/src/Promotions/CampaignDispatcher.php
 create mode 100644 server/src/Promotions/SegmentResolver.php
 create mode 100644 server/tests/Unit/Promotions/CampaignDeliveryTest.php
 create mode 100644 server/tests/Unit/Promotions/CampaignEndpointsTest.php

diff --git a/server/migrations/2026_09_27_100000_create_customer_segments_and_campaigns_tables.php b/server/migrations/2026_09_27_100000_create_customer_segments_and_campaigns_tables.php
new file mode 100644
index 00000000..542a9524
--- /dev/null
+++ b/server/migrations/2026_09_27_100000_create_customer_segments_and_campaigns_tables.php
@@ -0,0 +1,69 @@
+<?php
+
+use Fleetbase\Support\Utils;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Query\Expression;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration {
+    /**
+     * Customer segments (rule based customer audiences) and campaigns (notifications sent to
+     * an audience now or at a scheduled time, optionally announcing a promotion).
+     */
+    public function up(): void
+    {
+        $databaseName = Utils::getFleetbaseDatabaseName();
+        $schema       = Schema::connection(config('storefront.connection.db'));
+
+        $schema->create('customer_segments', function (Blueprint $table) use ($databaseName) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->string('public_id')->unique()->nullable();
+            $table->foreignUuid('company_uuid')->nullable()->index()->references('uuid')->on(new Expression($databaseName . '.companies'))->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->foreignUuid('created_by_uuid')->nullable()->references('uuid')->on(new Expression($databaseName . '.users'))->onUpdate('CASCADE')->onDelete('SET NULL');
+            $table->uuid('owner_uuid')->nullable()->index();
+            $table->string('owner_type')->nullable();
+            $table->string('name');
+            $table->text('description')->nullable();
+            $table->json('rules')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+        });
+
+        $schema->create('campaigns', function (Blueprint $table) use ($databaseName) {
+            $table->bigIncrements('id');
+            $table->uuid('uuid')->unique();
+            $table->string('public_id')->unique()->nullable();
+            $table->foreignUuid('company_uuid')->nullable()->index()->references('uuid')->on(new Expression($databaseName . '.companies'))->onUpdate('CASCADE')->onDelete('CASCADE');
+            $table->foreignUuid('created_by_uuid')->nullable()->references('uuid')->on(new Expression($databaseName . '.users'))->onUpdate('CASCADE')->onDelete('SET NULL');
+            $table->uuid('owner_uuid')->nullable()->index();
+            $table->string('owner_type')->nullable();
+            $table->foreignUuid('segment_uuid')->nullable()->references('uuid')->on('customer_segments')->onUpdate('CASCADE')->onDelete('SET NULL');
+            $table->foreignUuid('promotion_uuid')->nullable()->references('uuid')->on('promotions')->onUpdate('CASCADE')->onDelete('SET NULL');
+            $table->json('recipients')->nullable();
+            $table->string('name');
+            $table->string('status')->default('draft')->index();
+            $table->json('channels')->nullable();
+            $table->string('title');
+            $table->text('body');
+            $table->uuid('image_uuid')->nullable();
+            $table->json('action')->nullable();
+            $table->timestamp('send_at')->nullable()->index();
+            $table->timestamp('started_at')->nullable();
+            $table->timestamp('sent_at')->nullable();
+            $table->json('stats')->nullable();
+            $table->json('meta')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+        });
+    }
+
+    public function down(): void
+    {
+        $schema = Schema::connection(config('storefront.connection.db'));
+        $schema->dropIfExists('campaigns');
+        $schema->dropIfExists('customer_segments');
+    }
+};
diff --git a/server/src/Auth/Schemas/Storefront.php b/server/src/Auth/Schemas/Storefront.php
index a77cf6ff..d732a1df 100644
--- a/server/src/Auth/Schemas/Storefront.php
+++ b/server/src/Auth/Schemas/Storefront.php
@@ -113,12 +113,20 @@ class Storefront
         ],
         [
             'name'    => 'promotion',
-            'actions' => ['generate-codes'],
+            'actions' => ['generate-codes', 'announce'],
         ],
         [
             'name'    => 'promotion-code',
             'actions' => [],
         ],
+        [
+            'name'    => 'customer-segment',
+            'actions' => ['preview'],
+        ],
+        [
+            'name'    => 'campaign',
+            'actions' => ['send', 'cancel'],
+        ],
         [
             'name'           => 'settings',
             'action'         => ['import'],
@@ -164,11 +172,13 @@ class Storefront
         ],
         [
             'name'        => 'PromotionsManager',
-            'description' => 'Policy for managing promotions and promotion codes.',
+            'description' => 'Policy for managing promotions, promotion codes, customer segments and campaigns.',
             'permissions' => [
                 'see extension',
                 '* promotion',
                 '* promotion-code',
+                '* customer-segment',
+                '* campaign',
             ],
         ],
         [
diff --git a/server/src/Console/Commands/DispatchCampaigns.php b/server/src/Console/Commands/DispatchCampaigns.php
new file mode 100644
index 00000000..25092526
--- /dev/null
+++ b/server/src/Console/Commands/DispatchCampaigns.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\Storefront\Console\Commands;
+
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
+use Illuminate\Console\Command;
+
+class DispatchCampaigns extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'storefront:dispatch-campaigns';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Send scheduled storefront campaigns that are due';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     */
+    public function handle(CampaignDispatcher $dispatcher)
+    {
+        $sent = $dispatcher->dispatchDue();
+
+        $this->info('Dispatched ' . $sent . ' campaign(s).');
+
+        return 0;
+    }
+}
diff --git a/server/src/Http/Controllers/ActionController.php b/server/src/Http/Controllers/ActionController.php
index 00920ab7..4ff21e6c 100644
--- a/server/src/Http/Controllers/ActionController.php
+++ b/server/src/Http/Controllers/ActionController.php
@@ -5,10 +5,11 @@
 use Fleetbase\FleetOps\Models\Contact;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\Http\Controllers\Controller;
+use Fleetbase\Storefront\Models\Campaign;
 use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
 use Illuminate\Http\Request;
 use Illuminate\Support\Carbon;
-use Illuminate\Support\Facades\Log;
 
 class ActionController extends Controller
 {
@@ -100,7 +101,11 @@ public function getMetrics(Request $request)
     }
 
     /**
-     * Send promotional push notification to selected customers.
+     * Send a promotional notification to selected customers, or to all of them.
+     *
+     * The message is sent as a campaign (push and inbox), so it is recorded, honors customers'
+     * promotion preferences and is delivered in queued batches. `sent_count` and `total` are
+     * the number of customers targeted.
      *
      * @return \Illuminate\Http\Response
      */
@@ -122,41 +127,47 @@ public function sendPushNotification(Request $request)
         }
 
         // Get the store
-        $store = Store::where('public_id', $storeId)->first();
+        $store = Store::where('public_id', $storeId)->where('company_uuid', session('company'))->first();
         if (!$store) {
             return response()->json(['error' => 'Store not found'], 404);
         }
 
-        // Get customers
-        if ($selectAll) {
-            // Get all customers for this store's company
-            $customers = Contact::where('company_uuid', session('company'))
-                ->where('type', 'customer')
-                ->get();
-        } else {
-            // Get only selected customers
-            $customers = Contact::whereIn('uuid', $customerIds)
+        // Only the company's own customers can be targeted
+        $recipients = null;
+        if (!$selectAll) {
+            $recipients = Contact::whereIn('uuid', (array) $customerIds)
                 ->where('company_uuid', session('company'))
                 ->where('type', 'customer')
-                ->get();
-        }
+                ->pluck('uuid')
+                ->all();
 
-        // Send notifications
-        $sentCount = 0;
-        foreach ($customers as $customer) {
-            try {
-                $customer->notify(new \Fleetbase\Storefront\Notifications\PromotionalPushNotification($title, $body, $store));
-                $sentCount++;
-            } catch (\Exception $e) {
-                // Log error but continue with other customers
-                Log::error('Failed to send push notification to customer: ' . $customer->uuid, ['error' => $e->getMessage()]);
+            if (empty($recipients)) {
+                return response()->json(['status' => 'OK', 'sent_count' => 0, 'total' => 0]);
             }
         }
 
+        $campaign = Campaign::create([
+            'company_uuid'    => $store->company_uuid,
+            'created_by_uuid' => session('user'),
+            'owner_uuid'      => $store->uuid,
+            'owner_type'      => Store::class,
+            'name'            => 'Push notification: ' . $title,
+            'status'          => Campaign::STATUS_SCHEDULED,
+            'channels'        => [Campaign::CHANNEL_PUSH, Campaign::CHANNEL_INBOX],
+            'title'           => $title,
+            'body'            => $body,
+            'recipients'      => $recipients,
+            'send_at'         => now(),
+        ]);
+        app(CampaignDispatcher::class)->dispatch($campaign);
+
+        $targeted = (int) data_get($campaign->refresh()->stats, 'targeted', 0);
+
         return response()->json([
             'status'     => 'OK',
-            'sent_count' => $sentCount,
-            'total'      => count($customers),
+            'sent_count' => $targeted,
+            'total'      => $targeted,
+            'campaign'   => $campaign->public_id,
         ]);
     }
 }
diff --git a/server/src/Http/Controllers/CampaignController.php b/server/src/Http/Controllers/CampaignController.php
new file mode 100644
index 00000000..0bc5de33
--- /dev/null
+++ b/server/src/Http/Controllers/CampaignController.php
@@ -0,0 +1,84 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers;
+
+use Fleetbase\Storefront\Http\Requests\CampaignRequest;
+use Fleetbase\Storefront\Http\Resources\Campaign as CampaignResource;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
+
+class CampaignController extends StorefrontController
+{
+    /**
+     * The resource to query.
+     *
+     * @var string
+     */
+    public $resource = 'campaign';
+
+    /**
+     * Validates creates and updates.
+     *
+     * @var string
+     */
+    public $request = CampaignRequest::class;
+
+    /**
+     * Send a draft or scheduled campaign now.
+     */
+    public function send(string $id, CampaignDispatcher $dispatcher)
+    {
+        $campaign = $this->findCampaign($id);
+        if (!$campaign) {
+            return response()->error('Campaign not found.', 404);
+        }
+
+        if (!in_array($campaign->status, [Campaign::STATUS_DRAFT, Campaign::STATUS_SCHEDULED], true)) {
+            return response()->error('This campaign has already been ' . $campaign->status . '.');
+        }
+
+        $campaign->forceFill(['status' => Campaign::STATUS_SCHEDULED, 'send_at' => now()])->save();
+        $dispatcher->dispatch($campaign);
+
+        return new CampaignResource($campaign->refresh());
+    }
+
+    /**
+     * Cancel a campaign that has not been sent. Batches already queued are skipped.
+     */
+    public function cancel(string $id)
+    {
+        $campaign = $this->findCampaign($id);
+        if (!$campaign) {
+            return response()->error('Campaign not found.', 404);
+        }
+
+        if ($campaign->status === Campaign::STATUS_SENT) {
+            return response()->error('This campaign has already been sent.');
+        }
+
+        $campaign->forceFill(['status' => Campaign::STATUS_CANCELED])->save();
+
+        return new CampaignResource($campaign);
+    }
+
+    /**
+     * Number of customers the campaign would reach right now.
+     */
+    public function audience(string $id, CampaignDispatcher $dispatcher)
+    {
+        $campaign = $this->findCampaign($id);
+        if (!$campaign || !$campaign->resolveOwner()) {
+            return response()->error('Campaign not found.', 404);
+        }
+
+        return response()->json(['count' => $dispatcher->audience($campaign)->count()]);
+    }
+
+    protected function findCampaign(string $id): ?Campaign
+    {
+        return Campaign::where('company_uuid', session('company'))
+            ->where(fn ($query) => $query->where('uuid', $id)->orWhere('public_id', $id))
+            ->first();
+    }
+}
diff --git a/server/src/Http/Controllers/CustomerSegmentController.php b/server/src/Http/Controllers/CustomerSegmentController.php
new file mode 100644
index 00000000..a9d90840
--- /dev/null
+++ b/server/src/Http/Controllers/CustomerSegmentController.php
@@ -0,0 +1,80 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Controllers;
+
+use Fleetbase\Storefront\Http\Requests\CustomerSegmentRequest;
+use Fleetbase\Storefront\Models\CustomerSegment;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Promotions\SegmentResolver;
+use Illuminate\Http\Request;
+
+class CustomerSegmentController extends StorefrontController
+{
+    /**
+     * The resource to query.
+     *
+     * @var string
+     */
+    public $resource = 'customer_segment';
+
+    /**
+     * Validates creates and updates.
+     *
+     * @var string
+     */
+    public $request = CustomerSegmentRequest::class;
+
+    /**
+     * Count and sample the customers matching a saved segment.
+     */
+    public function preview(string $id, SegmentResolver $segments)
+    {
+        $segment = CustomerSegment::where('company_uuid', session('company'))
+            ->where(fn ($query) => $query->where('uuid', $id)->orWhere('public_id', $id))
+            ->first();
+        $owner = $segment ? $this->owner($segment->owner_uuid) : null;
+
+        if (!$owner) {
+            return response()->error('Segment not found.', 404);
+        }
+
+        return response()->json($this->summary($segments, $owner, (array) ($segment->rules ?? [])));
+    }
+
+    /**
+     * Count and sample the customers matching unsaved rules, for the segment builder.
+     *
+     * Body: `owner_uuid` and `rules`.
+     */
+    public function previewRules(Request $request, SegmentResolver $segments)
+    {
+        $owner = $this->owner((string) $request->input('owner_uuid'));
+        if (!$owner) {
+            return response()->error('The owner must be one of your stores or networks.');
+        }
+
+        return response()->json($this->summary($segments, $owner, (array) $request->input('rules', [])));
+    }
+
+    protected function owner(string $uuid): Store|Network|null
+    {
+        return Store::where('uuid', $uuid)->where('company_uuid', session('company'))->first()
+            ?? Network::where('uuid', $uuid)->where('company_uuid', session('company'))->first();
+    }
+
+    protected function summary(SegmentResolver $segments, Store|Network $owner, array $rules): array
+    {
+        $query = $segments->query($owner, array_intersect_key($rules, array_flip(SegmentResolver::RULES)));
+
+        return [
+            'count'  => (clone $query)->count(),
+            'sample' => $query->limit(10)->get(['uuid', 'public_id', 'name', 'email', 'phone'])->map(fn ($customer) => [
+                'id'    => $customer->public_id,
+                'name'  => $customer->name,
+                'email' => $customer->email,
+                'phone' => $customer->phone,
+            ])->all(),
+        ];
+    }
+}
diff --git a/server/src/Http/Controllers/PromotionController.php b/server/src/Http/Controllers/PromotionController.php
index afb5bdc5..02658e02 100644
--- a/server/src/Http/Controllers/PromotionController.php
+++ b/server/src/Http/Controllers/PromotionController.php
@@ -3,10 +3,15 @@
 namespace Fleetbase\Storefront\Http\Controllers;
 
 use Fleetbase\Storefront\Http\Requests\PromotionRequest;
+use Fleetbase\Storefront\Http\Resources\Campaign as CampaignResource;
 use Fleetbase\Storefront\Http\Resources\PromotionCode as PromotionCodeResource;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Models\CustomerSegment;
 use Fleetbase\Storefront\Models\Promotion;
 use Fleetbase\Storefront\Models\PromotionCode;
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
 use Illuminate\Http\Request;
+use Illuminate\Support\Carbon;
 
 class PromotionController extends StorefrontController
 {
@@ -74,6 +79,59 @@ public function generateCodes(string $id, Request $request)
         return response()->json(['codes' => PromotionCodeResource::collection(array_values($codes))]);
     }
 
+    /**
+     * Announce a promotion to customers with a campaign.
+     *
+     * Body (all optional): `title`, `body`, `segment` (segment uuid), `channels`, `send_at`
+     * (defaults to when the promotion starts, or now). Returns the campaign; it is sent right
+     * away when its send time has arrived, otherwise by the campaign scheduler.
+     */
+    public function announce(string $id, Request $request, CampaignDispatcher $dispatcher)
+    {
+        $promotion = Promotion::where('company_uuid', session('company'))
+            ->where(fn ($query) => $query->where('uuid', $id)->orWhere('public_id', $id))
+            ->first();
+
+        if (!$promotion) {
+            return response()->error('Promotion not found.', 404);
+        }
+
+        if (in_array($promotion->status, [Promotion::STATUS_PAUSED, Promotion::STATUS_ENDED], true)) {
+            return response()->error('Only draft or active promotions can be announced.');
+        }
+
+        $segment = $request->filled('segment')
+            ? CustomerSegment::where('company_uuid', session('company'))->where('uuid', $request->input('segment'))->first()
+            : null;
+        if ($request->filled('segment') && !$segment) {
+            return response()->error('Segment not found.', 404);
+        }
+
+        $sendAt   = $request->filled('send_at') ? Carbon::parse($request->input('send_at')) : ($promotion->starts_at && $promotion->starts_at->isFuture() ? $promotion->starts_at : now());
+        $campaign = Campaign::create([
+            'company_uuid'   => $promotion->company_uuid,
+            'created_by_uuid'=> session('user'),
+            'owner_uuid'     => $promotion->owner_uuid,
+            'owner_type'     => $promotion->owner_type,
+            'segment_uuid'   => $segment?->uuid,
+            'promotion_uuid' => $promotion->uuid,
+            'name'           => 'Announce: ' . $promotion->name,
+            'status'         => Campaign::STATUS_SCHEDULED,
+            'channels'       => $request->input('channels', [Campaign::CHANNEL_PUSH, Campaign::CHANNEL_INBOX]),
+            'title'          => $request->input('title', $promotion->name),
+            'body'           => $request->input('body', $promotion->description ?: 'A new deal is available, tap to see it.'),
+            'image_uuid'     => $promotion->image_uuid,
+            'action'         => ['type' => 'promotion', 'id' => $promotion->public_id],
+            'send_at'        => $sendAt,
+        ]);
+
+        if (!$campaign->send_at->isFuture()) {
+            $dispatcher->dispatch($campaign);
+        }
+
+        return new CampaignResource($campaign->refresh());
+    }
+
     protected function generateCode(int $length, string $prefix): string
     {
         return PromotionCode::generate($length, $prefix);
diff --git a/server/src/Http/Filter/CampaignFilter.php b/server/src/Http/Filter/CampaignFilter.php
new file mode 100644
index 00000000..c33e26eb
--- /dev/null
+++ b/server/src/Http/Filter/CampaignFilter.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Filter;
+
+use Fleetbase\Http\Filter\Filter;
+
+class CampaignFilter extends Filter
+{
+    public function queryForInternal()
+    {
+        $this->builder->where('company_uuid', $this->session->get('company'));
+    }
+
+    public function owner(string $owner)
+    {
+        $this->builder->where('owner_uuid', $owner);
+    }
+
+    public function status(string $status)
+    {
+        $this->builder->where('status', $status);
+    }
+
+    public function promotion(string $promotion)
+    {
+        $this->builder->where('promotion_uuid', $promotion);
+    }
+}
diff --git a/server/src/Http/Filter/CustomerSegmentFilter.php b/server/src/Http/Filter/CustomerSegmentFilter.php
new file mode 100644
index 00000000..f1ca6ae6
--- /dev/null
+++ b/server/src/Http/Filter/CustomerSegmentFilter.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Filter;
+
+use Fleetbase\Http\Filter\Filter;
+
+class CustomerSegmentFilter extends Filter
+{
+    public function queryForInternal()
+    {
+        $this->builder->where('company_uuid', $this->session->get('company'));
+    }
+
+    public function owner(string $owner)
+    {
+        $this->builder->where('owner_uuid', $owner);
+    }
+}
diff --git a/server/src/Http/Requests/CampaignRequest.php b/server/src/Http/Requests/CampaignRequest.php
new file mode 100644
index 00000000..c76633f1
--- /dev/null
+++ b/server/src/Http/Requests/CampaignRequest.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Requests;
+
+use Fleetbase\Http\Requests\FleetbaseRequest;
+use Fleetbase\Storefront\Models\Campaign;
+
+class CampaignRequest extends FleetbaseRequest
+{
+    public function authorize()
+    {
+        return request()->session()->has('user');
+    }
+
+    public function rules()
+    {
+        $required = $this->isMethod('post') ? 'required' : 'sometimes';
+
+        return [
+            'name'           => [$required, 'string', 'max:191'],
+            'title'          => [$required, 'string', 'max:191'],
+            'body'           => [$required, 'string', 'max:2000'],
+            'owner_uuid'     => [$required, 'string', CustomerSegmentRequest::ownedStorefrontRule()],
+            'segment_uuid'   => ['nullable', 'string'],
+            'promotion_uuid' => ['nullable', 'string'],
+            'recipients'     => ['nullable', 'array'],
+            'channels'       => ['nullable', 'array'],
+            'channels.*'     => ['in:' . Campaign::CHANNEL_PUSH . ',' . Campaign::CHANNEL_INBOX],
+            'action'         => ['nullable', 'array'],
+            'action.type'    => ['nullable', 'in:promotion,product,store,category,url'],
+            'send_at'        => ['nullable', 'date'],
+            // Sending, sent and canceled are set by the send and cancel actions only.
+            'status'         => ['sometimes', 'in:' . Campaign::STATUS_DRAFT . ',' . Campaign::STATUS_SCHEDULED],
+        ];
+    }
+}
diff --git a/server/src/Http/Requests/CustomerSegmentRequest.php b/server/src/Http/Requests/CustomerSegmentRequest.php
new file mode 100644
index 00000000..4c43f171
--- /dev/null
+++ b/server/src/Http/Requests/CustomerSegmentRequest.php
@@ -0,0 +1,47 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Requests;
+
+use Fleetbase\Http\Requests\FleetbaseRequest;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+
+class CustomerSegmentRequest extends FleetbaseRequest
+{
+    public function authorize()
+    {
+        return request()->session()->has('user');
+    }
+
+    public function rules()
+    {
+        $required = $this->isMethod('post') ? 'required' : 'sometimes';
+
+        return [
+            'name'                          => [$required, 'string', 'max:191'],
+            'owner_uuid'                    => [$required, 'string', static::ownedStorefrontRule()],
+            'rules'                         => ['nullable', 'array'],
+            'rules.customers'               => ['nullable', 'array'],
+            'rules.min_orders'              => ['nullable', 'integer', 'min:0'],
+            'rules.max_orders'              => ['nullable', 'integer', 'min:0'],
+            'rules.ordered_within_days'     => ['nullable', 'integer', 'min:1'],
+            'rules.not_ordered_within_days' => ['nullable', 'integer', 'min:1'],
+            'rules.joined_within_days'      => ['nullable', 'integer', 'min:1'],
+            'rules.min_spent'               => ['nullable', 'integer', 'min:1'],
+            'rules.has_push_device'         => ['nullable', 'boolean'],
+        ];
+    }
+
+    /**
+     * The value must be the uuid of one of the company's stores or networks.
+     */
+    public static function ownedStorefrontRule(): \Closure
+    {
+        return function ($attribute, $value, $fail) {
+            $owned = fn ($model) => $model::where('uuid', $value)->where('company_uuid', session('company'))->exists();
+            if (!$owned(Store::class) && !$owned(Network::class)) {
+                $fail('The owner must be one of your stores or networks.');
+            }
+        };
+    }
+}
diff --git a/server/src/Http/Resources/Campaign.php b/server/src/Http/Resources/Campaign.php
new file mode 100644
index 00000000..16c90635
--- /dev/null
+++ b/server/src/Http/Resources/Campaign.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Resources;
+
+use Fleetbase\Http\Resources\FleetbaseResource;
+
+class Campaign extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        return [
+            'id'             => $this->uuid,
+            'uuid'           => $this->uuid,
+            'public_id'      => $this->public_id,
+            'owner_uuid'     => $this->owner_uuid,
+            'owner_type'     => $this->owner_type,
+            'segment_uuid'   => $this->segment_uuid,
+            'segment_name'   => $this->segment?->name,
+            'promotion_uuid' => $this->promotion_uuid,
+            'promotion_name' => $this->promotion?->name,
+            'recipients'     => $this->recipients ?? [],
+            'name'           => $this->name,
+            'status'         => $this->status,
+            'channels'       => $this->enabledChannels(),
+            'title'          => $this->title,
+            'body'           => $this->body,
+            'image_uuid'     => $this->image_uuid,
+            'image_url'      => $this->image_uuid ? $this->image?->url : null,
+            'action'         => $this->action,
+            'send_at'        => $this->send_at,
+            'started_at'     => $this->started_at,
+            'sent_at'        => $this->sent_at,
+            'stats'          => $this->stats ?? (object) [],
+            'meta'           => $this->meta,
+            'created_at'     => $this->created_at,
+            'updated_at'     => $this->updated_at,
+        ];
+    }
+}
diff --git a/server/src/Http/Resources/CustomerSegment.php b/server/src/Http/Resources/CustomerSegment.php
new file mode 100644
index 00000000..a948e8a0
--- /dev/null
+++ b/server/src/Http/Resources/CustomerSegment.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace Fleetbase\Storefront\Http\Resources;
+
+use Fleetbase\Http\Resources\FleetbaseResource;
+
+class CustomerSegment extends FleetbaseResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param \Illuminate\Http\Request $request
+     *
+     * @return array
+     */
+    public function toArray($request)
+    {
+        return [
+            'id'          => $this->uuid,
+            'uuid'        => $this->uuid,
+            'public_id'   => $this->public_id,
+            'owner_uuid'  => $this->owner_uuid,
+            'owner_type'  => $this->owner_type,
+            'name'        => $this->name,
+            'description' => $this->description,
+            'rules'       => $this->rules ?? (object) [],
+            'meta'        => $this->meta,
+            'created_at'  => $this->created_at,
+            'updated_at'  => $this->updated_at,
+        ];
+    }
+}
diff --git a/server/src/Jobs/SendCampaignBatch.php b/server/src/Jobs/SendCampaignBatch.php
new file mode 100644
index 00000000..24f277b6
--- /dev/null
+++ b/server/src/Jobs/SendCampaignBatch.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace Fleetbase\Storefront\Jobs;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Notifications\CampaignNotification;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Sends a campaign to one batch of customers.
+ */
+class SendCampaignBatch implements ShouldQueue
+{
+    use InteractsWithQueue;
+    use Queueable;
+
+    public int $tries = 1;
+
+    /**
+     * @param string[] $customerUuids
+     */
+    public function __construct(public string $campaignUuid, public array $customerUuids)
+    {
+    }
+
+    public function handle(): void
+    {
+        $campaign = Campaign::where('uuid', $this->campaignUuid)->first();
+        if (!$campaign || $campaign->status === Campaign::STATUS_CANCELED) {
+            return;
+        }
+
+        $notification = new CampaignNotification($campaign);
+        foreach (Contact::whereIn('uuid', $this->customerUuids)->get() as $customer) {
+            try {
+                $customer->notify($notification);
+            } catch (\Throwable $e) {
+                Log::warning('[Storefront] Unable to send campaign to customer.', ['campaign' => $campaign->public_id, 'customer' => $customer->public_id, 'error' => $e->getMessage()]);
+            }
+        }
+    }
+}
diff --git a/server/src/Models/Campaign.php b/server/src/Models/Campaign.php
new file mode 100644
index 00000000..791cf096
--- /dev/null
+++ b/server/src/Models/Campaign.php
@@ -0,0 +1,98 @@
+<?php
+
+namespace Fleetbase\Storefront\Models;
+
+use Fleetbase\Casts\Json;
+use Fleetbase\Casts\PolymorphicType;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Models\File;
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasPublicId;
+use Fleetbase\Traits\HasUuid;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * A notification sent to a store's or network's customers, now or at a scheduled time.
+ */
+class Campaign extends StorefrontModel
+{
+    use HasUuid;
+    use HasPublicId;
+    use HasApiModelBehavior;
+    use SoftDeletes;
+
+    public const STATUS_DRAFT     = 'draft';
+    public const STATUS_SCHEDULED = 'scheduled';
+    public const STATUS_SENDING   = 'sending';
+    public const STATUS_SENT      = 'sent';
+    public const STATUS_CANCELED  = 'canceled';
+
+    public const CHANNEL_PUSH  = 'push';
+    public const CHANNEL_INBOX = 'inbox';
+
+    protected $publicIdType = 'campaign';
+
+    protected $table = 'campaigns';
+
+    protected $searchableColumns = ['name', 'title', 'body'];
+
+    protected $fillable = [
+        'company_uuid', 'created_by_uuid', 'owner_uuid', 'owner_type', 'segment_uuid', 'promotion_uuid', 'recipients', 'name', 'status',
+        'channels', 'title', 'body', 'image_uuid', 'action', 'send_at', 'started_at', 'sent_at', 'stats', 'meta',
+    ];
+
+    protected $casts = [
+        'owner_type' => PolymorphicType::class,
+        'recipients' => Json::class,
+        'channels'   => Json::class,
+        'action'     => Json::class,
+        'stats'      => Json::class,
+        'meta'       => Json::class,
+        'send_at'    => 'datetime',
+        'started_at' => 'datetime',
+        'sent_at'    => 'datetime',
+    ];
+
+    public function owner()
+    {
+        return $this->morphTo(__FUNCTION__, 'owner_type', 'owner_uuid');
+    }
+
+    public function segment()
+    {
+        return $this->belongsTo(CustomerSegment::class, 'segment_uuid', 'uuid');
+    }
+
+    public function promotion()
+    {
+        return $this->belongsTo(Promotion::class, 'promotion_uuid', 'uuid');
+    }
+
+    public function image()
+    {
+        return $this->setConnection(config('fleetbase.connection.db'))->belongsTo(File::class, 'image_uuid', 'uuid');
+    }
+
+    public function setOwnerTypeAttribute($type)
+    {
+        $this->attributes['owner_type'] = Utils::getMutationType($type);
+    }
+
+    /**
+     * The store or network the campaign is sent for.
+     */
+    public function resolveOwner(): Store|Network|null
+    {
+        return Store::where('uuid', $this->owner_uuid)->first() ?? Network::where('uuid', $this->owner_uuid)->first();
+    }
+
+    /**
+     * @return string[] enabled channels, defaulting to push and inbox
+     */
+    public function enabledChannels(): array
+    {
+        $channels = array_values(array_intersect((array) ($this->channels ?? []), [self::CHANNEL_PUSH, self::CHANNEL_INBOX]));
+
+        return $channels ?: [self::CHANNEL_PUSH, self::CHANNEL_INBOX];
+    }
+}
diff --git a/server/src/Models/CustomerSegment.php b/server/src/Models/CustomerSegment.php
new file mode 100644
index 00000000..ecfb3110
--- /dev/null
+++ b/server/src/Models/CustomerSegment.php
@@ -0,0 +1,48 @@
+<?php
+
+namespace Fleetbase\Storefront\Models;
+
+use Fleetbase\Casts\Json;
+use Fleetbase\Casts\PolymorphicType;
+use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\Traits\HasApiModelBehavior;
+use Fleetbase\Traits\HasPublicId;
+use Fleetbase\Traits\HasUuid;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * A rule based audience of a store's or network's customers.
+ *
+ * See Promotions\SegmentResolver for the supported rules.
+ */
+class CustomerSegment extends StorefrontModel
+{
+    use HasUuid;
+    use HasPublicId;
+    use HasApiModelBehavior;
+    use SoftDeletes;
+
+    protected $publicIdType = 'segment';
+
+    protected $table = 'customer_segments';
+
+    protected $searchableColumns = ['name', 'description'];
+
+    protected $fillable = ['company_uuid', 'created_by_uuid', 'owner_uuid', 'owner_type', 'name', 'description', 'rules', 'meta'];
+
+    protected $casts = [
+        'owner_type' => PolymorphicType::class,
+        'rules'      => Json::class,
+        'meta'       => Json::class,
+    ];
+
+    public function owner()
+    {
+        return $this->morphTo(__FUNCTION__, 'owner_type', 'owner_uuid');
+    }
+
+    public function setOwnerTypeAttribute($type)
+    {
+        $this->attributes['owner_type'] = Utils::getMutationType($type);
+    }
+}
diff --git a/server/src/Notifications/CampaignNotification.php b/server/src/Notifications/CampaignNotification.php
new file mode 100644
index 00000000..74aa0db4
--- /dev/null
+++ b/server/src/Notifications/CampaignNotification.php
@@ -0,0 +1,125 @@
+<?php
+
+namespace Fleetbase\Storefront\Notifications;
+
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel;
+use Fleetbase\Storefront\Push\Contracts\SendsPushNotification;
+use Fleetbase\Storefront\Push\PushMessage;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Fleetbase\Storefront\Support\CustomerNotificationPresenter;
+use Fleetbase\Storefront\Support\NotificationPreferences;
+use Illuminate\Bus\Queueable;
+use Illuminate\Notifications\Messages\BroadcastMessage;
+use Illuminate\Notifications\Notification;
+
+/**
+ * A campaign message delivered to one customer by push and/or to their inbox.
+ */
+class CampaignNotification extends Notification implements SendsPushNotification
+{
+    use Queueable;
+
+    public function __construct(public Campaign $campaign, public Store|Network|null $owner = null)
+    {
+        $this->owner ??= $campaign->resolveOwner();
+    }
+
+    /**
+     * Campaigns are marketing: customers who turned promotions off receive nothing.
+     */
+    public function via($notifiable): array
+    {
+        if (!NotificationPreferences::allows($notifiable, 'promotions')) {
+            return [];
+        }
+
+        $channels = $this->campaign->enabledChannels();
+        $via      = [];
+        if (in_array(Campaign::CHANNEL_PUSH, $channels, true)) {
+            $via[] = StorefrontPushChannel::class;
+        }
+        if (in_array(Campaign::CHANNEL_INBOX, $channels, true)) {
+            $via[] = 'database';
+            $via[] = SafeBroadcastChannel::class;
+        }
+
+        return $via;
+    }
+
+    public function toPush($notifiable): ?PushMessage
+    {
+        return PushMessage::create($this->campaign->title, $this->campaign->body, $this->payload())
+            ->image($this->imageUrl())
+            ->analyticsLabel('campaign');
+    }
+
+    /**
+     * The owner's app first, then (for a store) the apps of the networks it belongs to.
+     */
+    public function pushStorefronts(): array
+    {
+        $storefronts = array_filter([$this->owner]);
+
+        if ($this->owner instanceof Store) {
+            try {
+                foreach ($this->owner->networks as $network) {
+                    $storefronts[] = $network;
+                }
+            } catch (\Throwable $e) {
+                // Network membership is optional for delivery.
+            }
+        }
+
+        return array_values($storefronts);
+    }
+
+    public function toArray($notifiable): array
+    {
+        return [
+            'title'   => $this->campaign->title,
+            'body'    => $this->campaign->body,
+            'subject' => $this->campaign->title,
+            'message' => $this->campaign->body,
+            'image'   => $this->imageUrl(),
+            ...$this->payload(),
+        ];
+    }
+
+    public function toBroadcast($notifiable): BroadcastMessage
+    {
+        return new BroadcastMessage(CustomerNotificationPresenter::present($this->toArray($notifiable), static::class));
+    }
+
+    public function broadcastType(): string
+    {
+        return 'campaign';
+    }
+
+    /**
+     * Deep-link data shared by the push payload and the inbox copy.
+     */
+    protected function payload(): array
+    {
+        $owner  = $this->owner;
+        $action = (array) ($this->campaign->action ?? []);
+
+        return array_filter([
+            'type'        => 'campaign',
+            'campaign_id' => $this->campaign->public_id,
+            'promotion_id'=> $this->campaign->promotion?->public_id,
+            'store_id'    => $owner instanceof Store ? $owner->public_id : null,
+            'network_id'  => $owner instanceof Network ? $owner->public_id : null,
+            'action'      => $action['type'] ?? null,
+            'action_id'   => $action['id'] ?? null,
+            'action_url'  => $action['url'] ?? null,
+        ], fn ($value) => $value !== null);
+    }
+
+    protected function imageUrl(): ?string
+    {
+        return $this->campaign->image_uuid ? $this->campaign->image?->url : null;
+    }
+}
diff --git a/server/src/Notifications/PromotionalPushNotification.php b/server/src/Notifications/PromotionalPushNotification.php
index 0bd5be64..53b2e544 100644
--- a/server/src/Notifications/PromotionalPushNotification.php
+++ b/server/src/Notifications/PromotionalPushNotification.php
@@ -13,6 +13,10 @@
 use Illuminate\Notifications\Messages\BroadcastMessage;
 use Illuminate\Notifications\Notification;
 
+/**
+ * @deprecated Promotional messages are sent as campaigns (CampaignNotification). Kept for
+ *             integrations that notify customers with this class directly.
+ */
 class PromotionalPushNotification extends Notification implements SendsPushNotification
 {
     use Queueable;
diff --git a/server/src/Promotions/CampaignDispatcher.php b/server/src/Promotions/CampaignDispatcher.php
new file mode 100644
index 00000000..e37a9334
--- /dev/null
+++ b/server/src/Promotions/CampaignDispatcher.php
@@ -0,0 +1,102 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\Storefront\Jobs\SendCampaignBatch;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Models\Promotion;
+use Illuminate\Contracts\Bus\Dispatcher as BusDispatcher;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Carbon;
+
+/**
+ * Resolves a campaign's audience and queues it for delivery in batches.
+ */
+class CampaignDispatcher
+{
+    public const BATCH_SIZE = 250;
+
+    public function __construct(protected SegmentResolver $segments)
+    {
+    }
+
+    /**
+     * Send every scheduled campaign that is due.
+     */
+    public function dispatchDue(?Carbon $now = null): int
+    {
+        $now = $now ?? Carbon::now();
+        $due = Campaign::where('status', Campaign::STATUS_SCHEDULED)->where('send_at', '<=', $now)->get();
+
+        return $due->filter(fn (Campaign $campaign) => $this->dispatch($campaign))->count();
+    }
+
+    /**
+     * Send a campaign now. Returns false if it was not scheduled (e.g. already sending) or
+     * cannot be sent; the campaign status records why.
+     */
+    public function dispatch(Campaign $campaign): bool
+    {
+        // Claim the campaign so concurrent schedulers never send it twice.
+        $claimed = Campaign::where('uuid', $campaign->uuid)
+            ->where('status', Campaign::STATUS_SCHEDULED)
+            ->update(['status' => Campaign::STATUS_SENDING, 'started_at' => now()]);
+        if (!$claimed) {
+            return false;
+        }
+        $campaign->refresh();
+
+        $owner = $campaign->resolveOwner();
+        if (!$owner) {
+            return $this->finish($campaign, Campaign::STATUS_CANCELED, ['reason' => 'owner_missing']);
+        }
+
+        // An announcement for a promotion that is no longer running is not sent.
+        $promotion = $campaign->promotion;
+        if ($campaign->promotion_uuid && (!$promotion || in_array($promotion->status, [Promotion::STATUS_PAUSED, Promotion::STATUS_ENDED], true) || ($promotion->ends_at && $promotion->ends_at->isPast()))) {
+            return $this->finish($campaign, Campaign::STATUS_CANCELED, ['reason' => 'promotion_unavailable']);
+        }
+
+        $targeted = 0;
+        $batches  = 0;
+        $this->audience($campaign, $owner)->select('uuid')->chunkById(static::BATCH_SIZE, function ($customers) use ($campaign, &$targeted, &$batches) {
+            $uuids = $customers->pluck('uuid')->all();
+            $targeted += count($uuids);
+            $batches++;
+            app(BusDispatcher::class)->dispatch(new SendCampaignBatch($campaign->uuid, $uuids));
+        }, 'uuid');
+
+        return $this->finish($campaign, Campaign::STATUS_SENT, ['targeted' => $targeted, 'batches' => $batches]);
+    }
+
+    /**
+     * Customers the campaign is sent to: its segment's rules, narrowed to explicit recipients.
+     */
+    public function audience(Campaign $campaign, $owner = null): Builder
+    {
+        $owner ??= $campaign->resolveOwner();
+        $rules = (array) ($campaign->segment?->rules ?? []);
+
+        // An explicit recipient list (even an empty one) restricts the audience; null does not.
+        if ($campaign->recipients !== null) {
+            $recipients         = (array) $campaign->recipients;
+            $rules['customers'] = !empty($rules['customers']) ? array_values(array_intersect((array) $rules['customers'], $recipients)) : $recipients;
+            if (empty($rules['customers'])) {
+                $rules['customers'] = ['__none__'];
+            }
+        }
+
+        return $this->segments->query($owner, $rules);
+    }
+
+    protected function finish(Campaign $campaign, string $status, array $stats): bool
+    {
+        $campaign->forceFill([
+            'status'  => $status,
+            'sent_at' => $status === Campaign::STATUS_SENT ? now() : null,
+            'stats'   => array_merge((array) ($campaign->stats ?? []), $stats),
+        ])->save();
+
+        return $status === Campaign::STATUS_SENT;
+    }
+}
diff --git a/server/src/Promotions/SegmentResolver.php b/server/src/Promotions/SegmentResolver.php
new file mode 100644
index 00000000..5cc596d8
--- /dev/null
+++ b/server/src/Promotions/SegmentResolver.php
@@ -0,0 +1,94 @@
+<?php
+
+namespace Fleetbase\Storefront\Promotions;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Models\Transaction;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Store;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Carbon;
+
+/**
+ * Builds the customer query for a segment's rules.
+ *
+ * All rules are optional and combined with AND. Order rules count the customer's storefront
+ * orders placed with the owning store or network (canceled orders excluded):
+ *
+ * - `customers`: only these customer (contact) uuids
+ * - `min_orders` / `max_orders`: order count bounds (`max_orders: 0` targets customers who never ordered)
+ * - `ordered_within_days`: ordered at least once in the last N days
+ * - `not_ordered_within_days`: ordered before, but not in the last N days (lapsed customers)
+ * - `joined_within_days`: customer created in the last N days
+ * - `min_spent`: total successful storefront payments across the company, in minor units
+ * - `has_push_device`: `true` for customers with a registered push device
+ */
+class SegmentResolver
+{
+    public const RULES = ['customers', 'min_orders', 'max_orders', 'ordered_within_days', 'not_ordered_within_days', 'joined_within_days', 'min_spent', 'has_push_device'];
+
+    public function query(Store|Network $owner, array $rules = [], ?Carbon $now = null): Builder
+    {
+        $now    = $now ?? Carbon::now();
+        $orders = function ($query) use ($owner) {
+            $query->where('type', 'storefront')
+                ->where('status', '!=', 'canceled')
+                ->where(function ($query) use ($owner) {
+                    $query->where('meta->storefront_id', $owner->public_id)
+                        ->orWhere('meta->storefront_network_id', $owner->public_id);
+                });
+        };
+
+        $query = Contact::query()
+            ->where('company_uuid', $owner->company_uuid)
+            ->where('type', 'customer');
+
+        if (!empty($rules['customers'])) {
+            $query->whereIn('uuid', (array) $rules['customers']);
+        }
+
+        if (isset($rules['min_orders']) && $rules['min_orders'] !== null) {
+            $query->whereHas('customerOrders', $orders, '>=', (int) $rules['min_orders']);
+        }
+
+        if (isset($rules['max_orders']) && $rules['max_orders'] !== null) {
+            $query->has('customerOrders', '<=', (int) $rules['max_orders'], 'and', $orders);
+        }
+
+        if (!empty($rules['ordered_within_days'])) {
+            $since = $now->copy()->subDays((int) $rules['ordered_within_days']);
+            $query->whereHas('customerOrders', function ($query) use ($orders, $since) {
+                $orders($query);
+                $query->where('created_at', '>=', $since);
+            });
+        }
+
+        if (!empty($rules['not_ordered_within_days'])) {
+            $since = $now->copy()->subDays((int) $rules['not_ordered_within_days']);
+            $query->whereHas('customerOrders', $orders)
+                ->whereDoesntHave('customerOrders', function ($query) use ($orders, $since) {
+                    $orders($query);
+                    $query->where('created_at', '>=', $since);
+                });
+        }
+
+        if (!empty($rules['joined_within_days'])) {
+            $query->where('created_at', '>=', $now->copy()->subDays((int) $rules['joined_within_days']));
+        }
+
+        if (!empty($rules['min_spent'])) {
+            $transactions = (new Transaction())->getTable();
+            $contacts     = $query->getModel()->getTable();
+            $query->whereRaw(
+                '(select coalesce(sum(' . $transactions . '.amount), 0) from ' . $transactions . ' where ' . $transactions . '.customer_uuid = ' . $contacts . '.uuid and ' . $transactions . ".type = 'storefront' and " . $transactions . ".status = 'success' and " . $transactions . '.deleted_at is null) >= ?',
+                [(int) $rules['min_spent']]
+            );
+        }
+
+        if (!empty($rules['has_push_device'])) {
+            $query->whereHas('devices', fn ($query) => $query->where(fn ($query) => $query->whereNotIn('status', ['invalid', 'inactive'])->orWhereNull('status')));
+        }
+
+        return $query;
+    }
+}
diff --git a/server/src/Providers/StorefrontServiceProvider.php b/server/src/Providers/StorefrontServiceProvider.php
index 9b49c044..8fd668d9 100644
--- a/server/src/Providers/StorefrontServiceProvider.php
+++ b/server/src/Providers/StorefrontServiceProvider.php
@@ -64,6 +64,7 @@ class StorefrontServiceProvider extends CoreServiceProvider
         \Fleetbase\Storefront\Console\Commands\PurgeExpiredCarts::class,
         \Fleetbase\Storefront\Console\Commands\MigrateStripeSandboxCustomers::class,
         \Fleetbase\Storefront\Console\Commands\ReleasePromotionReservations::class,
+        \Fleetbase\Storefront\Console\Commands\DispatchCampaigns::class,
     ];
 
     /**
@@ -100,6 +101,7 @@ public function boot()
             $schedule->command('storefront:notify-order-nearby')->everyMinute()->storeOutputInDb();
             $schedule->command('storefront:purge-carts')->daily()->storeOutputInDb();
             $schedule->command('storefront:release-promotion-reservations')->everyFifteenMinutes()->storeOutputInDb();
+            $schedule->command('storefront:dispatch-campaigns')->everyMinute()->storeOutputInDb();
         });
         $this->registerObservers();
         $this->registerMiddleware();
diff --git a/server/src/routes.php b/server/src/routes.php
index a57c9c56..47577782 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -245,9 +245,25 @@ function ($router, $controller) {
                             'promotions',
                             function ($router, $controller) {
                                 $router->post('{id}/generate-codes', $controller('generateCodes'));
+                                $router->post('{id}/announce', $controller('announce'));
                             }
                         );
                         $router->fleetbaseRoutes('promotion-codes');
+                        $router->fleetbaseRoutes(
+                            'customer-segments',
+                            function ($router, $controller) {
+                                $router->post('preview', $controller('previewRules'));
+                                $router->get('{id}/preview', $controller('preview'));
+                            }
+                        );
+                        $router->fleetbaseRoutes(
+                            'campaigns',
+                            function ($router, $controller) {
+                                $router->post('{id}/send', $controller('send'));
+                                $router->post('{id}/cancel', $controller('cancel'));
+                                $router->get('{id}/audience', $controller('audience'));
+                            }
+                        );
                         $router->fleetbaseRoutes('reviews');
                         $router->fleetbaseRoutes('votes');
                         $router->fleetbaseRoutes('food-trucks');
diff --git a/server/tests/Support/PromotionTestHelpers.php b/server/tests/Support/PromotionTestHelpers.php
index cfb91eed..3895fcd9 100644
--- a/server/tests/Support/PromotionTestHelpers.php
+++ b/server/tests/Support/PromotionTestHelpers.php
@@ -209,4 +209,156 @@ function promotionContext(array $overrides = []): PromotionContext
             $overrides['now'] ?? null,
         );
     }
+
+    /**
+     * Tables for segments and campaigns, on top of createPromotionSchema().
+     */
+    function createCampaignSchema(): void
+    {
+        $schema = promotionDb()->getSchemaBuilder();
+        foreach (['customer_segments', 'campaigns', 'contacts', 'user_devices', 'transactions', 'notifications'] as $table) {
+            $schema->dropIfExists($table);
+        }
+
+        $schema->create('customer_segments', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('created_by_uuid')->nullable();
+            $table->string('owner_uuid')->nullable();
+            $table->string('owner_type')->nullable();
+            $table->string('name')->nullable();
+            $table->text('description')->nullable();
+            $table->text('rules')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('campaigns', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('created_by_uuid')->nullable();
+            $table->string('owner_uuid')->nullable();
+            $table->string('owner_type')->nullable();
+            $table->string('segment_uuid')->nullable();
+            $table->string('promotion_uuid')->nullable();
+            $table->text('recipients')->nullable();
+            $table->string('name')->nullable();
+            $table->string('status')->default('draft');
+            $table->text('channels')->nullable();
+            $table->string('title')->nullable();
+            $table->text('body')->nullable();
+            $table->string('image_uuid')->nullable();
+            $table->text('action')->nullable();
+            $table->timestamp('send_at')->nullable();
+            $table->timestamp('started_at')->nullable();
+            $table->timestamp('sent_at')->nullable();
+            $table->text('stats')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('contacts', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('company_uuid')->nullable();
+            $table->string('user_uuid')->nullable();
+            $table->string('type')->nullable();
+            $table->string('name')->nullable();
+            $table->string('email')->nullable();
+            $table->string('phone')->nullable();
+            $table->text('meta')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('user_devices', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('public_id')->nullable();
+            $table->string('user_uuid')->nullable();
+            $table->string('platform')->nullable();
+            $table->text('token')->nullable();
+            $table->string('status')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('transactions', function ($table) {
+            $table->increments('id');
+            $table->string('uuid')->nullable();
+            $table->string('customer_uuid')->nullable();
+            $table->string('type')->nullable();
+            $table->string('status')->nullable();
+            $table->integer('amount')->nullable();
+            $table->timestamps();
+            $table->timestamp('deleted_at')->nullable();
+        });
+        $schema->create('notifications', function ($table) {
+            $table->string('id')->primary();
+            $table->string('type');
+            $table->string('notifiable_type');
+            $table->string('notifiable_id');
+            $table->text('data');
+            $table->timestamp('read_at')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Bind a bus dispatcher that records queued jobs and, optionally, runs them.
+     */
+    function fakeCampaignBus(bool $run = false): object
+    {
+        $bus = new class($run) implements Illuminate\Contracts\Bus\Dispatcher {
+            public array $jobs = [];
+
+            public function __construct(public bool $run)
+            {
+            }
+
+            public function dispatch($command)
+            {
+                $this->jobs[] = $command;
+                if ($this->run) {
+                    $command->handle();
+                }
+            }
+
+            public function dispatchSync($command, $handler = null)
+            {
+                return $this->dispatch($command);
+            }
+
+            public function dispatchNow($command, $handler = null)
+            {
+                return $this->dispatch($command);
+            }
+
+            public function hasCommandHandler($command)
+            {
+                return false;
+            }
+
+            public function getCommandHandler($command)
+            {
+                return false;
+            }
+
+            public function pipeThrough(array $pipes)
+            {
+                return $this;
+            }
+
+            public function map(array $map)
+            {
+                return $this;
+            }
+        };
+        app()->instance(Illuminate\Contracts\Bus\Dispatcher::class, $bus);
+
+        return $bus;
+    }
 }
diff --git a/server/tests/Unit/Http/Controllers/SmallControllerContractsTest.php b/server/tests/Unit/Http/Controllers/SmallControllerContractsTest.php
index 3bdbd16d..97a0fa91 100644
--- a/server/tests/Unit/Http/Controllers/SmallControllerContractsTest.php
+++ b/server/tests/Unit/Http/Controllers/SmallControllerContractsTest.php
@@ -231,76 +231,6 @@ public function __construct(public Company $company)
     ]);
 });
 
-test('action controller sends selected and all-customer promotions while isolating delivery failures', function () {
-    $connection = Model::getConnectionResolver()->connection('mysql');
-    $schema     = $connection->getSchemaBuilder();
-    $schema->dropIfExists('contacts');
-    $schema->dropIfExists('stores');
-    $schema->create('stores', function ($table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('public_id')->nullable();
-        $table->string('company_uuid')->nullable();
-        $table->string('name')->nullable();
-        $table->timestamp('deleted_at')->nullable();
-    });
-    $schema->create('contacts', function ($table) {
-        $table->increments('id');
-        $table->string('uuid')->nullable();
-        $table->string('company_uuid')->nullable();
-        $table->string('type')->nullable();
-        $table->timestamp('deleted_at')->nullable();
-    });
-    $connection->table('stores')->insert([
-        'uuid'         => 'store_uuid',
-        'public_id'    => 'store_public',
-        'company_uuid' => 'company_uuid',
-        'name'         => 'Test Store',
-    ]);
-    $connection->table('contacts')->insert([
-        ['uuid' => 'customer_selected', 'company_uuid' => 'company_uuid', 'type' => 'customer'],
-        ['uuid' => 'other_company_customer', 'company_uuid' => 'other_company', 'type' => 'customer'],
-    ]);
-    session(['company' => 'company_uuid']);
-    $controller = new ActionController();
-    $selected   = $controller->sendPushNotification(Request::create('/notifications', 'POST', [
-        'title'     => 'New menu',
-        'body'      => 'Try our latest items.',
-        'customers' => ['customer_selected'],
-        'store'     => 'store_public',
-    ]));
-
-    app()->instance(
-        Illuminate\Contracts\Notifications\Dispatcher::class,
-        new class implements Illuminate\Contracts\Notifications\Dispatcher {
-            public function send($notifiables, $notification)
-            {
-            }
-
-            public function sendNow($notifiables, $notification, ?array $channels = null)
-            {
-            }
-        }
-    );
-    $all = $controller->sendPushNotification(Request::create('/notifications', 'POST', [
-        'title'      => 'New menu',
-        'body'       => 'Try our latest items.',
-        'select_all' => true,
-        'store'      => 'store_public',
-    ]));
-    app()->offsetUnset(Illuminate\Contracts\Notifications\Dispatcher::class);
-
-    expect($selected->getData(true))->toBe([
-        'status'     => 'OK',
-        'sent_count' => 0,
-        'total'      => 1,
-    ])->and($all->getData(true))->toBe([
-        'status'     => 'OK',
-        'sent_count' => 1,
-        'total'      => 1,
-    ]);
-});
-
 test('public catalog and food truck queries are empty without a storefront store context', function () {
     session(['storefront_store' => null]);
 
diff --git a/server/tests/Unit/Promotions/CampaignDeliveryTest.php b/server/tests/Unit/Promotions/CampaignDeliveryTest.php
new file mode 100644
index 00000000..d1154aa4
--- /dev/null
+++ b/server/tests/Unit/Promotions/CampaignDeliveryTest.php
@@ -0,0 +1,301 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\Storefront\Console\Commands\DispatchCampaigns;
+use Fleetbase\Storefront\Jobs\SendCampaignBatch;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Models\CustomerSegment;
+use Fleetbase\Storefront\Models\Network;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Notifications\CampaignNotification;
+use Fleetbase\Storefront\Notifications\Channels\SafeBroadcastChannel;
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
+use Fleetbase\Storefront\Promotions\SegmentResolver;
+use Fleetbase\Storefront\Push\StorefrontPushChannel;
+use Illuminate\Support\Carbon;
+
+function campaignStore(): Store
+{
+    return Store::where('uuid', 'store_a_uuid')->first();
+}
+
+function makeCampaign(array $attributes = []): Campaign
+{
+    static $sequence = 0;
+    $sequence++;
+
+    $campaign = new Campaign();
+    $campaign->forceFill(array_merge([
+        'uuid'         => 'campaign_uuid_' . $sequence,
+        'public_id'    => 'campaign_' . $sequence,
+        'company_uuid' => 'company_uuid',
+        'owner_uuid'   => 'store_a_uuid',
+        'owner_type'   => Store::class,
+        'name'         => 'Campaign ' . $sequence,
+        'status'       => Campaign::STATUS_SCHEDULED,
+        'title'        => 'Fresh deals',
+        'body'         => 'Come see what is new.',
+        'send_at'      => now()->subMinute(),
+    ], $attributes));
+    $campaign->save();
+
+    return $campaign;
+}
+
+function segmentUuids(array $rules, $owner = null, ?Carbon $now = null): array
+{
+    return (new SegmentResolver())->query($owner ?? campaignStore(), $rules, $now)->orderBy('uuid')->pluck('uuid')->all();
+}
+
+function fakeNotificationDispatcher(?callable $onSend = null): object
+{
+    $dispatcher = new class($onSend) implements Illuminate\Contracts\Notifications\Dispatcher {
+        public array $sent = [];
+
+        public function __construct(public $onSend)
+        {
+        }
+
+        public function send($notifiables, $notification)
+        {
+            foreach (collect($notifiables instanceof Illuminate\Support\Collection ? $notifiables : [$notifiables]) as $notifiable) {
+                if ($this->onSend) {
+                    ($this->onSend)($notifiable);
+                }
+                $this->sent[] = [$notifiable->uuid, $notification];
+            }
+        }
+
+        public function sendNow($notifiables, $notification, ?array $channels = null)
+        {
+            $this->send($notifiables, $notification);
+        }
+    };
+    app()->instance(Illuminate\Contracts\Notifications\Dispatcher::class, $dispatcher);
+    Illuminate\Support\Facades\Notification::clearResolvedInstance(Illuminate\Contracts\Notifications\Dispatcher::class);
+
+    return $dispatcher;
+}
+
+beforeEach(function () {
+    createPromotionSchema();
+    createCampaignSchema();
+    seedPromotionStores();
+
+    $days = fn (int $days) => now()->subDays($days)->toDateTimeString();
+    promotionDb()->table('contacts')->insert([
+        ['uuid' => 'a_regular', 'public_id' => 'contact_a', 'company_uuid' => 'company_uuid', 'user_uuid' => 'user_a', 'type' => 'customer', 'name' => 'Regular', 'created_at' => $days(400)],
+        ['uuid' => 'b_lapsed', 'public_id' => 'contact_b', 'company_uuid' => 'company_uuid', 'user_uuid' => 'user_b', 'type' => 'customer', 'name' => 'Lapsed', 'created_at' => $days(400)],
+        ['uuid' => 'c_new', 'public_id' => 'contact_c', 'company_uuid' => 'company_uuid', 'user_uuid' => null, 'type' => 'customer', 'name' => 'New', 'created_at' => $days(2)],
+        ['uuid' => 'd_other_company', 'public_id' => 'contact_d', 'company_uuid' => 'other_company', 'user_uuid' => null, 'type' => 'customer', 'name' => 'Other', 'created_at' => $days(2)],
+        ['uuid' => 'e_not_customer', 'public_id' => 'contact_e', 'company_uuid' => 'company_uuid', 'user_uuid' => null, 'type' => 'contact', 'name' => 'Vendor', 'created_at' => $days(2)],
+        ['uuid' => 'f_store_b', 'public_id' => 'contact_f', 'company_uuid' => 'company_uuid', 'user_uuid' => null, 'type' => 'customer', 'name' => 'Store B fan', 'created_at' => $days(400)],
+    ]);
+    $order = fn (string $uuid, string $customer, int $daysAgo, array $meta = ['storefront_id' => 'store_a'], string $status = 'completed') => [
+        'uuid' => $uuid, 'customer_uuid' => $customer, 'type' => 'storefront', 'status' => $status, 'meta' => json_encode($meta), 'created_at' => $days($daysAgo),
+    ];
+    promotionDb()->table('orders')->insert([
+        $order('o1', 'a_regular', 1),
+        $order('o2', 'a_regular', 5),
+        $order('o3', 'a_regular', 20, ['storefront_id' => 'store_a', 'storefront_network_id' => 'network_m']),
+        $order('o4', 'b_lapsed', 60),
+        $order('o5', 'b_lapsed', 2, ['storefront_id' => 'store_a'], 'canceled'),
+        $order('o6', 'f_store_b', 3, ['storefront_id' => 'store_b', 'storefront_network_id' => 'network_m']),
+    ]);
+    promotionDb()->table('transactions')->insert([
+        ['uuid' => 't1', 'customer_uuid' => 'a_regular', 'type' => 'storefront', 'status' => 'success', 'amount' => 9000],
+        ['uuid' => 't2', 'customer_uuid' => 'b_lapsed', 'type' => 'storefront', 'status' => 'success', 'amount' => 2000],
+        ['uuid' => 't3', 'customer_uuid' => 'b_lapsed', 'type' => 'storefront', 'status' => 'failed', 'amount' => 9000],
+    ]);
+    promotionDb()->table('user_devices')->insert([
+        ['uuid' => 'dev_a', 'user_uuid' => 'user_a', 'platform' => 'ios', 'token' => 'token_a', 'status' => 'active'],
+        ['uuid' => 'dev_b', 'user_uuid' => 'user_b', 'platform' => 'android', 'token' => 'token_b', 'status' => 'invalid'],
+    ]);
+});
+
+test('segment rules select the owner company customers by order history, spend, age and devices', function ($rules, $expected) {
+    expect(segmentUuids($rules))->toBe($expected);
+})->with([
+    'everyone'             => [[], ['a_regular', 'b_lapsed', 'c_new', 'f_store_b']],
+    'explicit customers'   => [['customers' => ['c_new', 'd_other_company']], ['c_new']],
+    'at least two orders'  => [['min_orders' => 2], ['a_regular']],
+    'never ordered here'   => [['max_orders' => 0], ['c_new', 'f_store_b']],
+    'ordered this week'    => [['ordered_within_days' => 7], ['a_regular']],
+    'lapsed for a month'   => [['not_ordered_within_days' => 30], ['b_lapsed']],
+    'joined this week'     => [['joined_within_days' => 7], ['c_new']],
+    'spent at least 5000'  => [['min_spent' => 5000], ['a_regular']],
+    'reachable by push'    => [['has_push_device' => true], ['a_regular']],
+    'combined'             => [['min_orders' => 1, 'max_orders' => 1], ['b_lapsed']],
+]);
+
+test('network segments count orders placed through the network', function () {
+    $network = Network::where('uuid', 'network_uuid')->first();
+
+    expect(segmentUuids(['min_orders' => 1], $network))->toBe(['a_regular', 'f_store_b']);
+});
+
+test('the dispatcher queues due campaigns in batches and records what it targeted', function () {
+    $bus     = fakeCampaignBus();
+    $segment = tap(new CustomerSegment())->forceFill(['uuid' => 'segment_uuid', 'company_uuid' => 'company_uuid', 'owner_uuid' => 'store_a_uuid', 'name' => 'Buyers', 'rules' => ['min_orders' => 1]]);
+    $segment->save();
+    $due     = makeCampaign(['segment_uuid' => 'segment_uuid']);
+    $future  = makeCampaign(['send_at' => now()->addHour()]);
+    $draft   = makeCampaign(['status' => Campaign::STATUS_DRAFT]);
+
+    $sent = (new CampaignDispatcher(new SegmentResolver()))->dispatchDue();
+
+    expect($sent)->toBe(1)
+        ->and($due->refresh()->status)->toBe(Campaign::STATUS_SENT)
+        ->and($due->stats)->toBe(['targeted' => 2, 'batches' => 1])
+        ->and($due->sent_at)->not->toBeNull()
+        ->and($future->refresh()->status)->toBe(Campaign::STATUS_SCHEDULED)
+        ->and($draft->refresh()->status)->toBe(Campaign::STATUS_DRAFT)
+        ->and($bus->jobs)->toHaveCount(1)
+        ->and($bus->jobs[0])->toBeInstanceOf(SendCampaignBatch::class)
+        ->and($bus->jobs[0]->customerUuids)->toBe(['a_regular', 'b_lapsed'])
+        // A campaign that is already being sent is never claimed twice.
+        ->and((new CampaignDispatcher(new SegmentResolver()))->dispatch($due))->toBeFalse();
+});
+
+test('explicit recipients narrow the audience, and an empty list reaches nobody', function () {
+    fakeCampaignBus();
+    $dispatcher = new CampaignDispatcher(new SegmentResolver());
+    $segment    = tap(new CustomerSegment())->forceFill(['uuid' => 'segment_uuid', 'company_uuid' => 'company_uuid', 'owner_uuid' => 'store_a_uuid', 'name' => 'Buyers', 'rules' => ['min_orders' => 1, 'customers' => ['a_regular', 'c_new']]]);
+    $segment->save();
+
+    $recipients   = makeCampaign(['recipients' => ['c_new', 'f_store_b']]);
+    $intersection = makeCampaign(['segment_uuid' => 'segment_uuid', 'recipients' => ['a_regular', 'b_lapsed']]);
+    $nobody       = makeCampaign(['recipients' => []]);
+    $disjoint     = makeCampaign(['segment_uuid' => 'segment_uuid', 'recipients' => ['f_store_b']]);
+
+    expect($dispatcher->audience($recipients)->orderBy('uuid')->pluck('uuid')->all())->toBe(['c_new', 'f_store_b'])
+        ->and($dispatcher->audience($intersection)->pluck('uuid')->all())->toBe(['a_regular'])
+        ->and($dispatcher->audience($nobody)->count())->toBe(0)
+        ->and($dispatcher->audience($disjoint)->count())->toBe(0);
+});
+
+test('campaigns without an owner or for a stopped promotion are canceled instead of sent', function () {
+    fakeCampaignBus();
+    $dispatcher = new CampaignDispatcher(new SegmentResolver());
+    $paused     = makePromotion(['status' => Promotion::STATUS_PAUSED]);
+    $expired    = makePromotion(['ends_at' => now()->subDay()]);
+    $live       = makePromotion();
+
+    $orphan    = makeCampaign(['owner_uuid' => 'missing_store']);
+    $forPaused = makeCampaign(['promotion_uuid' => $paused->uuid]);
+    $forEnded  = makeCampaign(['promotion_uuid' => $expired->uuid]);
+    $forGone   = makeCampaign(['promotion_uuid' => 'deleted_promotion']);
+    $forLive   = makeCampaign(['promotion_uuid' => $live->uuid]);
+
+    foreach ([$orphan, $forPaused, $forEnded, $forGone, $forLive] as $campaign) {
+        $dispatcher->dispatch($campaign);
+    }
+
+    expect($orphan->refresh()->stats)->toBe(['reason' => 'owner_missing'])
+        ->and($orphan->status)->toBe(Campaign::STATUS_CANCELED)
+        ->and($forPaused->refresh()->stats)->toBe(['reason' => 'promotion_unavailable'])
+        ->and($forEnded->refresh()->status)->toBe(Campaign::STATUS_CANCELED)
+        ->and($forGone->refresh()->status)->toBe(Campaign::STATUS_CANCELED)
+        ->and($forLive->refresh()->status)->toBe(Campaign::STATUS_SENT);
+});
+
+test('batches notify each customer, skip canceled campaigns and isolate failures', function () {
+    $campaign   = makeCampaign();
+    $dispatcher = fakeNotificationDispatcher(function ($notifiable) {
+        if ($notifiable->uuid === 'b_lapsed') {
+            throw new RuntimeException('database down');
+        }
+    });
+
+    (new SendCampaignBatch($campaign->uuid, ['a_regular', 'b_lapsed', 'c_new']))->handle();
+    (new SendCampaignBatch('missing_campaign', ['a_regular']))->handle();
+    $campaign->forceFill(['status' => Campaign::STATUS_CANCELED])->save();
+    (new SendCampaignBatch($campaign->uuid, ['a_regular']))->handle();
+
+    app()->offsetUnset(Illuminate\Contracts\Notifications\Dispatcher::class);
+
+    expect(array_column($dispatcher->sent, 0))->toBe(['a_regular', 'c_new'])
+        ->and($dispatcher->sent[0][1])->toBeInstanceOf(CampaignNotification::class);
+});
+
+test('the scheduled command dispatches due campaigns', function () {
+    fakeCampaignBus();
+    makeCampaign();
+    $command = new class extends DispatchCampaigns {
+        public array $lines = [];
+
+        public function info($string, $verbosity = null)
+        {
+            $this->lines[] = $string;
+        }
+    };
+
+    expect($command->handle(new CampaignDispatcher(new SegmentResolver())))->toBe(0)
+        ->and($command->lines)->toBe(['Dispatched 1 campaign(s).']);
+});
+
+test('campaign notifications honor channels and preferences and deep link to the campaign', function () {
+    $promotion = makePromotion();
+    $campaign  = makeCampaign(['promotion_uuid' => $promotion->uuid, 'channels' => ['inbox'], 'action' => ['type' => 'promotion', 'id' => $promotion->public_id]]);
+    $optedOut  = tap(new Contact())->forceFill(['meta' => ['notification_preferences' => ['promotions' => false]]]);
+    $customer  = tap(new Contact())->forceFill(['meta' => []]);
+
+    $inboxOnly = new CampaignNotification($campaign);
+    $pushOnly  = new CampaignNotification(makeCampaign(['channels' => ['push']]));
+    $both      = new CampaignNotification(makeCampaign(['channels' => ['sms']]));
+
+    expect($inboxOnly->via($optedOut))->toBe([])
+        ->and($inboxOnly->via($customer))->toBe(['database', SafeBroadcastChannel::class])
+        ->and($pushOnly->via($customer))->toBe([StorefrontPushChannel::class])
+        ->and($both->via($customer))->toBe([StorefrontPushChannel::class, 'database', SafeBroadcastChannel::class])
+        ->and($inboxOnly->toArray($customer))->toBe([
+            'title'        => 'Fresh deals',
+            'body'         => 'Come see what is new.',
+            'subject'      => 'Fresh deals',
+            'message'      => 'Come see what is new.',
+            'image'        => null,
+            'type'         => 'campaign',
+            'campaign_id'  => $campaign->public_id,
+            'promotion_id' => $promotion->public_id,
+            'store_id'     => 'store_a',
+            'action'       => 'promotion',
+            'action_id'    => $promotion->public_id,
+        ])
+        ->and($inboxOnly->toPush($customer)->data['campaign_id'])->toBe($campaign->public_id)
+        ->and($inboxOnly->toPush($customer)->analyticsLabel)->toBe('campaign')
+        ->and($inboxOnly->toBroadcast($customer)->data['type'])->toBe('campaign')
+        ->and($inboxOnly->broadcastType())->toBe('campaign')
+        ->and(collect($inboxOnly->pushStorefronts())->pluck('uuid')->all())->toBe(['store_a_uuid', 'network_uuid']);
+});
+
+test('network campaigns deep link with the network and survive missing memberships', function () {
+    $campaign = makeCampaign(['owner_uuid' => 'network_uuid', 'owner_type' => Network::class]);
+    $network  = new CampaignNotification($campaign);
+
+    expect($network->toArray(null)['network_id'])->toBe('network_m')
+        ->and(collect($network->pushStorefronts())->pluck('uuid')->all())->toBe(['network_uuid'])
+        ->and($campaign->resolveOwner())->toBeInstanceOf(Network::class)
+        ->and($campaign->enabledChannels())->toBe(['push', 'inbox']);
+
+    promotionDb()->getSchemaBuilder()->dropIfExists('network_stores');
+    $store = new CampaignNotification(makeCampaign());
+
+    expect(collect($store->pushStorefronts())->pluck('uuid')->all())->toBe(['store_a_uuid']);
+});
+
+test('campaigns relate to their segment, promotion and owner', function () {
+    $promotion = makePromotion();
+    $segment   = tap(new CustomerSegment())->forceFill(['uuid' => 'segment_uuid', 'owner_uuid' => 'store_a_uuid', 'owner_type' => 'storefront:store', 'name' => 'Buyers']);
+    $segment->save();
+    $campaign = makeCampaign(['segment_uuid' => 'segment_uuid', 'promotion_uuid' => $promotion->uuid]);
+
+    expect($campaign->segment->name)->toBe('Buyers')
+        ->and($campaign->promotion->uuid)->toBe($promotion->uuid)
+        ->and($campaign->owner()->getRelated())->toBeInstanceOf(Store::class)
+        ->and($segment->owner()->getRelated())->toBeInstanceOf(Store::class)
+        ->and($segment->getAttributes()['owner_type'])->toBe(Store::class)
+        ->and($campaign->image)->toBeNull();
+});
diff --git a/server/tests/Unit/Promotions/CampaignEndpointsTest.php b/server/tests/Unit/Promotions/CampaignEndpointsTest.php
new file mode 100644
index 00000000..f8e2e9ba
--- /dev/null
+++ b/server/tests/Unit/Promotions/CampaignEndpointsTest.php
@@ -0,0 +1,281 @@
+<?php
+
+require_once __DIR__ . '/../../Support/PromotionTestHelpers.php';
+
+use Fleetbase\Storefront\Http\Controllers\ActionController;
+use Fleetbase\Storefront\Http\Controllers\CampaignController;
+use Fleetbase\Storefront\Http\Controllers\CustomerSegmentController;
+use Fleetbase\Storefront\Http\Controllers\PromotionController;
+use Fleetbase\Storefront\Http\Filter\CampaignFilter;
+use Fleetbase\Storefront\Http\Filter\CustomerSegmentFilter;
+use Fleetbase\Storefront\Http\Requests\CampaignRequest;
+use Fleetbase\Storefront\Http\Requests\CustomerSegmentRequest;
+use Fleetbase\Storefront\Http\Resources\Campaign as CampaignResource;
+use Fleetbase\Storefront\Http\Resources\CustomerSegment as CustomerSegmentResource;
+use Fleetbase\Storefront\Models\Campaign;
+use Fleetbase\Storefront\Models\CustomerSegment;
+use Fleetbase\Storefront\Models\Promotion;
+use Fleetbase\Storefront\Models\Store;
+use Fleetbase\Storefront\Promotions\CampaignDispatcher;
+use Fleetbase\Storefront\Promotions\SegmentResolver;
+use Illuminate\Http\Request;
+
+function endpointCampaign(array $attributes = []): Campaign
+{
+    static $sequence = 0;
+    $sequence++;
+    $campaign = new Campaign();
+    $campaign->forceFill(array_merge([
+        'uuid'         => 'endpoint_campaign_' . $sequence,
+        'public_id'    => 'campaign_endpoint_' . $sequence,
+        'company_uuid' => 'company_uuid',
+        'owner_uuid'   => 'store_a_uuid',
+        'owner_type'   => Store::class,
+        'name'         => 'Campaign',
+        'status'       => Campaign::STATUS_DRAFT,
+        'title'        => 'Hello',
+        'body'         => 'World',
+    ], $attributes));
+    $campaign->save();
+
+    return $campaign;
+}
+
+function endpointSegment(array $attributes = []): CustomerSegment
+{
+    $segment = new CustomerSegment();
+    $segment->forceFill(array_merge([
+        'uuid'         => 'segment_uuid',
+        'public_id'    => 'segment_public',
+        'company_uuid' => 'company_uuid',
+        'owner_uuid'   => 'store_a_uuid',
+        'owner_type'   => Store::class,
+        'name'         => 'Everyone',
+        'rules'        => [],
+    ], $attributes));
+    $segment->save();
+
+    return $segment;
+}
+
+function endpointRequest(array $input = [], string $method = 'POST'): Request
+{
+    $request = Request::create('/', $method, $input);
+    $request->setLaravelSession(new Illuminate\Session\Store('campaigns', new Illuminate\Session\ArraySessionHandler(120)));
+    app()->instance('request', $request);
+
+    return $request;
+}
+
+/**
+ * Run model events (uuid and public id generation) for records created by the code under test.
+ */
+function withModelEvents(callable $callback): mixed
+{
+    Illuminate\Database\Eloquent\Model::setEventDispatcher(new Illuminate\Events\Dispatcher());
+    Illuminate\Database\Eloquent\Model::clearBootedModels();
+    app()->instance('responsecache', new class {
+        public function __call($method, $arguments)
+        {
+            return null;
+        }
+    });
+
+    try {
+        return $callback();
+    } finally {
+        Illuminate\Database\Eloquent\Model::unsetEventDispatcher();
+        Illuminate\Database\Eloquent\Model::clearBootedModels();
+        app()->offsetUnset('responsecache');
+    }
+}
+
+function campaignDispatcher(): CampaignDispatcher
+{
+    return new CampaignDispatcher(new SegmentResolver());
+}
+
+beforeEach(function () {
+    createPromotionSchema();
+    createCampaignSchema();
+    seedPromotionStores();
+    promotionDb()->table('contacts')->insert([
+        ['uuid' => 'customer_1', 'public_id' => 'contact_1', 'company_uuid' => 'company_uuid', 'type' => 'customer', 'name' => 'One', 'email' => 'one@example.test'],
+        ['uuid' => 'customer_2', 'public_id' => 'contact_2', 'company_uuid' => 'company_uuid', 'type' => 'customer', 'name' => 'Two', 'email' => null],
+        ['uuid' => 'outsider', 'public_id' => 'contact_3', 'company_uuid' => 'other_company', 'type' => 'customer', 'name' => 'Three', 'email' => null],
+    ]);
+    session(['company' => 'company_uuid', 'user' => 'user_uuid']);
+});
+
+test('campaigns can be sent now, only once, and canceled until sent', function () {
+    $bus        = fakeCampaignBus();
+    $controller = new CampaignController();
+    $draft      = endpointCampaign();
+    $canceled   = endpointCampaign(['status' => Campaign::STATUS_SCHEDULED, 'send_at' => now()->addDay()]);
+
+    $sent = $controller->send($draft->public_id, campaignDispatcher())->resolve(endpointRequest());
+
+    expect($sent['status'])->toBe(Campaign::STATUS_SENT)
+        ->and($sent['stats'])->toBe(['targeted' => 2, 'batches' => 1])
+        ->and($bus->jobs)->toHaveCount(1)
+        ->and($controller->send($draft->uuid, campaignDispatcher())->getData(true))->toBe(['error' => 'This campaign has already been sent.'])
+        ->and($controller->cancel($draft->uuid)->getData(true))->toBe(['error' => 'This campaign has already been sent.'])
+        ->and($controller->cancel($canceled->uuid)->resolve(endpointRequest())['status'])->toBe(Campaign::STATUS_CANCELED)
+        ->and($controller->send('missing', campaignDispatcher())->getStatusCode())->toBe(404)
+        ->and($controller->cancel('missing')->getStatusCode())->toBe(404);
+});
+
+test('campaign audiences are counted before sending', function () {
+    $controller = new CampaignController();
+    $all        = endpointCampaign();
+    $selected   = endpointCampaign(['recipients' => ['customer_2', 'outsider']]);
+    $orphan     = endpointCampaign(['owner_uuid' => 'missing_store']);
+
+    expect($controller->audience($all->uuid, campaignDispatcher())->getData(true))->toBe(['count' => 2])
+        ->and($controller->audience($selected->uuid, campaignDispatcher())->getData(true))->toBe(['count' => 1])
+        ->and($controller->audience($orphan->uuid, campaignDispatcher())->getStatusCode())->toBe(404)
+        ->and($controller->audience('missing', campaignDispatcher())->getStatusCode())->toBe(404);
+});
+
+test('segments preview their size and a sample, saved or not', function () {
+    $segment    = endpointSegment(['rules' => ['customers' => ['customer_1']]]);
+    $controller = new CustomerSegmentController();
+    $resolver   = new SegmentResolver();
+
+    expect($controller->preview($segment->public_id, $resolver)->getData(true))->toBe([
+        'count'  => 1,
+        'sample' => [['id' => 'contact_1', 'name' => 'One', 'email' => 'one@example.test', 'phone' => null]],
+    ])
+        ->and($controller->previewRules(endpointRequest(['owner_uuid' => 'network_uuid', 'rules' => ['unknown_rule' => 1]]), $resolver)->getData(true)['count'])->toBe(2)
+        ->and($controller->previewRules(endpointRequest(['owner_uuid' => 'someone_else']), $resolver)->getStatusCode())->toBe(400)
+        ->and($controller->preview('missing', $resolver)->getStatusCode())->toBe(404);
+
+    endpointSegment(['uuid' => 'orphan_segment', 'public_id' => 'segment_orphan', 'owner_uuid' => 'missing_store']);
+
+    expect($controller->preview('orphan_segment', $resolver)->getStatusCode())->toBe(404);
+});
+
+test('promotions are announced with a campaign sent now or when the promotion starts', function () {
+    withModelEvents(function () {
+        $bus        = fakeCampaignBus();
+        $controller = new PromotionController();
+        $live       = makePromotion(['name' => 'Half off', 'description' => 'Half off everything']);
+        $upcoming   = makePromotion(['name' => 'Next week', 'starts_at' => now()->addWeek()]);
+        $paused     = makePromotion(['status' => Promotion::STATUS_PAUSED]);
+        $segment    = endpointSegment(['rules' => ['customers' => ['customer_1']]]);
+
+        $now   = $controller->announce($live->public_id, endpointRequest(['segment' => $segment->uuid]), campaignDispatcher())->resolve(endpointRequest());
+        $later = $controller->announce($upcoming->uuid, endpointRequest(['title' => 'Coming soon', 'channels' => ['inbox']]), campaignDispatcher())->resolve(endpointRequest());
+
+        expect($now)->toMatchArray([
+            'name'           => 'Announce: Half off',
+            'title'          => 'Half off',
+            'body'           => 'Half off everything',
+            'status'         => Campaign::STATUS_SENT,
+            'promotion_uuid' => $live->uuid,
+            'segment_uuid'   => $segment->uuid,
+            'action'         => ['type' => 'promotion', 'id' => $live->public_id],
+            'stats'          => ['targeted' => 1, 'batches' => 1],
+        ])
+            ->and($later)->toMatchArray([
+                'title'    => 'Coming soon',
+                'body'     => 'A new deal is available, tap to see it.',
+                'status'   => Campaign::STATUS_SCHEDULED,
+                'channels' => ['inbox'],
+            ])
+            ->and($bus->jobs)->toHaveCount(1)
+            ->and($controller->announce($paused->uuid, endpointRequest(), campaignDispatcher())->getStatusCode())->toBe(400)
+            ->and($controller->announce($live->uuid, endpointRequest(['segment' => 'missing']), campaignDispatcher())->getStatusCode())->toBe(404)
+            ->and($controller->announce('missing', endpointRequest(), campaignDispatcher())->getStatusCode())->toBe(404);
+
+        $explicit = $controller->announce($live->uuid, endpointRequest(['send_at' => now()->addDay()->toDateTimeString()]), campaignDispatcher())->resolve(endpointRequest());
+
+        expect($explicit['status'])->toBe(Campaign::STATUS_SCHEDULED);
+    });
+});
+
+test('segment and campaign validation require owned storefronts and allowed values', function () {
+    $segmentRules  = (new CustomerSegmentRequest())->rules();
+    $campaignRules = CampaignRequest::createFrom(endpointRequest([], 'PUT'))->rules();
+    $owned         = CustomerSegmentRequest::ownedStorefrontRule();
+    $failures      = [];
+    foreach (['store_a_uuid', 'network_uuid', 'strangers_store'] as $owner) {
+        $owned('owner_uuid', $owner, function ($message) use (&$failures) {
+            $failures[] = $message;
+        });
+    }
+
+    expect($segmentRules['rules.min_orders'])->toBe(['nullable', 'integer', 'min:0'])
+        ->and($campaignRules['name'][0])->toBe('sometimes')
+        ->and($campaignRules['channels.*'])->toBe(['in:push,inbox'])
+        ->and($campaignRules['status'])->toBe(['sometimes', 'in:draft,scheduled'])
+        ->and($failures)->toBe(['The owner must be one of your stores or networks.'])
+        ->and((new CustomerSegmentRequest())->authorize())->toBeFalse()
+        ->and((new CampaignRequest())->authorize())->toBeFalse();
+});
+
+test('segment and campaign filters scope to the company', function () {
+    endpointSegment();
+    endpointSegment(['uuid' => 'network_segment', 'public_id' => 'segment_network', 'owner_uuid' => 'network_uuid', 'name' => 'Network']);
+    endpointSegment(['uuid' => 'foreign_segment', 'public_id' => 'segment_foreign', 'company_uuid' => 'other_company', 'name' => 'Foreign']);
+    endpointCampaign(['name' => 'Draft']);
+    endpointCampaign(['name' => 'Sent', 'status' => Campaign::STATUS_SENT, 'promotion_uuid' => 'promo', 'owner_uuid' => 'network_uuid']);
+    endpointCampaign(['name' => 'Foreign', 'company_uuid' => 'other_company']);
+
+    $filter = function (string $class, $builder, array $calls) {
+        $instance = (new ReflectionClass($class))->newInstanceWithoutConstructor();
+        $session  = new Illuminate\Session\Store('filter', new Illuminate\Session\ArraySessionHandler(1));
+        $session->put('company', 'company_uuid');
+        (new ReflectionProperty(Fleetbase\Http\Filter\Filter::class, 'builder'))->setValue($instance, $builder);
+        (new ReflectionProperty(Fleetbase\Http\Filter\Filter::class, 'session'))->setValue($instance, $session);
+        $instance->queryForInternal();
+        foreach ($calls as $method => $argument) {
+            $instance->{$method}($argument);
+        }
+
+        return $builder->orderBy('name')->pluck('name')->all();
+    };
+
+    expect($filter(CustomerSegmentFilter::class, CustomerSegment::query(), []))->toBe(['Everyone', 'Network'])
+        ->and($filter(CustomerSegmentFilter::class, CustomerSegment::query(), ['owner' => 'network_uuid']))->toBe(['Network'])
+        ->and($filter(CampaignFilter::class, Campaign::query(), []))->toBe(['Draft', 'Sent'])
+        ->and($filter(CampaignFilter::class, Campaign::query(), ['status' => 'sent', 'owner' => 'network_uuid', 'promotion' => 'promo']))->toBe(['Sent']);
+});
+
+test('segment and campaign resources expose console fields', function () {
+    $segment  = endpointSegment(['rules' => ['min_orders' => 1]]);
+    $campaign = endpointCampaign(['segment_uuid' => $segment->uuid, 'channels' => ['push']]);
+
+    expect((new CustomerSegmentResource($segment))->resolve(endpointRequest()))->toMatchArray(['id' => 'segment_uuid', 'name' => 'Everyone', 'rules' => ['min_orders' => 1]])
+        ->and((new CampaignResource($campaign))->resolve(endpointRequest()))->toMatchArray([
+            'id'           => $campaign->uuid,
+            'segment_name' => 'Everyone',
+            'channels'     => ['push'],
+            'recipients'   => [],
+            'image_url'    => null,
+        ]);
+});
+
+test('the promotional push action sends a tracked campaign to selected or all customers', function () {
+    withModelEvents(function () {
+        $bus        = fakeCampaignBus();
+        $controller = new ActionController();
+
+        $selected = $controller->sendPushNotification(endpointRequest(['title' => 'New menu', 'body' => 'Try it', 'customers' => ['customer_1', 'outsider'], 'store' => 'store_a']))->getData(true);
+        $all      = $controller->sendPushNotification(endpointRequest(['title' => 'New menu', 'body' => 'Try it', 'select_all' => true, 'store' => 'store_a']))->getData(true);
+        $nobody   = $controller->sendPushNotification(endpointRequest(['title' => 'New menu', 'body' => 'Try it', 'customers' => ['outsider'], 'store' => 'store_a']))->getData(true);
+
+        expect($selected)->toMatchArray(['status' => 'OK', 'sent_count' => 1, 'total' => 1])
+            ->and($all)->toMatchArray(['status' => 'OK', 'sent_count' => 2, 'total' => 2])
+            ->and($nobody)->toBe(['status' => 'OK', 'sent_count' => 0, 'total' => 0])
+            ->and(Campaign::query()->count())->toBe(2)
+            ->and(Campaign::query()->first()->only(['name', 'status', 'owner_uuid', 'recipients']))->toBe([
+                'name'       => 'Push notification: New menu',
+                'status'     => Campaign::STATUS_SENT,
+                'owner_uuid' => 'store_a_uuid',
+                'recipients' => ['customer_1'],
+            ])
+            ->and($bus->jobs)->toHaveCount(2)
+            ->and($controller->sendPushNotification(endpointRequest(['title' => 'x', 'body' => 'y', 'select_all' => true, 'store' => 'store_missing']))->getStatusCode())->toBe(404);
+    });
+});
diff --git a/server/tests/Unit/Providers/StorefrontServiceProviderTest.php b/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
index 1975fa63..d71c6aac 100644
--- a/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
+++ b/server/tests/Unit/Providers/StorefrontServiceProviderTest.php
@@ -110,6 +110,7 @@ protected function mergeConfigFrom($path, $key)
         'storefront:notify-order-nearby',
         'storefront:purge-carts',
         'storefront:release-promotion-reservations',
+        'storefront:dispatch-campaigns',
         'observers',
         'middleware',
         'expansions',

From c7a10fb16dce84a3b0e2a95800e20fc96feba012 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 18:29:03 +0800
Subject: [PATCH 7/8] feat: add console screens for promotions, promo codes,
 segments and campaigns

Promotions now has Promotions, Campaigns, Segments and Push Notifications
tabs (and sidebar entries). Promotions: list with type, trigger, status,
schedule, redemptions and discount given; a form for discounts,
conditions, targeting, limits and stacking; activate/pause/end; promo
code generation and management; and announcing a promotion to a segment.
Segments: rule builder with a live count of matching customers.
Campaigns: message, audience, channels and deep link, saved as a draft,
sent now or scheduled, with send and cancel actions.
---
 addon/adapters/campaign.js                    |   1 +
 addon/adapters/customer-segment.js            |   1 +
 addon/adapters/promotion-code.js              |   1 +
 addon/adapters/promotion.js                   |   1 +
 addon/components/modals/campaign-form.hbs     |  80 +++++++
 addon/components/modals/campaign-form.js      |  83 +++++++
 .../modals/customer-segment-form.hbs          |  31 +++
 .../modals/customer-segment-form.js           |  67 ++++++
 .../components/modals/promotion-announce.hbs  |  27 +++
 addon/components/modals/promotion-codes.hbs   |  65 +++++
 addon/components/modals/promotion-codes.js    |  69 ++++++
 addon/components/modals/promotion-form.hbs    | 167 +++++++++++++
 addon/components/modals/promotion-form.js     |  70 ++++++
 .../storefront/promotion/runs-cell.hbs        |   8 +
 .../storefront/promotion/trigger-cell.hbs     |   3 +
 .../storefront/promotion/type-cell.hbs        |  12 +
 addon/controllers/application.js              |  23 +-
 addon/controllers/promotions.js               |  15 ++
 addon/controllers/promotions/campaigns.js     | 196 +++++++++++++++
 addon/controllers/promotions/index.js         | 226 ++++++++++++++++++
 addon/controllers/promotions/segments.js      | 119 +++++++++
 addon/models/campaign.js                      |  50 ++++
 addon/models/customer-segment.js              |  23 ++
 addon/models/promotion-code.js                |  19 ++
 addon/models/promotion.js                     |  69 ++++++
 addon/routes.js                               |   5 +-
 addon/routes/promotions/campaigns.js          |  28 +++
 addon/routes/promotions/index.js              |  28 +++
 addon/routes/promotions/segments.js           |  27 +++
 addon/templates/promotions/campaigns.hbs      |  21 ++
 addon/templates/promotions/index.hbs          |  21 ++
 addon/templates/promotions/segments.hbs       |  21 ++
 app/adapters/campaign.js                      |   1 +
 app/adapters/customer-segment.js              |   1 +
 app/adapters/promotion-code.js                |   1 +
 app/adapters/promotion.js                     |   1 +
 app/components/modals/campaign-form.js        |   1 +
 .../modals/customer-segment-form.js           |   1 +
 app/components/modals/promotion-announce.js   |   1 +
 app/components/modals/promotion-codes.js      |   1 +
 app/components/modals/promotion-form.js       |   1 +
 .../storefront/promotion/runs-cell.js         |   1 +
 .../storefront/promotion/trigger-cell.js      |   1 +
 .../storefront/promotion/type-cell.js         |   1 +
 app/controllers/promotions/campaigns.js       |   1 +
 app/controllers/promotions/index.js           |   1 +
 app/controllers/promotions/segments.js        |   1 +
 app/models/campaign.js                        |   1 +
 app/models/customer-segment.js                |   1 +
 app/models/promotion-code.js                  |   1 +
 app/models/promotion.js                       |   1 +
 app/routes/promotions/campaigns.js            |   1 +
 app/routes/promotions/index.js                |   1 +
 app/routes/promotions/segments.js             |   1 +
 translations/en-us.yaml                       | 162 +++++++++++++
 55 files changed, 1759 insertions(+), 2 deletions(-)
 create mode 100644 addon/adapters/campaign.js
 create mode 100644 addon/adapters/customer-segment.js
 create mode 100644 addon/adapters/promotion-code.js
 create mode 100644 addon/adapters/promotion.js
 create mode 100644 addon/components/modals/campaign-form.hbs
 create mode 100644 addon/components/modals/campaign-form.js
 create mode 100644 addon/components/modals/customer-segment-form.hbs
 create mode 100644 addon/components/modals/customer-segment-form.js
 create mode 100644 addon/components/modals/promotion-announce.hbs
 create mode 100644 addon/components/modals/promotion-codes.hbs
 create mode 100644 addon/components/modals/promotion-codes.js
 create mode 100644 addon/components/modals/promotion-form.hbs
 create mode 100644 addon/components/modals/promotion-form.js
 create mode 100644 addon/components/storefront/promotion/runs-cell.hbs
 create mode 100644 addon/components/storefront/promotion/trigger-cell.hbs
 create mode 100644 addon/components/storefront/promotion/type-cell.hbs
 create mode 100644 addon/controllers/promotions/campaigns.js
 create mode 100644 addon/controllers/promotions/index.js
 create mode 100644 addon/controllers/promotions/segments.js
 create mode 100644 addon/models/campaign.js
 create mode 100644 addon/models/customer-segment.js
 create mode 100644 addon/models/promotion-code.js
 create mode 100644 addon/models/promotion.js
 create mode 100644 addon/routes/promotions/campaigns.js
 create mode 100644 addon/routes/promotions/index.js
 create mode 100644 addon/routes/promotions/segments.js
 create mode 100644 addon/templates/promotions/campaigns.hbs
 create mode 100644 addon/templates/promotions/index.hbs
 create mode 100644 addon/templates/promotions/segments.hbs
 create mode 100644 app/adapters/campaign.js
 create mode 100644 app/adapters/customer-segment.js
 create mode 100644 app/adapters/promotion-code.js
 create mode 100644 app/adapters/promotion.js
 create mode 100644 app/components/modals/campaign-form.js
 create mode 100644 app/components/modals/customer-segment-form.js
 create mode 100644 app/components/modals/promotion-announce.js
 create mode 100644 app/components/modals/promotion-codes.js
 create mode 100644 app/components/modals/promotion-form.js
 create mode 100644 app/components/storefront/promotion/runs-cell.js
 create mode 100644 app/components/storefront/promotion/trigger-cell.js
 create mode 100644 app/components/storefront/promotion/type-cell.js
 create mode 100644 app/controllers/promotions/campaigns.js
 create mode 100644 app/controllers/promotions/index.js
 create mode 100644 app/controllers/promotions/segments.js
 create mode 100644 app/models/campaign.js
 create mode 100644 app/models/customer-segment.js
 create mode 100644 app/models/promotion-code.js
 create mode 100644 app/models/promotion.js
 create mode 100644 app/routes/promotions/campaigns.js
 create mode 100644 app/routes/promotions/index.js
 create mode 100644 app/routes/promotions/segments.js

diff --git a/addon/adapters/campaign.js b/addon/adapters/campaign.js
new file mode 100644
index 00000000..b7ad838d
--- /dev/null
+++ b/addon/adapters/campaign.js
@@ -0,0 +1 @@
+export { default } from './storefront';
diff --git a/addon/adapters/customer-segment.js b/addon/adapters/customer-segment.js
new file mode 100644
index 00000000..b7ad838d
--- /dev/null
+++ b/addon/adapters/customer-segment.js
@@ -0,0 +1 @@
+export { default } from './storefront';
diff --git a/addon/adapters/promotion-code.js b/addon/adapters/promotion-code.js
new file mode 100644
index 00000000..b7ad838d
--- /dev/null
+++ b/addon/adapters/promotion-code.js
@@ -0,0 +1 @@
+export { default } from './storefront';
diff --git a/addon/adapters/promotion.js b/addon/adapters/promotion.js
new file mode 100644
index 00000000..b7ad838d
--- /dev/null
+++ b/addon/adapters/promotion.js
@@ -0,0 +1 @@
+export { default } from './storefront';
diff --git a/addon/components/modals/campaign-form.hbs b/addon/components/modals/campaign-form.hbs
new file mode 100644
index 00000000..a803a755
--- /dev/null
+++ b/addon/components/modals/campaign-form.hbs
@@ -0,0 +1,80 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container space-y-3">
+        {{#if this.hasAudienceCount}}
+            <div class="text-sm text-gray-600 dark:text-gray-300">{{t "storefront.promotions.campaigns.audience-count" count=this.audienceCount}}</div>
+        {{/if}}
+        <InputGroup @name={{t "storefront.promotions.common.name"}} @value={{this.campaign.name}} />
+        <InputGroup @name={{t "storefront.promotions.campaigns.title-label"}} @value={{this.campaign.title}} />
+        <InputGroup @name={{t "storefront.promotions.campaigns.body-label"}}>
+            <Textarea @value={{this.campaign.body}} class="form-input w-full" rows="3" />
+        </InputGroup>
+
+        <InputGroup @name={{t "storefront.promotions.campaigns.audience"}}>
+            <ModelSelect
+                @modelName="customer-segment"
+                @selectedModel={{this.segment}}
+                @query={{hash owner=this.campaign.owner_uuid}}
+                @placeholder={{t "storefront.promotions.common.all-customers"}}
+                @triggerClass="form-select form-input"
+                @renderInPlace={{true}}
+                @infiniteScroll={{false}}
+                @allowClear={{true}}
+                @onChange={{this.setSegment}}
+                as |segment|
+            >
+                {{segment.name}}
+            </ModelSelect>
+        </InputGroup>
+
+        <InputGroup @name={{t "storefront.promotions.campaigns.channels"}}>
+            <div class="flex space-x-6">
+                <Checkbox @value={{this.hasChannel "push"}} @label={{t "storefront.promotions.campaigns.channel-push"}} @onToggle={{fn this.toggleChannel "push"}} />
+                <Checkbox @value={{this.hasChannel "inbox"}} @label={{t "storefront.promotions.campaigns.channel-inbox"}} @onToggle={{fn this.toggleChannel "inbox"}} />
+            </div>
+        </InputGroup>
+
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+            <InputGroup @name={{t "storefront.promotions.campaigns.promotion"}} @helpText={{t "storefront.promotions.campaigns.promotion-help"}}>
+                <ModelSelect
+                    @modelName="promotion"
+                    @selectedModel={{this.promotion}}
+                    @query={{hash owner=this.campaign.owner_uuid}}
+                    @placeholder={{t "storefront.promotions.common.none"}}
+                    @triggerClass="form-select form-input"
+                    @renderInPlace={{true}}
+                    @infiniteScroll={{false}}
+                    @allowClear={{true}}
+                    @onChange={{this.setPromotion}}
+                    as |promotion|
+                >
+                    {{promotion.name}}
+                </ModelSelect>
+            </InputGroup>
+            {{#unless this.promotion}}
+                <InputGroup @name={{t "storefront.promotions.campaigns.link-url"}}>
+                    <Input class="form-input w-full" placeholder="https://" @value={{this.linkUrl}} {{on "change" this.setLinkUrl}} />
+                </InputGroup>
+            {{/unless}}
+        </div>
+
+        {{#if this.campaign.isEditable}}
+            <InputGroup @name={{t "storefront.promotions.campaigns.when"}}>
+                <div class="flex space-x-2">
+                    {{#each this.whenOptions as |option|}}
+                        <Button
+                            @size="sm"
+                            @type={{if (eq this.when option) "primary" "default"}}
+                            @text={{t (concat "storefront.promotions.campaigns.when-" option)}}
+                            @onClick={{fn this.setWhen option}}
+                        />
+                    {{/each}}
+                </div>
+            </InputGroup>
+            {{#if (eq this.when "schedule")}}
+                <InputGroup @name={{t "storefront.promotions.campaigns.send-at"}}>
+                    <DateTimeInput class="form-input w-full" @value={{this.campaign.send_at}} @onUpdate={{fn (mut this.campaign.send_at)}} />
+                </InputGroup>
+            {{/if}}
+        {{/if}}
+    </div>
+</Modal::Default>
diff --git a/addon/components/modals/campaign-form.js b/addon/components/modals/campaign-form.js
new file mode 100644
index 00000000..d117a932
--- /dev/null
+++ b/addon/components/modals/campaign-form.js
@@ -0,0 +1,83 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+
+/**
+ * Create / edit a campaign: message, audience, channels, deep link and when to send.
+ */
+export default class ModalsCampaignFormComponent extends Component {
+    @service store;
+    @service fetch;
+    @service modalsManager;
+    @tracked segment = null;
+    @tracked promotion = null;
+    @tracked audienceCount = null;
+
+    whenOptions = ['draft', 'now', 'schedule'];
+
+    constructor() {
+        super(...arguments);
+        this.load();
+    }
+
+    get campaign() {
+        return this.args.options.campaign;
+    }
+
+    get when() {
+        return this.args.options.when;
+    }
+
+    get hasAudienceCount() {
+        return this.audienceCount !== null;
+    }
+
+    get linkUrl() {
+        return this.campaign.action?.type === 'url' ? this.campaign.action.url : '';
+    }
+
+    hasChannel = (channel) => (this.campaign.channels ?? []).includes(channel);
+
+    async load() {
+        if (this.campaign.segment_uuid) {
+            this.segment = await this.store.findRecord('customer-segment', this.campaign.segment_uuid).catch(() => null);
+        }
+        if (this.campaign.promotion_uuid) {
+            this.promotion = await this.store.findRecord('promotion', this.campaign.promotion_uuid).catch(() => null);
+        }
+        if (!this.campaign.isNew) {
+            const { count } = await this.fetch.get(`campaigns/${this.campaign.id}/audience`, {}, { namespace: 'storefront/int/v1' }).catch(() => ({ count: null }));
+            this.audienceCount = count;
+        }
+    }
+
+    @action setWhen(when) {
+        this.modalsManager.setOption('when', when);
+    }
+
+    @action setSegment(segment) {
+        this.segment = segment;
+        this.campaign.segment_uuid = segment?.id ?? null;
+    }
+
+    @action setPromotion(promotion) {
+        this.promotion = promotion;
+        this.campaign.promotion_uuid = promotion?.id ?? null;
+        this.campaign.action = promotion ? { type: 'promotion', id: promotion.public_id } : null;
+    }
+
+    @action setLinkUrl({ target }) {
+        this.campaign.action = target.value ? { type: 'url', url: target.value } : null;
+    }
+
+    @action toggleChannel(channel, enabled) {
+        const channels = new Set(this.campaign.channels ?? []);
+        if (enabled) {
+            channels.add(channel);
+        } else {
+            channels.delete(channel);
+        }
+        this.campaign.channels = [...channels];
+    }
+}
diff --git a/addon/components/modals/customer-segment-form.hbs b/addon/components/modals/customer-segment-form.hbs
new file mode 100644
index 00000000..b9f84eb6
--- /dev/null
+++ b/addon/components/modals/customer-segment-form.hbs
@@ -0,0 +1,31 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container space-y-3">
+        <InputGroup @name={{t "storefront.promotions.common.name"}} @value={{this.segment.name}} />
+        <InputGroup @name={{t "storefront.promotions.common.description"}}>
+            <Textarea @value={{this.segment.description}} class="form-input w-full" rows="2" />
+        </InputGroup>
+
+        <div class="pt-2 border-t dark:border-gray-700">
+            <div class="flex items-center justify-between mb-2">
+                <h4 class="font-semibold text-sm dark:text-white">{{t "storefront.promotions.segments.rules"}}</h4>
+                {{#if this.hasMatching}}
+                    <Badge @status="info" @hideStatusDot={{true}}>{{t "storefront.promotions.segments.matching" count=this.matching}}</Badge>
+                {{/if}}
+            </div>
+            <p class="text-xs text-gray-500 mb-2">{{t "storefront.promotions.segments.rules-help"}}</p>
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+                {{#each this.numberRules as |rule|}}
+                    <InputGroup @name={{t rule.label}}>
+                        <Input @type="number" min="0" class="form-input w-full" @value={{get this.rules rule.key}} {{on "input" (fn this.setNumberRule rule.key)}} />
+                    </InputGroup>
+                {{/each}}
+                <InputGroup @name={{t "storefront.promotions.segments.min-spent"}}>
+                    <MoneyInput class="w-full" @currency={{@options.currency}} @value={{this.rules.min_spent}} @canSelectCurrency={{false}} @onChange={{fn this.setMoneyRule "min_spent"}} />
+                </InputGroup>
+            </div>
+            <div class="mt-3">
+                <Toggle @isToggled={{this.rules.has_push_device}} @onToggle={{fn this.setBooleanRule "has_push_device"}} @label={{t "storefront.promotions.segments.has-push-device"}} />
+            </div>
+        </div>
+    </div>
+</Modal::Default>
diff --git a/addon/components/modals/customer-segment-form.js b/addon/components/modals/customer-segment-form.js
new file mode 100644
index 00000000..fc90f937
--- /dev/null
+++ b/addon/components/modals/customer-segment-form.js
@@ -0,0 +1,67 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { debounce } from '@ember/runloop';
+
+/**
+ * Create / edit a customer segment with a live count of matching customers.
+ */
+export default class ModalsCustomerSegmentFormComponent extends Component {
+    @service fetch;
+    @tracked matching = null;
+
+    numberRules = ['min_orders', 'max_orders', 'ordered_within_days', 'not_ordered_within_days', 'joined_within_days'].map((key) => ({
+        key,
+        label: `storefront.promotions.segments.${key.replace(/_/g, '-')}`,
+    }));
+
+    constructor() {
+        super(...arguments);
+        this.refreshCount();
+    }
+
+    get segment() {
+        return this.args.options.segment;
+    }
+
+    get hasMatching() {
+        return this.matching !== null;
+    }
+
+    get rules() {
+        return this.segment.rules ?? {};
+    }
+
+    setRule(key, value) {
+        const rules = { ...this.rules };
+        if (value === null || value === '' || value === false) {
+            delete rules[key];
+        } else {
+            rules[key] = value;
+        }
+        this.segment.rules = rules;
+        debounce(this, this.refreshCount, 400);
+    }
+
+    @action setNumberRule(key, { target }) {
+        this.setRule(key, target.value === '' ? null : Number(target.value));
+    }
+
+    @action setMoneyRule(key, value) {
+        this.setRule(key, value || null);
+    }
+
+    @action setBooleanRule(key, value) {
+        this.setRule(key, value);
+    }
+
+    async refreshCount() {
+        try {
+            const { count } = await this.fetch.post('customer-segments/preview', { owner_uuid: this.segment.owner_uuid, rules: this.rules }, { namespace: 'storefront/int/v1' });
+            this.matching = count;
+        } catch {
+            this.matching = null;
+        }
+    }
+}
diff --git a/addon/components/modals/promotion-announce.hbs b/addon/components/modals/promotion-announce.hbs
new file mode 100644
index 00000000..ef4f47ad
--- /dev/null
+++ b/addon/components/modals/promotion-announce.hbs
@@ -0,0 +1,27 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container space-y-3">
+        <p class="text-sm text-gray-600 dark:text-gray-300">{{t "storefront.promotions.announce.help"}}</p>
+        <InputGroup @name={{t "storefront.promotions.announce.segment"}}>
+            <ModelSelect
+                @modelName="customer-segment"
+                @selectedModel={{@options.announcement.segment}}
+                @placeholder={{t "storefront.promotions.announce.segment-placeholder"}}
+                @triggerClass="form-select form-input"
+                @renderInPlace={{true}}
+                @infiniteScroll={{false}}
+                @allowClear={{true}}
+                @onChange={{fn (mut @options.announcement.segment)}}
+                as |segment|
+            >
+                {{segment.name}}
+            </ModelSelect>
+        </InputGroup>
+        <InputGroup @name={{t "storefront.promotions.announce.message-title"}} @value={{@options.announcement.title}} />
+        <InputGroup @name={{t "storefront.promotions.announce.message-body"}}>
+            <Textarea @value={{@options.announcement.body}} class="form-input w-full" rows="3" />
+        </InputGroup>
+        <InputGroup @name={{t "storefront.promotions.announce.send-at"}}>
+            <DateTimeInput class="form-input w-full" @value={{@options.announcement.send_at}} @onUpdate={{fn (mut @options.announcement.send_at)}} />
+        </InputGroup>
+    </div>
+</Modal::Default>
diff --git a/addon/components/modals/promotion-codes.hbs b/addon/components/modals/promotion-codes.hbs
new file mode 100644
index 00000000..1fa4061f
--- /dev/null
+++ b/addon/components/modals/promotion-codes.hbs
@@ -0,0 +1,65 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container space-y-4">
+        <div class="grid grid-cols-2 md:grid-cols-4 gap-2">
+            <InputGroup @name={{t "storefront.promotions.codes.count"}}>
+                <Input @type="number" min="1" max="1000" class="form-input w-full" @value={{this.count}} {{on "input" (fn this.setValue "count")}} />
+            </InputGroup>
+            <InputGroup @name={{t "storefront.promotions.codes.prefix"}}>
+                <Input class="form-input w-full uppercase" @value={{this.prefix}} {{on "input" (fn this.setValue "prefix")}} />
+            </InputGroup>
+            <InputGroup @name={{t "storefront.promotions.codes.length"}}>
+                <Input @type="number" min="6" max="16" class="form-input w-full" @value={{this.length}} {{on "input" (fn this.setValue "length")}} />
+            </InputGroup>
+            <InputGroup @name={{t "storefront.promotions.codes.usage-limit"}} @helpText={{t "storefront.promotions.codes.usage-limit-help"}}>
+                <Input @type="number" min="1" class="form-input w-full" @value={{this.usageLimit}} {{on "input" (fn this.setValue "usageLimit")}} />
+            </InputGroup>
+        </div>
+        <InputGroup @name={{t "storefront.promotions.codes.specific-code"}}>
+            <Input class="form-input w-full uppercase" placeholder={{t "storefront.promotions.codes.specific-code-placeholder"}} @value={{this.specificCode}} {{on "input" (fn this.setValue "specificCode")}} />
+        </InputGroup>
+        <div class="flex justify-end">
+            <Button
+                @type="primary"
+                @icon="wand-magic-sparkles"
+                @text={{t "storefront.promotions.codes.generate"}}
+                @isLoading={{this.isGenerating}}
+                @onClick={{this.generate}}
+                @permission="storefront generate-codes promotion"
+            />
+        </div>
+
+        <div class="border rounded-md dark:border-gray-700 max-h-80 overflow-y-auto">
+            <table class="w-full text-sm">
+                <thead class="text-left text-xs uppercase text-gray-500">
+                    <tr>
+                        <th class="px-3 py-2">{{t "storefront.promotions.codes.code"}}</th>
+                        <th class="px-3 py-2">{{t "storefront.promotions.codes.used"}}</th>
+                        <th class="px-3 py-2">{{t "storefront.promotions.common.status"}}</th>
+                        <th class="px-3 py-2"></th>
+                    </tr>
+                </thead>
+                <tbody>
+                    {{#each this.codes as |code|}}
+                        <tr class="border-t dark:border-gray-700">
+                            <td class="px-3 py-2 font-mono"><ClickToCopy @value={{code.code}}>{{code.code}}</ClickToCopy></td>
+                            <td class="px-3 py-2">{{code.times_used}}{{#if code.usage_limit}} / {{code.usage_limit}}{{/if}}</td>
+                            <td class="px-3 py-2"><Badge @status={{code.status}} @hideStatusDot={{true}} /></td>
+                            <td class="px-3 py-2 text-right">
+                                <Button
+                                    @size="xs"
+                                    @text={{if (eq code.status "active") (t "storefront.promotions.codes.disable") (t "storefront.promotions.codes.enable")}}
+                                    @onClick={{fn this.toggleCode code}}
+                                    @permission="storefront update promotion-code"
+                                />
+                            </td>
+                        </tr>
+                    {{else}}
+                        <tr>
+                            <td colspan="4" class="px-3 py-4 text-center text-gray-500">{{t "storefront.promotions.codes.empty"}}</td>
+                        </tr>
+                    {{/each}}
+                </tbody>
+            </table>
+        </div>
+    </div>
+</Modal::Default>
diff --git a/addon/components/modals/promotion-codes.js b/addon/components/modals/promotion-codes.js
new file mode 100644
index 00000000..fa4acb1d
--- /dev/null
+++ b/addon/components/modals/promotion-codes.js
@@ -0,0 +1,69 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+
+/**
+ * Lists a promotion's codes and generates new ones with the settings in the form.
+ */
+export default class ModalsPromotionCodesComponent extends Component {
+    @service store;
+    @service fetch;
+    @service intl;
+    @service notifications;
+    @tracked codes = [];
+    @tracked count = 10;
+    @tracked prefix = '';
+    @tracked length = 8;
+    @tracked usageLimit = 1;
+    @tracked specificCode = '';
+    @tracked isGenerating = false;
+
+    constructor() {
+        super(...arguments);
+        this.loadCodes();
+    }
+
+    get promotion() {
+        return this.args.options.promotion;
+    }
+
+    async loadCodes() {
+        this.codes = await this.store.query('promotion-code', { promotion: this.promotion.id, limit: 500, sort: '-created_at' });
+    }
+
+    @action setValue(property, { target }) {
+        this[property] = target.value;
+    }
+
+    @action async generate() {
+        this.isGenerating = true;
+
+        const body = this.specificCode
+            ? { code: this.specificCode, usage_limit: this.usageLimit || null }
+            : { count: Number(this.count) || 1, prefix: this.prefix, length: Number(this.length) || 8, usage_limit: this.usageLimit || null };
+
+        try {
+            await this.fetch.post(`promotions/${this.promotion.id}/generate-codes`, body, { namespace: 'storefront/int/v1' });
+            this.specificCode = '';
+            this.promotion.trigger = 'code';
+            this.notifications.success(this.intl.t('storefront.promotions.codes.generated-success'));
+            await this.loadCodes();
+        } catch (error) {
+            this.notifications.serverError(error);
+        } finally {
+            this.isGenerating = false;
+        }
+    }
+
+    @action async toggleCode(code) {
+        code.status = code.status === 'active' ? 'disabled' : 'active';
+
+        try {
+            await code.save();
+        } catch (error) {
+            code.rollbackAttributes();
+            this.notifications.serverError(error);
+        }
+    }
+}
diff --git a/addon/components/modals/promotion-form.hbs b/addon/components/modals/promotion-form.hbs
new file mode 100644
index 00000000..2673e0d1
--- /dev/null
+++ b/addon/components/modals/promotion-form.hbs
@@ -0,0 +1,167 @@
+<Modal::Default @modalIsOpened={{@modalIsOpened}} @options={{@options}} @confirm={{@onConfirm}} @decline={{@onDecline}}>
+    <div class="modal-body-container space-y-4">
+        <ContentPanel @title={{t "storefront.promotions.form.basics"}} @open={{true}} @wrapperClass="bordered-top">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+                <InputGroup @name={{t "storefront.promotions.common.name"}} @value={{this.promotion.name}} @helpText={{t "storefront.promotions.form.name-help"}} @wrapperClass="md:col-span-2" />
+                <InputGroup @name={{t "storefront.promotions.common.description"}} @helpText={{t "storefront.promotions.form.description-help"}} @wrapperClass="md:col-span-2">
+                    <Textarea @value={{this.promotion.description}} class="form-input w-full" rows="2" />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.list.type"}} @helpText={{t "storefront.promotions.form.type-help"}}>
+                    <select class="form-select w-full" {{on "change" (fn this.setField "type")}}>
+                        {{#each this.types as |type|}}
+                            <option value={{type}} selected={{eq type this.promotion.type}}>{{t (concat "storefront.promotions.types." type)}}</option>
+                        {{/each}}
+                    </select>
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.list.trigger"}} @helpText={{t "storefront.promotions.form.trigger-help"}}>
+                    <select class="form-select w-full" {{on "change" (fn this.setField "trigger")}}>
+                        {{#each this.triggers as |trigger|}}
+                            <option value={{trigger}} selected={{eq trigger this.promotion.trigger}}>{{t (concat "storefront.promotions.triggers." trigger)}}</option>
+                        {{/each}}
+                    </select>
+                </InputGroup>
+
+                {{#if (eq this.promotion.type "percentage")}}
+                    <InputGroup @name={{t "storefront.promotions.form.percent-off"}}>
+                        <Input @type="number" min="0" max="100" step="0.01" class="form-input w-full" @value={{this.promotion.value}} {{on "input" (fn this.setNumber "value")}} />
+                    </InputGroup>
+                {{else if (eq this.promotion.type "fixed_amount")}}
+                    <InputGroup @name={{t "storefront.promotions.form.amount-off"}}>
+                        <MoneyInput class="w-full" @currency={{@options.currency}} @value={{this.promotion.value}} @canSelectCurrency={{false}} @onChange={{fn this.setMoney "value"}} />
+                    </InputGroup>
+                {{else if (eq this.promotion.type "bogo")}}
+                    <div class="md:col-span-2 grid grid-cols-3 gap-2">
+                        <InputGroup @name={{t "storefront.promotions.form.buy-quantity"}}>
+                            <Input @type="number" min="1" class="form-input w-full" @value={{this.bogo.buy_quantity}} {{on "input" (fn this.setBogo "buy_quantity")}} />
+                        </InputGroup>
+                        <InputGroup @name={{t "storefront.promotions.form.get-quantity"}}>
+                            <Input @type="number" min="1" class="form-input w-full" @value={{this.bogo.get_quantity}} {{on "input" (fn this.setBogo "get_quantity")}} />
+                        </InputGroup>
+                        <InputGroup @name={{t "storefront.promotions.form.get-discount-percent"}}>
+                            <Input @type="number" min="0" max="100" class="form-input w-full" @value={{this.bogo.discount_percent}} {{on "input" (fn this.setBogo "discount_percent")}} />
+                        </InputGroup>
+                        <p class="col-span-3 text-xs text-gray-500">{{t "storefront.promotions.form.bogo-help"}}</p>
+                    </div>
+                {{/if}}
+
+                <InputGroup @name={{t "storefront.promotions.common.status"}}>
+                    <select class="form-select w-full" {{on "change" (fn this.setField "status")}}>
+                        {{#each this.statuses as |status|}}
+                            <option value={{status}} selected={{eq status this.promotion.status}}>{{t (concat "storefront.promotions.statuses." status)}}</option>
+                        {{/each}}
+                    </select>
+                </InputGroup>
+            </div>
+        </ContentPanel>
+
+        <ContentPanel @title={{t "storefront.promotions.form.schedule"}} @open={{true}} @wrapperClass="bordered-top">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+                <InputGroup @name={{t "storefront.promotions.form.starts-at"}}>
+                    <DateTimeInput class="form-input w-full" @value={{this.promotion.starts_at}} @onUpdate={{fn (mut this.promotion.starts_at)}} />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.form.ends-at"}}>
+                    <DateTimeInput class="form-input w-full" @value={{this.promotion.ends_at}} @onUpdate={{fn (mut this.promotion.ends_at)}} />
+                </InputGroup>
+                <p class="md:col-span-2 text-xs text-gray-500">{{t "storefront.promotions.form.schedule-help"}}</p>
+            </div>
+        </ContentPanel>
+
+        <ContentPanel @title={{t "storefront.promotions.form.conditions"}} @open={{false}} @wrapperClass="bordered-top">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+                <InputGroup @name={{t "storefront.promotions.form.min-subtotal"}}>
+                    <MoneyInput class="w-full" @currency={{@options.currency}} @value={{this.promotion.min_subtotal}} @canSelectCurrency={{false}} @onChange={{fn this.setMoney "min_subtotal"}} />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.form.min-items"}}>
+                    <Input @type="number" min="1" class="form-input w-full" @value={{this.promotion.min_items}} {{on "input" (fn this.setNumber "min_items")}} />
+                </InputGroup>
+                <div class="md:col-span-2">
+                    <Toggle
+                        @isToggled={{this.promotion.first_order_only}}
+                        @onToggle={{fn (mut this.promotion.first_order_only)}}
+                        @label={{t "storefront.promotions.form.first-order-only"}}
+                        @helpText={{t "storefront.promotions.form.first-order-only-help"}}
+                    />
+                </div>
+            </div>
+        </ContentPanel>
+
+        <ContentPanel @title={{t "storefront.promotions.form.targeting"}} @open={{false}} @wrapperClass="bordered-top">
+            <p class="text-xs text-gray-500 mb-2">{{t "storefront.promotions.form.targeting-help"}}</p>
+            <InputGroup @name={{t "storefront.promotions.form.products"}}>
+                <ModelSelectMultiple
+                    @modelName="product"
+                    @query={{hash store_uuid=@options.storeId}}
+                    @selectedModel={{this.products}}
+                    @onChange={{fn this.setTargets "products" "products"}}
+                    @triggerClass="form-select form-input w-full"
+                    @renderInPlace={{true}}
+                    @infiniteScroll={{false}}
+                    as |model|
+                >
+                    {{model.name}}
+                </ModelSelectMultiple>
+            </InputGroup>
+            <InputGroup @name={{t "storefront.promotions.form.categories"}}>
+                <ModelSelectMultiple
+                    @modelName="category"
+                    @query={{hash for="storefront_product" owner_uuid=@options.storeId}}
+                    @selectedModel={{this.categories}}
+                    @onChange={{fn this.setTargets "categories" "categories"}}
+                    @triggerClass="form-select form-input w-full"
+                    @renderInPlace={{true}}
+                    @infiniteScroll={{false}}
+                    as |model|
+                >
+                    {{model.name}}
+                </ModelSelectMultiple>
+            </InputGroup>
+            <InputGroup @name={{t "storefront.promotions.form.exclude-products"}}>
+                <ModelSelectMultiple
+                    @modelName="product"
+                    @query={{hash store_uuid=@options.storeId}}
+                    @selectedModel={{this.excludedProducts}}
+                    @onChange={{fn this.setTargets "exclude_products" "excludedProducts"}}
+                    @triggerClass="form-select form-input w-full"
+                    @renderInPlace={{true}}
+                    @infiniteScroll={{false}}
+                    as |model|
+                >
+                    {{model.name}}
+                </ModelSelectMultiple>
+            </InputGroup>
+        </ContentPanel>
+
+        <ContentPanel @title={{t "storefront.promotions.form.limits"}} @open={{false}} @wrapperClass="bordered-top">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-2">
+                <InputGroup @name={{t "storefront.promotions.form.usage-limit"}}>
+                    <Input @type="number" min="1" class="form-input w-full" @value={{this.promotion.usage_limit}} {{on "input" (fn this.setNumber "usage_limit")}} />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.form.usage-limit-per-customer"}}>
+                    <Input @type="number" min="1" class="form-input w-full" @value={{this.promotion.usage_limit_per_customer}} {{on "input" (fn this.setNumber "usage_limit_per_customer")}} />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.form.budget-amount"}}>
+                    <MoneyInput class="w-full" @currency={{@options.currency}} @value={{this.promotion.budget_amount}} @canSelectCurrency={{false}} @onChange={{fn this.setMoney "budget_amount"}} />
+                </InputGroup>
+                <InputGroup @name={{t "storefront.promotions.form.max-discount-amount"}}>
+                    <MoneyInput class="w-full" @currency={{@options.currency}} @value={{this.promotion.max_discount_amount}} @canSelectCurrency={{false}} @onChange={{fn this.setMoney "max_discount_amount"}} />
+                </InputGroup>
+                <p class="md:col-span-2 text-xs text-gray-500">{{t "storefront.promotions.form.limits-help"}}</p>
+            </div>
+        </ContentPanel>
+
+        <ContentPanel @title={{t "storefront.promotions.form.stacking"}} @open={{false}} @wrapperClass="bordered-top">
+            <div class="space-y-3">
+                <Toggle
+                    @isToggled={{this.promotion.stackable}}
+                    @onToggle={{fn (mut this.promotion.stackable)}}
+                    @label={{t "storefront.promotions.form.stackable"}}
+                    @helpText={{t "storefront.promotions.form.stackable-help"}}
+                />
+                <InputGroup @name={{t "storefront.promotions.form.priority"}} @helpText={{t "storefront.promotions.form.priority-help"}}>
+                    <Input @type="number" class="form-input w-full" @value={{this.promotion.priority}} {{on "input" (fn this.setNumber "priority")}} />
+                </InputGroup>
+                <Toggle @isToggled={{this.promotion.is_public}} @onToggle={{fn (mut this.promotion.is_public)}} @label={{t "storefront.promotions.form.is-public"}} />
+            </div>
+        </ContentPanel>
+    </div>
+</Modal::Default>
diff --git a/addon/components/modals/promotion-form.js b/addon/components/modals/promotion-form.js
new file mode 100644
index 00000000..dc45af6a
--- /dev/null
+++ b/addon/components/modals/promotion-form.js
@@ -0,0 +1,70 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+
+/**
+ * Create / edit a promotion. Targeting pickers work on models, while the promotion stores
+ * their ids in `applies_to`, so the selected models are loaded when the form opens.
+ */
+export default class ModalsPromotionFormComponent extends Component {
+    @service store;
+    @tracked products = [];
+    @tracked categories = [];
+    @tracked excludedProducts = [];
+
+    types = ['percentage', 'fixed_amount', 'free_delivery', 'bogo'];
+    triggers = ['automatic', 'code'];
+    statuses = ['draft', 'active', 'paused', 'ended'];
+
+    constructor() {
+        super(...arguments);
+        this.loadTargets();
+    }
+
+    get promotion() {
+        return this.args.options.promotion;
+    }
+
+    get appliesTo() {
+        return this.promotion.applies_to ?? {};
+    }
+
+    get bogo() {
+        return this.promotion.bogo_config ?? {};
+    }
+
+    async loadTargets() {
+        this.products = await this.findAll('product', this.appliesTo.products);
+        this.categories = await this.findAll('category', this.appliesTo.categories);
+        this.excludedProducts = await this.findAll('product', this.appliesTo.exclude_products);
+    }
+
+    async findAll(modelName, ids = []) {
+        const records = await Promise.all((ids ?? []).map((id) => this.store.findRecord(modelName, id).catch(() => null)));
+
+        return records.filter(Boolean);
+    }
+
+    @action setTargets(key, property, models) {
+        this[property] = models;
+        this.promotion.applies_to = { ...this.appliesTo, [key]: models.map((model) => model.id) };
+    }
+
+    @action setBogo(key, { target }) {
+        const value = target.value === '' ? null : Number(target.value);
+        this.promotion.bogo_config = { ...this.bogo, [key]: value };
+    }
+
+    @action setField(property, { target }) {
+        this.promotion[property] = target.value;
+    }
+
+    @action setNumber(property, { target }) {
+        this.promotion[property] = target.value === '' ? null : Number(target.value);
+    }
+
+    @action setMoney(property, value) {
+        this.promotion[property] = value === 0 ? null : value;
+    }
+}
diff --git a/addon/components/storefront/promotion/runs-cell.hbs b/addon/components/storefront/promotion/runs-cell.hbs
new file mode 100644
index 00000000..d52e2e87
--- /dev/null
+++ b/addon/components/storefront/promotion/runs-cell.hbs
@@ -0,0 +1,8 @@
+<Table::Cell::Base @column={{@column}}>
+    <div class="flex flex-col text-xs">
+        <span>{{or @row.runsFrom "—"}}</span>
+        {{#if @row.runsUntil}}
+            <span class="text-gray-500">→ {{@row.runsUntil}}</span>
+        {{/if}}
+    </div>
+</Table::Cell::Base>
diff --git a/addon/components/storefront/promotion/trigger-cell.hbs b/addon/components/storefront/promotion/trigger-cell.hbs
new file mode 100644
index 00000000..bc5d619c
--- /dev/null
+++ b/addon/components/storefront/promotion/trigger-cell.hbs
@@ -0,0 +1,3 @@
+<Table::Cell::Base @column={{@column}}>
+    <Badge @status={{if (eq @row.trigger "code") "info" "success"}} @hideStatusDot={{true}}>{{t (concat "storefront.promotions.triggers." @row.trigger)}}</Badge>
+</Table::Cell::Base>
diff --git a/addon/components/storefront/promotion/type-cell.hbs b/addon/components/storefront/promotion/type-cell.hbs
new file mode 100644
index 00000000..6e9fb7e5
--- /dev/null
+++ b/addon/components/storefront/promotion/type-cell.hbs
@@ -0,0 +1,12 @@
+<Table::Cell::Base @column={{@column}}>
+    <div class="flex flex-col">
+        <span>{{t (concat "storefront.promotions.types." @row.type)}}</span>
+        {{#if (eq @row.type "percentage")}}
+            <span class="text-xs text-gray-500">{{@row.value}}%</span>
+        {{else if (eq @row.type "fixed_amount")}}
+            <span class="text-xs text-gray-500">{{format-currency @row.value @row.currency}}</span>
+        {{else if (eq @row.type "bogo")}}
+            <span class="text-xs text-gray-500">{{or @row.bogo_config.buy_quantity 1}} + {{or @row.bogo_config.get_quantity 1}}</span>
+        {{/if}}
+    </div>
+</Table::Cell::Base>
diff --git a/addon/controllers/application.js b/addon/controllers/application.js
index e8e43b3a..a214b57e 100644
--- a/addon/controllers/application.js
+++ b/addon/controllers/application.js
@@ -97,12 +97,33 @@ export default class ApplicationController extends Controller {
             },
             {
                 label: this.intl.t('storefront.sidebar.promotions'),
-                description: 'Send promotional notifications.',
+                description: 'Discounts, promo codes, customer segments and campaigns.',
                 icon: 'bullhorn',
                 permission: 'storefront view promotions',
                 visible: this.can('storefront see promotions'),
                 disabled: !hasActiveStore,
                 children: [
+                    {
+                        label: this.intl.t('storefront.promotions.list.tab-title'),
+                        description: 'Create discounts and promo codes applied at checkout.',
+                        icon: 'tags',
+                        route: 'console.storefront.promotions.index',
+                        keywords: ['discounts', 'coupons', 'promo codes', 'sales', 'deals'],
+                    },
+                    {
+                        label: this.intl.t('storefront.promotions.campaigns.tab-title'),
+                        description: 'Send scheduled notifications to customer segments.',
+                        icon: 'bullhorn',
+                        route: 'console.storefront.promotions.campaigns',
+                        keywords: ['marketing', 'broadcast', 'notifications'],
+                    },
+                    {
+                        label: this.intl.t('storefront.promotions.segments.tab-title'),
+                        description: 'Group customers by their order history for targeting.',
+                        icon: 'users',
+                        route: 'console.storefront.promotions.segments',
+                        keywords: ['audience', 'customers', 'targeting'],
+                    },
                     {
                         label: 'Push Notifications',
                         description: 'Send push notifications to storefront customers.',
diff --git a/addon/controllers/promotions.js b/addon/controllers/promotions.js
index c5f896de..6ab371df 100644
--- a/addon/controllers/promotions.js
+++ b/addon/controllers/promotions.js
@@ -6,6 +6,21 @@ export default class PromotionsController extends Controller {
 
     get tabs() {
         return [
+            {
+                route: 'promotions.index',
+                label: this.intl.t('storefront.promotions.list.tab-title'),
+                icon: 'tags',
+            },
+            {
+                route: 'promotions.campaigns',
+                label: this.intl.t('storefront.promotions.campaigns.tab-title'),
+                icon: 'bullhorn',
+            },
+            {
+                route: 'promotions.segments',
+                label: this.intl.t('storefront.promotions.segments.tab-title'),
+                icon: 'users',
+            },
             {
                 route: 'promotions.push-notifications',
                 label: this.intl.t('storefront.promotions.push-notifications.tab-title'),
diff --git a/addon/controllers/promotions/campaigns.js b/addon/controllers/promotions/campaigns.js
new file mode 100644
index 00000000..d41d7551
--- /dev/null
+++ b/addon/controllers/promotions/campaigns.js
@@ -0,0 +1,196 @@
+import Controller from '@ember/controller';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { debounce } from '@ember/runloop';
+
+export default class PromotionsCampaignsController extends Controller {
+    @service store;
+    @service intl;
+    @service storefront;
+    @service modalsManager;
+    @service notifications;
+    @service crud;
+    @service fetch;
+    @service hostRouter;
+    queryParams = ['query', 'status', 'page'];
+
+    @tracked query;
+    @tracked status;
+    @tracked page = 1;
+
+    get columns() {
+        return [
+            {
+                label: this.intl.t('storefront.promotions.common.name'),
+                valuePath: 'name',
+                width: '22%',
+                cellComponent: 'table/cell/anchor',
+                action: this.editCampaign,
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.common.status'),
+                valuePath: 'status',
+                width: '10%',
+                cellComponent: 'table/cell/status',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.campaigns.audience'),
+                valuePath: 'segment_name',
+                width: '16%',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.campaigns.title-label'),
+                valuePath: 'title',
+                width: '20%',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.campaigns.send-at'),
+                valuePath: 'sendAtFormatted',
+                width: '14%',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.campaigns.targeted'),
+                valuePath: 'targeted',
+                width: '10%',
+                resizable: true,
+            },
+            {
+                label: '',
+                cellComponent: 'table/cell/dropdown',
+                ddButtonText: false,
+                ddButtonIcon: 'ellipsis-h',
+                ddButtonIconPrefix: 'fas',
+                cellClassNames: 'overflow-visible',
+                wrapperClass: 'flex items-center justify-end mx-2',
+                sticky: 'right',
+                width: 60,
+                actions: [
+                    { label: this.intl.t('storefront.promotions.common.edit'), fn: this.editCampaign, permission: 'storefront update campaign' },
+                    { label: this.intl.t('storefront.promotions.campaigns.send-now'), fn: this.sendCampaign, permission: 'storefront send campaign' },
+                    { label: this.intl.t('storefront.promotions.campaigns.cancel-campaign'), fn: this.cancelCampaign, permission: 'storefront cancel campaign' },
+                    { separator: true },
+                    {
+                        label: this.intl.t('storefront.promotions.common.delete'),
+                        fn: this.deleteCampaign,
+                        class: 'text-red-700 hover:text-red-800',
+                        permission: 'storefront delete campaign',
+                    },
+                ],
+            },
+        ];
+    }
+
+    @action search({ target }) {
+        debounce(this, this.setQuery, target.value, 300);
+    }
+
+    setQuery(query) {
+        this.query = query;
+        this.page = 1;
+    }
+
+    @action createCampaign() {
+        const campaign = this.store.createRecord('campaign', {
+            owner_uuid: this.storefront.activeStore.id,
+            owner_type: 'storefront:store',
+            channels: ['push', 'inbox'],
+        });
+
+        return this.editCampaign(campaign, {
+            title: this.intl.t('storefront.promotions.campaigns.new-campaign'),
+            decline: (modal) => {
+                campaign.rollbackAttributes();
+                modal.done();
+            },
+        });
+    }
+
+    @action editCampaign(campaign, options = {}) {
+        this.modalsManager.show('modals/campaign-form', {
+            title: this.intl.t('storefront.promotions.campaigns.edit-campaign'),
+            acceptButtonText: this.intl.t('storefront.promotions.common.save'),
+            acceptButtonIcon: 'save',
+            acceptButtonDisabled: !campaign.isEditable,
+            modalClass: 'modal-lg',
+            campaign,
+            when: campaign.status === 'scheduled' ? 'schedule' : 'draft',
+            confirm: async (modal) => {
+                const when = modal.getOption('when');
+                modal.startLoading();
+
+                campaign.status = when === 'schedule' ? 'scheduled' : 'draft';
+                if (when !== 'schedule') {
+                    campaign.send_at = null;
+                }
+
+                try {
+                    await campaign.save();
+                    if (when === 'now') {
+                        await this.fetch.post(`campaigns/${campaign.id}/send`, {}, { namespace: 'storefront/int/v1' });
+                        this.notifications.success(this.intl.t('storefront.promotions.campaigns.sent-success'));
+                    } else {
+                        this.notifications.success(this.intl.t('storefront.promotions.campaigns.saved-success'));
+                    }
+                    this.hostRouter.refresh();
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+            ...options,
+        });
+    }
+
+    @action sendCampaign(campaign) {
+        this.modalsManager.confirm({
+            title: this.intl.t('storefront.promotions.campaigns.send-now'),
+            body: this.intl.t('storefront.promotions.campaigns.send-now-confirm'),
+            confirm: async (modal) => {
+                modal.startLoading();
+
+                try {
+                    await this.fetch.post(`campaigns/${campaign.id}/send`, {}, { namespace: 'storefront/int/v1' });
+                    this.notifications.success(this.intl.t('storefront.promotions.campaigns.sent-success'));
+                    this.hostRouter.refresh();
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+        });
+    }
+
+    @action cancelCampaign(campaign) {
+        this.modalsManager.confirm({
+            title: this.intl.t('storefront.promotions.campaigns.cancel-campaign'),
+            body: this.intl.t('storefront.promotions.campaigns.cancel-confirm'),
+            confirm: async (modal) => {
+                modal.startLoading();
+
+                try {
+                    await this.fetch.post(`campaigns/${campaign.id}/cancel`, {}, { namespace: 'storefront/int/v1' });
+                    this.notifications.success(this.intl.t('storefront.promotions.campaigns.canceled-success'));
+                    this.hostRouter.refresh();
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+        });
+    }
+
+    @action deleteCampaign(campaign) {
+        this.crud.delete(campaign, {
+            onSuccess: () => this.hostRouter.refresh(),
+        });
+    }
+}
diff --git a/addon/controllers/promotions/index.js b/addon/controllers/promotions/index.js
new file mode 100644
index 00000000..c198354b
--- /dev/null
+++ b/addon/controllers/promotions/index.js
@@ -0,0 +1,226 @@
+import Controller from '@ember/controller';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { debounce } from '@ember/runloop';
+
+export default class PromotionsIndexController extends Controller {
+    @service store;
+    @service intl;
+    @service storefront;
+    @service modalsManager;
+    @service notifications;
+    @service crud;
+    @service fetch;
+    @service hostRouter;
+    queryParams = ['query', 'status', 'page'];
+
+    @tracked query;
+    @tracked status;
+    @tracked page = 1;
+
+    get columns() {
+        return [
+            {
+                label: this.intl.t('storefront.promotions.common.name'),
+                valuePath: 'name',
+                width: '22%',
+                cellComponent: 'table/cell/anchor',
+                action: this.editPromotion,
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.list.type'),
+                valuePath: 'type',
+                width: '14%',
+                cellComponent: 'storefront/promotion/type-cell',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.list.trigger'),
+                valuePath: 'trigger',
+                width: '10%',
+                cellComponent: 'storefront/promotion/trigger-cell',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.common.status'),
+                valuePath: 'status',
+                width: '10%',
+                cellComponent: 'table/cell/status',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.list.runs'),
+                valuePath: 'runsFrom',
+                width: '18%',
+                cellComponent: 'storefront/promotion/runs-cell',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.list.redemptions'),
+                valuePath: 'redemptionsCount',
+                width: '10%',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.list.discount-given'),
+                valuePath: 'discountGiven',
+                width: '12%',
+                cellComponent: 'table/cell/currency',
+                currencyPath: 'currency',
+                resizable: true,
+            },
+            {
+                label: '',
+                cellComponent: 'table/cell/dropdown',
+                ddButtonText: false,
+                ddButtonIcon: 'ellipsis-h',
+                ddButtonIconPrefix: 'fas',
+                ddMenuLabel: this.intl.t('storefront.promotions.list.actions'),
+                cellClassNames: 'overflow-visible',
+                wrapperClass: 'flex items-center justify-end mx-2',
+                sticky: 'right',
+                width: 60,
+                actions: [
+                    { label: this.intl.t('storefront.promotions.common.edit'), fn: this.editPromotion, permission: 'storefront update promotion' },
+                    { label: this.intl.t('storefront.promotions.list.manage-codes'), fn: this.manageCodes, permission: 'storefront generate-codes promotion' },
+                    { label: this.intl.t('storefront.promotions.list.announce'), fn: this.announce, permission: 'storefront announce promotion' },
+                    { separator: true },
+                    { label: this.intl.t('storefront.promotions.list.activate'), fn: (promotion) => this.setStatus(promotion, 'active'), permission: 'storefront update promotion' },
+                    { label: this.intl.t('storefront.promotions.list.pause'), fn: (promotion) => this.setStatus(promotion, 'paused'), permission: 'storefront update promotion' },
+                    { label: this.intl.t('storefront.promotions.list.end'), fn: (promotion) => this.setStatus(promotion, 'ended'), permission: 'storefront update promotion' },
+                    { separator: true },
+                    {
+                        label: this.intl.t('storefront.promotions.common.delete'),
+                        fn: this.deletePromotion,
+                        class: 'text-red-700 hover:text-red-800',
+                        permission: 'storefront delete promotion',
+                    },
+                ],
+            },
+        ];
+    }
+
+    @action search({ target }) {
+        debounce(this, this.setQuery, target.value, 300);
+    }
+
+    setQuery(query) {
+        this.query = query;
+        this.page = 1;
+    }
+
+    @action createPromotion() {
+        const activeStore = this.storefront.activeStore;
+        const promotion = this.store.createRecord('promotion', {
+            owner_uuid: activeStore.id,
+            owner_type: 'storefront:store',
+            currency: activeStore.currency,
+            applies_to: {},
+            bogo_config: { buy_quantity: 1, get_quantity: 1, discount_percent: 100 },
+        });
+
+        return this.editPromotion(promotion, {
+            title: this.intl.t('storefront.promotions.list.new-promotion'),
+            successMessage: this.intl.t('storefront.promotions.list.created-success'),
+            decline: (modal) => {
+                promotion.rollbackAttributes();
+                modal.done();
+            },
+        });
+    }
+
+    @action editPromotion(promotion, options = {}) {
+        this.modalsManager.show('modals/promotion-form', {
+            title: this.intl.t('storefront.promotions.list.edit-promotion'),
+            acceptButtonText: this.intl.t('storefront.promotions.common.save'),
+            acceptButtonIcon: 'save',
+            modalClass: 'modal-lg',
+            promotion,
+            currency: promotion.currency ?? this.storefront.activeStore?.currency,
+            storeId: this.storefront.activeStore?.id,
+            confirm: async (modal) => {
+                modal.startLoading();
+
+                try {
+                    await promotion.save();
+                    this.notifications.success(options.successMessage ?? this.intl.t('storefront.promotions.list.saved-success'));
+                    this.hostRouter.refresh();
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+            ...options,
+        });
+    }
+
+    @action async setStatus(promotion, status) {
+        promotion.status = status;
+
+        try {
+            await promotion.save();
+            this.notifications.success(this.intl.t('storefront.promotions.list.status-updated'));
+        } catch (error) {
+            promotion.rollbackAttributes();
+            this.notifications.serverError(error);
+        }
+    }
+
+    @action manageCodes(promotion) {
+        this.modalsManager.show('modals/promotion-codes', {
+            title: this.intl.t('storefront.promotions.codes.title', { name: promotion.name }),
+            hideAcceptButton: true,
+            declineButtonText: this.intl.t('storefront.promotions.common.done'),
+            modalClass: 'modal-lg',
+            promotion,
+        });
+    }
+
+    @action announce(promotion) {
+        this.modalsManager.show('modals/promotion-announce', {
+            title: this.intl.t('storefront.promotions.announce.title', { name: promotion.name }),
+            acceptButtonText: this.intl.t('storefront.promotions.list.announce'),
+            acceptButtonIcon: 'bullhorn',
+            promotion,
+            announcement: {
+                title: promotion.name,
+                body: promotion.description,
+                segment: null,
+                channels: ['push', 'inbox'],
+                send_at: null,
+            },
+            confirm: async (modal) => {
+                const { announcement } = modal.getOptions(['announcement']);
+                modal.startLoading();
+
+                try {
+                    await this.fetch.post(
+                        `promotions/${promotion.id}/announce`,
+                        {
+                            title: announcement.title,
+                            body: announcement.body,
+                            segment: announcement.segment?.id,
+                            channels: announcement.channels,
+                            send_at: announcement.send_at,
+                        },
+                        { namespace: 'storefront/int/v1' }
+                    );
+                    this.notifications.success(this.intl.t('storefront.promotions.announce.success'));
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+        });
+    }
+
+    @action deletePromotion(promotion) {
+        this.crud.delete(promotion, {
+            onSuccess: () => this.hostRouter.refresh(),
+        });
+    }
+}
diff --git a/addon/controllers/promotions/segments.js b/addon/controllers/promotions/segments.js
new file mode 100644
index 00000000..d9789e60
--- /dev/null
+++ b/addon/controllers/promotions/segments.js
@@ -0,0 +1,119 @@
+import Controller from '@ember/controller';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { debounce } from '@ember/runloop';
+
+export default class PromotionsSegmentsController extends Controller {
+    @service store;
+    @service intl;
+    @service storefront;
+    @service modalsManager;
+    @service notifications;
+    @service crud;
+    @service hostRouter;
+    queryParams = ['query', 'page'];
+
+    @tracked query;
+    @tracked page = 1;
+
+    get columns() {
+        return [
+            {
+                label: this.intl.t('storefront.promotions.common.name'),
+                valuePath: 'name',
+                width: '30%',
+                cellComponent: 'table/cell/anchor',
+                action: this.editSegment,
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.common.description'),
+                valuePath: 'description',
+                width: '40%',
+                resizable: true,
+            },
+            {
+                label: this.intl.t('storefront.promotions.segments.rules'),
+                valuePath: 'ruleCount',
+                width: '15%',
+                resizable: true,
+            },
+            {
+                label: '',
+                cellComponent: 'table/cell/dropdown',
+                ddButtonText: false,
+                ddButtonIcon: 'ellipsis-h',
+                ddButtonIconPrefix: 'fas',
+                cellClassNames: 'overflow-visible',
+                wrapperClass: 'flex items-center justify-end mx-2',
+                sticky: 'right',
+                width: 60,
+                actions: [
+                    { label: this.intl.t('storefront.promotions.common.edit'), fn: this.editSegment, permission: 'storefront update customer-segment' },
+                    {
+                        label: this.intl.t('storefront.promotions.common.delete'),
+                        fn: this.deleteSegment,
+                        class: 'text-red-700 hover:text-red-800',
+                        permission: 'storefront delete customer-segment',
+                    },
+                ],
+            },
+        ];
+    }
+
+    @action search({ target }) {
+        debounce(this, this.setQuery, target.value, 300);
+    }
+
+    setQuery(query) {
+        this.query = query;
+        this.page = 1;
+    }
+
+    @action createSegment() {
+        const segment = this.store.createRecord('customer-segment', {
+            owner_uuid: this.storefront.activeStore.id,
+            owner_type: 'storefront:store',
+            rules: {},
+        });
+
+        return this.editSegment(segment, {
+            title: this.intl.t('storefront.promotions.segments.new-segment'),
+            decline: (modal) => {
+                segment.rollbackAttributes();
+                modal.done();
+            },
+        });
+    }
+
+    @action editSegment(segment, options = {}) {
+        this.modalsManager.show('modals/customer-segment-form', {
+            title: this.intl.t('storefront.promotions.segments.edit-segment'),
+            acceptButtonText: this.intl.t('storefront.promotions.common.save'),
+            acceptButtonIcon: 'save',
+            segment,
+            currency: this.storefront.activeStore?.currency,
+            confirm: async (modal) => {
+                modal.startLoading();
+
+                try {
+                    await segment.save();
+                    this.notifications.success(this.intl.t('storefront.promotions.segments.saved-success'));
+                    this.hostRouter.refresh();
+                    modal.done();
+                } catch (error) {
+                    this.notifications.serverError(error);
+                    modal.stopLoading();
+                }
+            },
+            ...options,
+        });
+    }
+
+    @action deleteSegment(segment) {
+        this.crud.delete(segment, {
+            onSuccess: () => this.hostRouter.refresh(),
+        });
+    }
+}
diff --git a/addon/models/campaign.js b/addon/models/campaign.js
new file mode 100644
index 00000000..7e464fbc
--- /dev/null
+++ b/addon/models/campaign.js
@@ -0,0 +1,50 @@
+import Model, { attr } from '@ember-data/model';
+import { format, isValid } from 'date-fns';
+
+export default class CampaignModel extends Model {
+    /** @ids */
+    @attr('string') public_id;
+    @attr('string') owner_uuid;
+    @attr('string') owner_type;
+    @attr('string') segment_uuid;
+    @attr('string') promotion_uuid;
+    @attr('string') image_uuid;
+
+    /** @attributes */
+    @attr('string') name;
+    @attr('string', { defaultValue: 'draft' }) status;
+    @attr('raw', { defaultValue: () => ['push', 'inbox'] }) channels;
+    @attr('raw') recipients;
+    @attr('string') title;
+    @attr('string') body;
+    @attr('string') image_url;
+    @attr('raw') action;
+    @attr('string') segment_name;
+    @attr('string') promotion_name;
+    @attr('date') send_at;
+    @attr('date') started_at;
+    @attr('date') sent_at;
+    @attr('raw') stats;
+    @attr('raw') meta;
+
+    /** @dates */
+    @attr('date') created_at;
+    @attr('date') updated_at;
+
+    /** @computed */
+    get isEditable() {
+        return ['draft', 'scheduled'].includes(this.status);
+    }
+
+    get targeted() {
+        return this.stats?.targeted ?? null;
+    }
+
+    get sendAtFormatted() {
+        return this.send_at && isValid(this.send_at) ? format(this.send_at, 'PP p') : null;
+    }
+
+    get sentAtFormatted() {
+        return this.sent_at && isValid(this.sent_at) ? format(this.sent_at, 'PP p') : null;
+    }
+}
diff --git a/addon/models/customer-segment.js b/addon/models/customer-segment.js
new file mode 100644
index 00000000..26497e4f
--- /dev/null
+++ b/addon/models/customer-segment.js
@@ -0,0 +1,23 @@
+import Model, { attr } from '@ember-data/model';
+
+export default class CustomerSegmentModel extends Model {
+    /** @ids */
+    @attr('string') public_id;
+    @attr('string') owner_uuid;
+    @attr('string') owner_type;
+
+    /** @attributes */
+    @attr('string') name;
+    @attr('string') description;
+    @attr('raw') rules;
+    @attr('raw') meta;
+
+    /** @dates */
+    @attr('date') created_at;
+    @attr('date') updated_at;
+
+    /** @computed */
+    get ruleCount() {
+        return Object.values(this.rules ?? {}).filter((value) => value !== null && value !== undefined && value !== '' && !(Array.isArray(value) && value.length === 0)).length;
+    }
+}
diff --git a/addon/models/promotion-code.js b/addon/models/promotion-code.js
new file mode 100644
index 00000000..7445f487
--- /dev/null
+++ b/addon/models/promotion-code.js
@@ -0,0 +1,19 @@
+import Model, { attr } from '@ember-data/model';
+
+export default class PromotionCodeModel extends Model {
+    /** @ids */
+    @attr('string') public_id;
+    @attr('string') promotion_uuid;
+    @attr('string') customer_uuid;
+
+    /** @attributes */
+    @attr('string') code;
+    @attr('string', { defaultValue: 'active' }) status;
+    @attr('number') usage_limit;
+    @attr('number') times_used;
+    @attr('date') expires_at;
+
+    /** @dates */
+    @attr('date') created_at;
+    @attr('date') updated_at;
+}
diff --git a/addon/models/promotion.js b/addon/models/promotion.js
new file mode 100644
index 00000000..8617c20b
--- /dev/null
+++ b/addon/models/promotion.js
@@ -0,0 +1,69 @@
+import Model, { attr } from '@ember-data/model';
+import { format, formatDistanceToNow, isValid } from 'date-fns';
+
+export default class PromotionModel extends Model {
+    /** @ids */
+    @attr('string') public_id;
+    @attr('string') company_uuid;
+    @attr('string') owner_uuid;
+    @attr('string') owner_type;
+    @attr('string') image_uuid;
+
+    /** @attributes */
+    @attr('string') name;
+    @attr('string') description;
+    @attr('string', { defaultValue: 'draft' }) status;
+    @attr('string', { defaultValue: 'automatic' }) trigger;
+    @attr('string', { defaultValue: 'percentage' }) type;
+    @attr('number') value;
+    @attr('number') max_discount_amount;
+    @attr('string') currency;
+    @attr('number') min_subtotal;
+    @attr('number') min_items;
+    @attr('raw') applies_to;
+    @attr('raw') bogo_config;
+    @attr('boolean', { defaultValue: false }) first_order_only;
+    @attr('number') usage_limit;
+    @attr('number') usage_limit_per_customer;
+    @attr('number') budget_amount;
+    @attr('boolean', { defaultValue: false }) stackable;
+    @attr('number', { defaultValue: 0 }) priority;
+    @attr('boolean', { defaultValue: true }) is_public;
+    @attr('date') starts_at;
+    @attr('date') ends_at;
+    @attr('raw') schedule;
+    @attr('string') timezone;
+    @attr('string') image_url;
+    @attr('raw') translations;
+    @attr('raw') stats;
+    @attr('raw') meta;
+
+    /** @dates */
+    @attr('date') created_at;
+    @attr('date') updated_at;
+
+    /** @computed */
+    get isCodeBased() {
+        return this.trigger === 'code';
+    }
+
+    get redemptionsCount() {
+        return this.stats?.redemptions ?? 0;
+    }
+
+    get discountGiven() {
+        return this.stats?.discount_given ?? 0;
+    }
+
+    get runsFrom() {
+        return this.starts_at && isValid(this.starts_at) ? format(this.starts_at, 'PP p') : null;
+    }
+
+    get runsUntil() {
+        return this.ends_at && isValid(this.ends_at) ? format(this.ends_at, 'PP p') : null;
+    }
+
+    get updatedAgo() {
+        return this.updated_at && isValid(this.updated_at) ? formatDistanceToNow(this.updated_at) : null;
+    }
+}
diff --git a/addon/routes.js b/addon/routes.js
index 05274a5e..d558ea6f 100644
--- a/addon/routes.js
+++ b/addon/routes.js
@@ -45,7 +45,10 @@ export default buildRoutes(function () {
         this.route('index', { path: '/' }, function () {});
     });
     this.route('promotions', function () {
-        this.route('push-notifications', { path: '/' });
+        this.route('index', { path: '/' });
+        this.route('campaigns');
+        this.route('segments');
+        this.route('push-notifications');
     });
     this.route('coupons');
     this.route('broadcast');
diff --git a/addon/routes/promotions/campaigns.js b/addon/routes/promotions/campaigns.js
new file mode 100644
index 00000000..0d50dd1d
--- /dev/null
+++ b/addon/routes/promotions/campaigns.js
@@ -0,0 +1,28 @@
+import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
+
+export default class PromotionsCampaignsRoute extends Route {
+    @service store;
+    @service storefront;
+    @service intl;
+    @service abilities;
+    @service hostRouter;
+    @service notifications;
+
+    queryParams = {
+        query: { refreshModel: true },
+        status: { refreshModel: true },
+        page: { refreshModel: true },
+    };
+
+    beforeModel() {
+        if (this.abilities.cannot('storefront list campaign')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.storefront');
+        }
+    }
+
+    model(params) {
+        return this.store.query('campaign', { ...params, owner: this.storefront.getActiveStore('id'), sort: '-created_at' });
+    }
+}
diff --git a/addon/routes/promotions/index.js b/addon/routes/promotions/index.js
new file mode 100644
index 00000000..c41af2db
--- /dev/null
+++ b/addon/routes/promotions/index.js
@@ -0,0 +1,28 @@
+import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
+
+export default class PromotionsIndexRoute extends Route {
+    @service store;
+    @service storefront;
+    @service intl;
+    @service abilities;
+    @service hostRouter;
+    @service notifications;
+
+    queryParams = {
+        query: { refreshModel: true },
+        status: { refreshModel: true },
+        page: { refreshModel: true },
+    };
+
+    beforeModel() {
+        if (this.abilities.cannot('storefront list promotion')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.storefront');
+        }
+    }
+
+    model(params) {
+        return this.store.query('promotion', { ...params, owner: this.storefront.getActiveStore('id'), sort: '-created_at' });
+    }
+}
diff --git a/addon/routes/promotions/segments.js b/addon/routes/promotions/segments.js
new file mode 100644
index 00000000..3e67aae8
--- /dev/null
+++ b/addon/routes/promotions/segments.js
@@ -0,0 +1,27 @@
+import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
+
+export default class PromotionsSegmentsRoute extends Route {
+    @service store;
+    @service storefront;
+    @service intl;
+    @service abilities;
+    @service hostRouter;
+    @service notifications;
+
+    queryParams = {
+        query: { refreshModel: true },
+        page: { refreshModel: true },
+    };
+
+    beforeModel() {
+        if (this.abilities.cannot('storefront list customer-segment')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.storefront');
+        }
+    }
+
+    model(params) {
+        return this.store.query('customer-segment', { ...params, owner: this.storefront.getActiveStore('id'), sort: '-created_at' });
+    }
+}
diff --git a/addon/templates/promotions/campaigns.hbs b/addon/templates/promotions/campaigns.hbs
new file mode 100644
index 00000000..7c8d521e
--- /dev/null
+++ b/addon/templates/promotions/campaigns.hbs
@@ -0,0 +1,21 @@
+<Layout::Section::Header @title={{t "storefront.promotions.campaigns.header"}} @searchQuery={{this.query}} @onSearch={{this.search}}>
+    <Button @type="primary" @icon="plus" @text={{t "storefront.promotions.campaigns.new-campaign"}} @onClick={{this.createCampaign}} @permission="storefront create campaign" />
+</Layout::Section::Header>
+
+<Layout::Section::Body>
+    {{#if @model.length}}
+        <Table
+            @wrapperClass="overscroll-y-none"
+            @rows={{@model}}
+            @columns={{this.columns}}
+            @selectable={{false}}
+            @canSelectAll={{false}}
+            @pagination={{true}}
+            @paginationMeta={{@model.meta}}
+            @page={{this.page}}
+            @onPageChange={{fn (mut this.page)}}
+        />
+    {{else}}
+        <div class="p-8 text-center text-sm text-gray-500 dark:text-gray-400">{{t "storefront.promotions.campaigns.empty"}}</div>
+    {{/if}}
+</Layout::Section::Body>
diff --git a/addon/templates/promotions/index.hbs b/addon/templates/promotions/index.hbs
new file mode 100644
index 00000000..2a502eda
--- /dev/null
+++ b/addon/templates/promotions/index.hbs
@@ -0,0 +1,21 @@
+<Layout::Section::Header @title={{t "storefront.promotions.list.header"}} @searchQuery={{this.query}} @onSearch={{this.search}}>
+    <Button @type="primary" @icon="plus" @text={{t "storefront.promotions.list.new-promotion"}} @onClick={{this.createPromotion}} @permission="storefront create promotion" />
+</Layout::Section::Header>
+
+<Layout::Section::Body>
+    {{#if @model.length}}
+        <Table
+            @wrapperClass="overscroll-y-none"
+            @rows={{@model}}
+            @columns={{this.columns}}
+            @selectable={{false}}
+            @canSelectAll={{false}}
+            @pagination={{true}}
+            @paginationMeta={{@model.meta}}
+            @page={{this.page}}
+            @onPageChange={{fn (mut this.page)}}
+        />
+    {{else}}
+        <div class="p-8 text-center text-sm text-gray-500 dark:text-gray-400">{{t "storefront.promotions.list.empty"}}</div>
+    {{/if}}
+</Layout::Section::Body>
diff --git a/addon/templates/promotions/segments.hbs b/addon/templates/promotions/segments.hbs
new file mode 100644
index 00000000..c3fe28c7
--- /dev/null
+++ b/addon/templates/promotions/segments.hbs
@@ -0,0 +1,21 @@
+<Layout::Section::Header @title={{t "storefront.promotions.segments.header"}} @searchQuery={{this.query}} @onSearch={{this.search}}>
+    <Button @type="primary" @icon="plus" @text={{t "storefront.promotions.segments.new-segment"}} @onClick={{this.createSegment}} @permission="storefront create customer-segment" />
+</Layout::Section::Header>
+
+<Layout::Section::Body>
+    {{#if @model.length}}
+        <Table
+            @wrapperClass="overscroll-y-none"
+            @rows={{@model}}
+            @columns={{this.columns}}
+            @selectable={{false}}
+            @canSelectAll={{false}}
+            @pagination={{true}}
+            @paginationMeta={{@model.meta}}
+            @page={{this.page}}
+            @onPageChange={{fn (mut this.page)}}
+        />
+    {{else}}
+        <div class="p-8 text-center text-sm text-gray-500 dark:text-gray-400">{{t "storefront.promotions.segments.empty"}}</div>
+    {{/if}}
+</Layout::Section::Body>
diff --git a/app/adapters/campaign.js b/app/adapters/campaign.js
new file mode 100644
index 00000000..bbba6e09
--- /dev/null
+++ b/app/adapters/campaign.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/adapters/campaign';
diff --git a/app/adapters/customer-segment.js b/app/adapters/customer-segment.js
new file mode 100644
index 00000000..53423d97
--- /dev/null
+++ b/app/adapters/customer-segment.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/adapters/customer-segment';
diff --git a/app/adapters/promotion-code.js b/app/adapters/promotion-code.js
new file mode 100644
index 00000000..2f00dba3
--- /dev/null
+++ b/app/adapters/promotion-code.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/adapters/promotion-code';
diff --git a/app/adapters/promotion.js b/app/adapters/promotion.js
new file mode 100644
index 00000000..f0fa631b
--- /dev/null
+++ b/app/adapters/promotion.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/adapters/promotion';
diff --git a/app/components/modals/campaign-form.js b/app/components/modals/campaign-form.js
new file mode 100644
index 00000000..775cf40f
--- /dev/null
+++ b/app/components/modals/campaign-form.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/campaign-form';
diff --git a/app/components/modals/customer-segment-form.js b/app/components/modals/customer-segment-form.js
new file mode 100644
index 00000000..46e1cf7b
--- /dev/null
+++ b/app/components/modals/customer-segment-form.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/customer-segment-form';
diff --git a/app/components/modals/promotion-announce.js b/app/components/modals/promotion-announce.js
new file mode 100644
index 00000000..a7c96876
--- /dev/null
+++ b/app/components/modals/promotion-announce.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/promotion-announce';
diff --git a/app/components/modals/promotion-codes.js b/app/components/modals/promotion-codes.js
new file mode 100644
index 00000000..65f69766
--- /dev/null
+++ b/app/components/modals/promotion-codes.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/promotion-codes';
diff --git a/app/components/modals/promotion-form.js b/app/components/modals/promotion-form.js
new file mode 100644
index 00000000..9da05a09
--- /dev/null
+++ b/app/components/modals/promotion-form.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/modals/promotion-form';
diff --git a/app/components/storefront/promotion/runs-cell.js b/app/components/storefront/promotion/runs-cell.js
new file mode 100644
index 00000000..ca25d189
--- /dev/null
+++ b/app/components/storefront/promotion/runs-cell.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/storefront/promotion/runs-cell';
diff --git a/app/components/storefront/promotion/trigger-cell.js b/app/components/storefront/promotion/trigger-cell.js
new file mode 100644
index 00000000..b3addc19
--- /dev/null
+++ b/app/components/storefront/promotion/trigger-cell.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/storefront/promotion/trigger-cell';
diff --git a/app/components/storefront/promotion/type-cell.js b/app/components/storefront/promotion/type-cell.js
new file mode 100644
index 00000000..02432544
--- /dev/null
+++ b/app/components/storefront/promotion/type-cell.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/components/storefront/promotion/type-cell';
diff --git a/app/controllers/promotions/campaigns.js b/app/controllers/promotions/campaigns.js
new file mode 100644
index 00000000..4ce23ac4
--- /dev/null
+++ b/app/controllers/promotions/campaigns.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/controllers/promotions/campaigns';
diff --git a/app/controllers/promotions/index.js b/app/controllers/promotions/index.js
new file mode 100644
index 00000000..c6732540
--- /dev/null
+++ b/app/controllers/promotions/index.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/controllers/promotions/index';
diff --git a/app/controllers/promotions/segments.js b/app/controllers/promotions/segments.js
new file mode 100644
index 00000000..066207ba
--- /dev/null
+++ b/app/controllers/promotions/segments.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/controllers/promotions/segments';
diff --git a/app/models/campaign.js b/app/models/campaign.js
new file mode 100644
index 00000000..6b519835
--- /dev/null
+++ b/app/models/campaign.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/models/campaign';
diff --git a/app/models/customer-segment.js b/app/models/customer-segment.js
new file mode 100644
index 00000000..397c5860
--- /dev/null
+++ b/app/models/customer-segment.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/models/customer-segment';
diff --git a/app/models/promotion-code.js b/app/models/promotion-code.js
new file mode 100644
index 00000000..323dc077
--- /dev/null
+++ b/app/models/promotion-code.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/models/promotion-code';
diff --git a/app/models/promotion.js b/app/models/promotion.js
new file mode 100644
index 00000000..9b181e55
--- /dev/null
+++ b/app/models/promotion.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/models/promotion';
diff --git a/app/routes/promotions/campaigns.js b/app/routes/promotions/campaigns.js
new file mode 100644
index 00000000..f5afc1ce
--- /dev/null
+++ b/app/routes/promotions/campaigns.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/routes/promotions/campaigns';
diff --git a/app/routes/promotions/index.js b/app/routes/promotions/index.js
new file mode 100644
index 00000000..de18bb76
--- /dev/null
+++ b/app/routes/promotions/index.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/routes/promotions/index';
diff --git a/app/routes/promotions/segments.js b/app/routes/promotions/segments.js
new file mode 100644
index 00000000..59fc6234
--- /dev/null
+++ b/app/routes/promotions/segments.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/storefront-engine/routes/promotions/segments';
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index 353e68b9..587a7836 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -703,3 +703,165 @@ storefront:
       validation-customers-required: Please select at least one customer to send the notification to
       notification-sent-success: Push notification sent successfully to selected customers
       notification-sent-error: Failed to send push notification. Please try again.
+    common:
+      new: New
+      edit: Edit
+      delete: Delete
+      save: Save
+      cancel: Cancel
+      name: Name
+      description: Description
+      status: Status
+      created: Created
+      updated: Updated
+      none: None
+      all-customers: All customers
+      done: Done
+    statuses:
+      draft: Draft
+      active: Active
+      paused: Paused
+      ended: Ended
+      scheduled: Scheduled
+      sending: Sending
+      sent: Sent
+      canceled: Canceled
+    list:
+      tab-title: Promotions
+      header: Promotions
+      new-promotion: New promotion
+      edit-promotion: Edit promotion
+      type: Type
+      trigger: Trigger
+      runs: Runs
+      redemptions: Redemptions
+      discount-given: Discount given
+      actions: Promotion actions
+      manage-codes: Manage codes
+      announce: Announce to customers
+      activate: Activate
+      pause: Pause
+      end: End promotion
+      created-success: Promotion created.
+      saved-success: Promotion saved.
+      status-updated: Promotion status updated.
+      empty: No promotions yet. Create one to offer discounts at checkout.
+    types:
+      percentage: Percentage off
+      fixed_amount: Amount off
+      free_delivery: Free delivery
+      bogo: Buy X get Y
+    triggers:
+      automatic: Automatic
+      code: Promo code
+    form:
+      basics: Basics
+      name-help: Shown to customers at checkout and in the app.
+      description-help: Optional details shown with the deal in the app.
+      type-help: How the discount is calculated.
+      trigger-help: Automatic promotions apply to every eligible cart; code promotions need a promo code.
+      percent-off: Percent off
+      amount-off: Amount off
+      buy-quantity: Buy quantity
+      get-quantity: Get quantity
+      get-discount-percent: Discount on the free items (%)
+      bogo-help: For every group of "buy" + "get" eligible items, the cheapest "get" items are discounted.
+      schedule: Schedule
+      starts-at: Starts at
+      ends-at: Ends at
+      schedule-help: Leave empty to run until paused.
+      conditions: Conditions
+      min-subtotal: Minimum spend
+      min-items: Minimum items
+      first-order-only: First order only
+      first-order-only-help: Only customers who have never ordered can use it.
+      targeting: Targeting
+      targeting-help: Limit the discount to these products or categories. Leave empty for the whole cart.
+      products: Products
+      categories: Categories
+      exclude-products: Excluded products
+      limits: Limits
+      usage-limit: Total uses
+      usage-limit-per-customer: Uses per customer
+      budget-amount: Total budget
+      max-discount-amount: Maximum discount per order
+      limits-help: Leave empty for no limit.
+      stacking: Stacking and visibility
+      stackable: Can combine with other promotions
+      stackable-help: Otherwise it applies alone, when it gives the customer the bigger discount.
+      priority: Priority
+      priority-help: Higher priority promotions apply first.
+      is-public: Show in the app's deals
+    codes:
+      title: Promo codes for {name}
+      generate: Generate codes
+      count: How many
+      prefix: Prefix
+      length: Code length
+      usage-limit: Uses per code
+      usage-limit-help: 1 for single-use codes. Leave empty for unlimited.
+      specific-code: Or create a specific code
+      specific-code-placeholder: e.g. SUMMER25
+      code: Code
+      used: Used
+      expires: Expires
+      disable: Disable
+      enable: Enable
+      generated-success: Codes generated.
+      empty: No codes yet.
+    announce:
+      title: Announce {name}
+      help: Send a notification about this promotion to your customers. It is sent when the promotion starts, or right away if it already has.
+      segment: Audience
+      segment-placeholder: All customers
+      message-title: Notification title
+      message-body: Notification message
+      send-at: Send at (optional)
+      success: Announcement scheduled.
+    campaigns:
+      tab-title: Campaigns
+      header: Campaigns
+      new-campaign: New campaign
+      edit-campaign: Edit campaign
+      audience: Audience
+      channels: Channels
+      channel-push: Push notification
+      channel-inbox: In-app inbox
+      send-at: Send at
+      sent-at: Sent
+      targeted: Customers reached
+      send-now: Send now
+      send-now-confirm: Send this campaign to its audience now?
+      cancel-campaign: Cancel campaign
+      cancel-confirm: Cancel this campaign? It will not be sent.
+      audience-count: This campaign will reach {count} customers.
+      title-label: Notification title
+      body-label: Notification message
+      promotion: Linked promotion
+      promotion-help: Tapping the notification opens this promotion.
+      link-url: Or link to a URL
+      when: When to send
+      when-draft: Save as draft
+      when-now: Send now
+      when-schedule: Schedule
+      saved-success: Campaign saved.
+      sent-success: Campaign sent.
+      canceled-success: Campaign canceled.
+      empty: No campaigns yet.
+    segments:
+      tab-title: Segments
+      header: Customer segments
+      new-segment: New segment
+      edit-segment: Edit segment
+      rules: Rules
+      rules-help: Customers must match every rule you fill in.
+      min-orders: At least this many orders
+      max-orders: At most this many orders
+      ordered-within-days: Ordered in the last (days)
+      not-ordered-within-days: Has not ordered in the last (days)
+      joined-within-days: Joined in the last (days)
+      min-spent: Spent at least
+      has-push-device: Can receive push notifications
+      matching: '{count} matching customers'
+      saved-success: Segment saved.
+      empty: No segments yet. Segments let you target campaigns at groups of customers.

From b6738c043ad47420a3a91c96949bfff8a5f98a08 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 18:29:59 +0800
Subject: [PATCH 8/8] fix: allow a promotion end date without a start date

after:starts_at failed validation whenever starts_at was empty.
---
 server/src/Http/Requests/PromotionRequest.php        |  7 ++++++-
 .../tests/Unit/Promotions/PromotionEndpointsTest.php | 12 ++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/server/src/Http/Requests/PromotionRequest.php b/server/src/Http/Requests/PromotionRequest.php
index 93db0c97..040017a0 100644
--- a/server/src/Http/Requests/PromotionRequest.php
+++ b/server/src/Http/Requests/PromotionRequest.php
@@ -47,7 +47,12 @@ public function rules()
             'priority'                     => ['sometimes', 'integer'],
             'is_public'                    => ['sometimes', 'boolean'],
             'starts_at'                    => ['nullable', 'date'],
-            'ends_at'                      => ['nullable', 'date', 'after:starts_at'],
+            'ends_at'                      => ['nullable', 'date', function ($attribute, $value, $fail) {
+                $startsAt = $this->input('promotion.starts_at', $this->input('starts_at'));
+                if ($value && $startsAt && strtotime($value) <= strtotime($startsAt)) {
+                    $fail('The end date must be after the start date.');
+                }
+            }],
             'schedule'                     => ['nullable', 'array'],
             'schedule.*.days'              => ['sometimes', 'array'],
             'schedule.*.days.*'            => ['integer', 'between:1,7'],
diff --git a/server/tests/Unit/Promotions/PromotionEndpointsTest.php b/server/tests/Unit/Promotions/PromotionEndpointsTest.php
index 5ea1db72..57556924 100644
--- a/server/tests/Unit/Promotions/PromotionEndpointsTest.php
+++ b/server/tests/Unit/Promotions/PromotionEndpointsTest.php
@@ -199,6 +199,18 @@ protected function generateCode(int $length, string $prefix): string
         $failures[] = $message;
     });
 
+    $endsAt       = PromotionRequest::createFrom(promotionRequest(['promotion' => ['starts_at' => '2026-10-01 00:00:00']], 'POST'))->rules()['ends_at'][2];
+    $dateFailures = [];
+    $collect      = function ($message) use (&$dateFailures) {
+        $dateFailures[] = $message;
+    };
+    $endsAt('ends_at', '2026-11-01 00:00:00', $collect);
+    $endsAt('ends_at', '2026-09-01 00:00:00', $collect);
+    $endsAt('ends_at', null, $collect);
+    PromotionRequest::createFrom(promotionRequest([], 'POST'))->rules()['ends_at'][2]('ends_at', '2026-09-01 00:00:00', $collect);
+
+    expect($dateFailures)->toBe(['The end date must be after the start date.']);
+
     expect($rules['name'][0])->toBe('required')
         ->and($rules['type'][1])->toBe('in:percentage,fixed_amount,free_delivery,bogo')
         ->and($rules['value'][3])->toBe('required_if:type,percentage,fixed_amount')