TrackShip Documentation

Overview

TrackShip lets you track local deliveries in real time from your WordPress dashboard. When a driver starts a delivery, their GPS is captured, a customer ETA is calculated using the Haversine formula, and a live tracking page is made available to the customer — no external API keys required.

The plugin works with WooCommerce orders or in its own standalone order mode for businesses that don't use WooCommerce.

Tier breakdown:

• Lite — GPS ETA, progress bar, countdown, email notifications, WooCommerce + standalone, PWA, live map, real-time GPS, push notifications
• Plus — Everything in Lite + driver roster & assignment, route notes, delivery zones
• Pro — Everything in Plus + SMS notifications (Twilio), delivery analytics dashboard, white-label tracking page

Installation

1. Download trackship.zip from your Boulley Technology account.
2. Go to Plugins > Add New > Upload Plugin, select the ZIP, and activate.
3. TrackShip appears as a top-level menu item in your WordPress admin sidebar.
4. A Track Your Delivery page is auto-created with the [trackship_track] shortcode — customers are linked here from notification emails.

Settings

All settings are in TrackShip > Settings.

Delivery Settings

• Average Speed (km/h) — Used to calculate ETA from driver GPS to customer address. Default: 40 km/h.
• ETA Buffer (minutes) — Extra minutes added to every ETA for traffic and stops. Default: 5 min.
• Auto-Complete (minutes) — Auto-marks orders as Delivered this many minutes after the ETA has passed. Set to 0 to disable.

Email Notifications

• Sender Name — Name shown as the email sender. Defaults to your site name.
• Individual toggles for Order Confirmed, Out for Delivery, and Delivered emails.

PWA Mobile App

• App Name — Name shown when the customer installs the PWA to their home screen.
• Theme Color — Color used in the PWA chrome and splash screen.

Starting a Delivery

On any WooCommerce order edit screen, find the TrackShip — Delivery Tracking meta box in the sidebar.

1. Select a Driver from the dropdown (Plus — populated from your driver roster) or type a driver name manually (Lite).
2. If you have a Plus license, optionally enter Route Notes (e.g. "Ring doorbell, leave at side door").
3. Click Start Delivery. The browser requests the driver's GPS location.
4. TrackShip geocodes the customer's shipping address via OpenStreetMap Nominatim, calculates the ETA, saves all tracking data, and sends the "Out for Delivery" email to the customer with their tracking link.
5. If you have a Plus license and Delivery Zones are configured, a zone warning appears in the meta box if the driver's GPS is outside the service area.
6. If you have a Pro license and SMS notifications are enabled, the customer is automatically texted via Twilio with the ETA and tracking link.

Once delivery is started, the meta box shows the driver name, ETA, and a Mark Delivered button.

Customer Tracking Page

The auto-created Track Your Delivery page uses the shortcode [trackship_track]. Customers visit this page via the link in their "Out for Delivery" email.

The tracking page shows:

• Order number and current status badge
• Three-step status timeline: Order Confirmed → Out for Delivery → Delivered
• Driver name (if set) and route notes (Plus+)
• Animated progress bar with car icon
• ETA time and live countdown timer
• Live OpenStreetMap with driver position (Lite+)

The page auto-refreshes tracking data every 30 seconds. If GPS is unavailable, only the progress bar and ETA are shown — the map is hidden gracefully.

Customers can also look up their order manually by entering their order number in the form if they visit the tracking page without the direct link.

Live Map Lite

With a Lite or higher license, the customer tracking page shows an interactive OpenStreetMap with the driver's current position and the delivery address pinned. The map updates every 30 seconds as the driver's GPS position is refreshed from the driver's device.

No Google Maps API key is needed — the map is powered entirely by OpenStreetMap (free, no usage limits).

Driver Roster Plus

Plus licenses unlock a saved driver roster. Instead of typing a driver name each time you start a delivery, you select from a dropdown populated with your saved drivers.

Manage your roster in TrackShip > Settings > Driver Roster:

• Click Add Driver, enter a name and optional phone number, and save.
• Drivers appear in the table immediately via AJAX — no page reload needed.
• Click Delete next to a driver to remove them from the roster.

When starting a delivery, the meta box renders a dropdown of your saved drivers. Selecting a driver auto-fills the driver's phone number (used by SMS notifications if Pro is active). The selected driver name is saved to the order and shown on the customer tracking page.

Route Notes Plus

Route notes let you pass special delivery instructions from the dispatcher to the customer's tracking page. When starting a delivery, a Route Notes field appears in the meta box.

Examples: "Ring doorbell", "Leave at side entrance", "Call customer on arrival".

Notes are shown on the customer tracking page below the driver name, with a blue left-border callout. They are only visible when a delivery is in progress. Notes are stored in order meta (_trackship_route_notes) and are also returned in the ajax_get_tracking response so the live-update JS can display them without a page refresh.

Delivery Zones Plus

Delivery zones let you define a radius-based service area for your business. When a driver starts a delivery and their GPS position is outside the configured zone radius, a warning is shown in the admin meta box.

Configure zones in TrackShip > Settings > Delivery Zones:

• Enable Zone Check — Toggle the zone warning on or off.
• Zone Center (address) — Reference label for your zone center (not geocoded — enter lat/lng below).
• Zone Center Latitude / Longitude — Decimal coordinates for the center of your service area.
• Zone Radius (km) — Maximum distance from the center in kilometres.

The zone check uses the Haversine formula against the driver's GPS coordinates at the moment "Start Delivery" is clicked. It is advisory only — the delivery still proceeds. The warning appears in the meta box response message as: "Warning: driver is X.X km from the delivery zone center (zone radius: Y km)."

SMS Notifications Pro

Pro licenses can automatically text customers when a delivery starts. Messages are sent via the Twilio REST API — no SDK or Composer dependency required.

Setup

1. Create a Twilio account at twilio.com and purchase a phone number.
2. In the Twilio console, copy your Account SID and generate an Auth Token.
3. In TrackShip > Settings > SMS Notifications, enter your Account SID, Auth Token, and From Number (in E.164 format, e.g. +15551234567).
4. Enable the SMS on Delivery Start toggle.

Message content

When a delivery starts, TrackShip sends a message in the format:

Your order is out for delivery! ETA: 2:30 PM. Track it here: https://yoursite.com/track-your-delivery/?order=123&token=abc

If the ETA could not be calculated, the ETA portion is omitted.

Phone number source

TrackShip uses the customer's WooCommerce billing phone first. If WooCommerce is not active, it falls back to the _trackship_customer_phone order meta field (standalone mode). If no phone number is found, the SMS is silently skipped.

Delivery Analytics Pro

Pro licenses unlock the Delivery Analytics panel at the bottom of the TrackShip settings page. The panel loads automatically via AJAX and shows:

• Total Delivered — All-time count of deliveries marked as delivered.
• Delivered Today — Count of deliveries completed since midnight.
• Active Deliveries — Orders currently in "Out for Delivery" status.
• Avg Delivery Time — Average minutes from delivery start to delivered, calculated over the last 30 days.
• Last 7 Days chart — Bar chart showing daily delivered count for the past 7 days.

All data is read directly from WordPress post meta — no external analytics service required.

White-label Tracking Page Pro

Pro licenses let you replace TrackShip branding on the customer tracking page with your own. Configure in TrackShip > Settings > White-label:

• Brand Name — Replaces "TrackShip" in the header logo text and footer. Leave blank to use the default.
• Logo URL — Full URL to your logo image (max height 36 px recommended). When set, replaces the truck emoji + brand name with your logo image.
• Brand Color — Hex color applied to CTAs, progress fills, links, and the route-notes accent via the --ts-brand CSS variable.
• Footer Text — Replaces the default "Powered by TrackShip" footer. Leave blank for the default.

White-label settings take effect immediately — no cache to clear. Blank fields revert to TrackShip defaults, so you can safely leave only some fields filled in.

Email Notifications

TrackShip sends HTML emails at three delivery milestones. Each can be toggled independently in settings.

• Order Confirmed — Sent when an order is confirmed/processing. Lets the customer know their order was received.
• Out for Delivery — Sent when "Start Delivery" is clicked. Includes the driver's name, ETA, and a direct link to the tracking page.
• Delivered — Sent when the order is marked as delivered. Confirms delivery with a timestamp.

Emails are sent via WordPress's built-in wp_mail(). For reliable delivery, use an SMTP plugin (e.g. WP Mail SMTP).

PWA Mobile App

TrackShip generates a Web App Manifest so customers can install the tracking page as a PWA on iOS and Android. Once installed, it opens full-screen without browser chrome, loads faster on repeat visits, and shows your configured App Name and Theme Color on the splash screen.

No app store submission required — customers add it from their browser's "Add to Home Screen" prompt. Configure the app name and theme color in TrackShip > Settings > PWA Mobile App.

Standalone Mode (No WooCommerce)

If WooCommerce is not active, TrackShip registers its own Delivery Orders custom post type. You can create orders directly from the WordPress admin with fields for customer name, email, phone, delivery address, order items, and total.

The tracking flow is identical to WooCommerce mode — start delivery from the order screen, customer gets a tracking link via email, and the same branded tracking page is shown.

License Activation

Go to TrackShip > Settings. At the top of the page, enter your license key and click Activate License.

• Lite — 1 site activation
• Plus — 3 site activations
• Pro — Unlimited site activations

To move a license to a different site, click Deactivate License on the current site first, then activate on the new site. License keys are managed in your Boulley Technology account.

Troubleshooting

"Getting location…" spinner never finishes

The browser is waiting for GPS permission. If the driver denies location access or the browser times out (8 seconds), the delivery starts with a 0,0 coordinate and the 45-minute default ETA is used. Check that location services are enabled on the device and that the browser has permission to access location for your site.

ETA is always 45 minutes

This means TrackShip is falling back to the default because either (a) GPS was denied, or (b) the customer's address could not be geocoded by OpenStreetMap Nominatim. Verify the shipping address on the order is a complete, valid address. Nominatim requires a street address, city, and country to geocode reliably.

The "Out for Delivery" email was not received

Check the notification toggles in settings. Also verify your WordPress site can send email — use WP Mail SMTP for reliable delivery. If using WooCommerce, the customer's billing email must be set on the order.

The tracking page shows "Order not found"

The tracking URL contains the order ID and a security token. If the URL was modified or the token is wrong, this error appears. Resend the Out for Delivery email to regenerate a fresh tracking link. The customer can also enter their order number in the form on the tracking page.

The Live Map is not showing

The live map requires a Lite or higher license. Verify the license is active in settings. Also ensure the Leaflet CDN is not being blocked by a security plugin or Content Security Policy header on your server.

The zone warning is not appearing

Verify that Zone Check is enabled in settings, that the lat/lng fields are non-zero, and that the radius is greater than 0. The warning only appears if the driver's GPS is captured successfully (not 0,0). It is shown in the meta box response message after clicking Start Delivery — check the message area below the button.

Changelog

1.3.0

• 3-tier licensing — Lite, Plus, Pro
• Driver roster (Plus) — save drivers, assign from dropdown on delivery start
• Route notes (Plus) — delivery instructions shown on customer tracking page
• Delivery zones (Plus) — radius-based service area with driver warning on zone breach
• SMS notifications (Pro) — auto-text customers on dispatch via Twilio
• Delivery analytics (Pro) — total delivered, today's count, active deliveries, avg delivery time, 7-day chart
• White-label tracking page (Pro) — custom logo, brand name, brand color, footer text
• Fixed str_starts_with PHP 7.4 compatibility

1.2.0

• Security improvements — input sanitization, output escaping
• WordPress 6.9 compatibility

1.0.0

• Initial release
• GPS-based delivery tracking with Haversine ETA calculation
• WooCommerce + standalone order support
• Animated progress bar, countdown timer, email notifications
• PWA mobile app support
• Live OpenStreetMap (Lite+)

Support

If you run into anything that isn't covered here:

• Submit a support ticket at boulleytechnology.ca/support.php
• Email support at support@boulleytechnology.ca
• General inquiries: info@boulleytechnology.ca

License holders get priority response. We typically reply within a few hours during business hours.