Delivery Driver App for WooCommerce documentation

What you bought: three parts that work together

Optional extras you can switch on or off: drivers can claim orders nobody has taken (the “open pool”), drivers can reject an order, and a delivery photo can be compulsory.

1. Unzip the package you downloaded. Inside you will find delivery-driver-app-for-woocommerce-plugin.zip and flutter-app-source.zip. Do not unzip these two.
2. In WordPress open Plugins → Add New → Upload Plugin, choose delivery-driver-app-for-woocommerce-plugin.zip, press Install Now, then Activate.
3. Open Settings → Delivery App. If you see the page with five tabs (Operations, Mobile App, SMS & WhatsApp, Push Notifications, App Builder), the plugin is ready.
4. Check Settings → Permalinks: anything except “Plain” is fine. Press Save Changes once if the app cannot reach your store.

1. Open Users → Add New.
2. Fill in a username (for example maria), an email, the name and a strong password.
3. Set Role to Delivery Boy and press Add User.
4. Give the username and password to the driver. That is all.

Operations: the rules of your delivery business

Mobile App

SMS & WhatsApp

Switch on Enable Automated Texts, choose your provider, paste the key (and secret, if your provider has one), type the sender name or number, and edit the two messages. In the messages you can use {order_id}, {customer_name} and {total}. The “on the way” message is sent when the driver taps Mark as Picked Up; the “delivered” message when the order is completed.

Push Notifications

This is where your Firebase key goes (chapter 7).

A. Create the Firebase project

1. Go to console.firebase.google.com and sign in with a Google account.
2. Press Add project, type a name (for example “Acme Drivers”), and finish the wizard. You can turn Google Analytics off.

B. The file for the app: google-services.json (Android)

1. In your project press the Android icon (“Add app”).
2. Android package name: type the unique name of your app, for example com.acme.drivers. Write it down: you must use exactly the same name in the App Builder (chapter 12).
3. Press Register app, then Download google-services.json. Keep this file for chapter 12 or 13. You can skip the remaining Firebase screens.

C. The file for your store: a service account key

1. In Firebase press the gear icon → Project settings → tab Service accounts.
2. Press Generate new private key and confirm. A .json file downloads.
3. Open that file in a text editor, select everything and copy it.
4. In WordPress open Settings → Delivery App → Push Notifications, paste into the box, press Save Settings.

D. iPhone only

For iPhone also add an iOS app in Firebase (use your bundle ID), download GoogleService-Info.plist, and upload an Apple APNs key under Project settings → Cloud Messaging. Details are in chapter 13.

Test it

Log into the app on a phone (chapter 9), then assign that driver an order (chapter 8). The phone should ring within seconds. The order notes on the order screen say “Push notification sent to driver…” or show the exact error from Google if something is wrong.

1. Open WooCommerce → Orders and click an order that is Processing.
2. In Assign Delivery Boy, open the list and choose the driver.
3. The status line shows “Assigned” and the driver gets a push message.

You can change the driver as long as the delivery is not finished. The new driver starts again at “Assigned”. Choosing the empty line removes the driver.

What you see on the order afterwards

Install and log in

1. Install your app (the APK file from the App Builder email, or from Google Play).
2. Open it, allow notifications and location when asked, and log in with the username and password you created.
3. The dashboard opens. The driver stays logged in until they press Logout or you change their password.

The dashboard

Doing a delivery

1. Tap the order. Call rings the customer, Navigate opens the address in the maps app.
2. Tap Accept Route (or Reject this order, if you allowed it).
3. At the shop tap Mark as Picked Up. The customer can now get the “on the way” text.
4. At the door tap Complete Delivery. If the customer has not paid yet (cash on delivery) the button says Collect Cash & Complete. If you turned on photo proof, the camera opens: take a photo of the parcel at the door and the delivery is completed.

Earnings and profile

The profile screen (person icon, top right) shows Total Earnings from TeraWallet, the dispatch phone number, delivery history, privacy and terms, the app version and Logout.

Set an amount under Operations → Driver Commission per Delivery. When a delivery is completed the plugin adds that amount to the driver’s TeraWallet balance. It is paid once per order, even if the order is edited afterwards. The order notes show “Credited … to driver”. The driver sees the balance as Total Earnings in the app.

Install and activate the free TeraWallet plugin (WooCommerce wallet) for this. Without it deliveries still work; the order note says “Commission not paid: TeraWallet is not active” and the app shows 0.00. To pay your drivers out, use TeraWallet’s own screens (Wallet menu → adjust or withdraw).

Turn on Settings → Delivery App → SMS & WhatsApp → Enable Automated Texts. The customer’s billing phone number is used, so make it a required checkout field and ask for the country code.

Before you start

• Your purchase code.
• Your app icon (square PNG, 1024×1024), a logo and a splash image.
• The google-services.json file from chapter 7, made for the package name you will type below.

Step by step

1. Open Settings → Delivery App → App Builder.
2. Step 1. Check your website address (https, no slash at the end), paste your purchase code and press Connect & load my app. The green “Connected” sign appears. Your code is stored on your server and is not shown again.
3. Step 2. Type the App name (shown under the icon on the phone), the Package name (the same one you gave Firebase, for example com.acme.drivers) and your email. We send the download link to that email.
4. Step 3. Choose the icon, logo and splash images (they upload as soon as you pick them), choose the splash colour and upload google-services.json.
5. Step 4. Choose APK (to install straight on a phone and test) or App Bundle (to upload to Google Play). Press Save details, then Start Android build.
6. Wait for the email (usually a few minutes; builds are queued one after another). Open the link on the phone to download and install the APK.

Good to know

• The builder makes Android apps. For iPhone use the source code (chapter 13).
• Every purchase code can build one app. To change the name, icon or screens later, save the form again and press Build again.
• What is sent to the build server: your site address, purchase code, app name, package name, your email and phone, the splash colour, your three images and the Firebase file. No store passwords or WooCommerce keys are needed.
• Only administrators can use this tab, and every request is protected by a security token.

Install the APK on a phone: open the link in the phone’s browser, allow “install from this source” if Android asks, and open the app. Log in with a driver account from chapter 5.

Requirements

• Flutter 3.41 or newer (flutter doctor should be green), Android Studio for Android, Xcode and CocoaPods for iPhone.

1. Open the project and point it to your store

unzip flutter-app-source.zip -d driver_app && cd driver_app
flutter pub get

# run on a connected phone or emulator
flutter run --dart-define=API_DOMAIN=https://yourstore.com

Or change the default permanently in lib/core/constants/app_config.dart:

class ApiConstants {
  static const String domain = String.fromEnvironment(
    'API_DOMAIN',
    defaultValue: 'https://yourstore.com',   // <- your store, no slash at the end
  );
  ...
}

2. Add your Firebase files

• Android: android/app/google-services.json (the Gradle plugin switches on automatically when the file exists).
• iPhone: ios/Runner/GoogleService-Info.plist, then open ios/Runner.xcworkspace in Xcode and drag it into the Runner group if it shows in red.

3. Name, package and icons

# unique app id (must match Firebase)
dart run change_app_package_name:main com.acme.drivers

# replace assets/images/icon.png (1024x1024) and assets/images/splash.png, then:
dart run flutter_launcher_icons
dart run flutter_native_splash:create

The app name shown on the phone is in android/app/src/main/AndroidManifest.xml (android:label) and ios/Runner/Info.plist (CFBundleDisplayName). Brand colours are in lib/core/constants/app_colors.dart.

4. Sign and build (Android)

# create a signing key once and keep it safe
keytool -genkey -v -keystore ~/acme-drivers.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

# android/key.properties
storeFile=/Users/you/acme-drivers.jks
storePassword=...
keyAlias=upload
keyPassword=...

In android/app/build.gradle.kts read these values in a signingConfigs { create("release") { … } } block and use it in buildTypes.release instead of the debug key (the file has a comment where). Then:

flutter build apk --release --dart-define=API_DOMAIN=https://yourstore.com          # APK to test
flutter build appbundle --release --dart-define=API_DOMAIN=https://yourstore.com     # AAB for Google Play

5. iPhone

cd ios && pod install --repo-update && cd ..
flutter build ipa --release --dart-define=API_DOMAIN=https://yourstore.com

In Xcode choose your Team, set a unique Bundle Identifier (the same as in Firebase) and keep the Push Notifications capability. Upload an APNs key in Firebase for push.

Where things are

Base address: https://yourstore.com/wp-json/taqnix/v1. Everything except /login and /settings needs the token you get from login, sent in the header X-Driver-Token (Authorization: Bearer … works too). Tokens last 90 days, a driver can be logged in on up to 5 phones, and /logout ends one.

Try it

# 1. log in
curl -s -X POST https://yourstore.com/wp-json/taqnix/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"maria","password":"your-password"}'
# -> {"success":true,"data":{"boy_id":7,"token":"7.3f9c…","display_name":"Maria Lopez",...}}

# 2. list my orders
curl -s https://yourstore.com/wp-json/taqnix/v1/orders -H 'X-Driver-Token: 7.3f9c…'

# 3. accept an order
curl -s -X POST https://yourstore.com/wp-json/taqnix/v1/orders/123/status \
  -H 'X-Driver-Token: 7.3f9c…' -H 'Content-Type: application/json' -d '{"status":"accepted"}'

Assign an order from your own code

// PHP, inside WordPress
$order = wc_get_order( 123 );
$result = TDB_Flow::assign( $order, $driver_user_id );   // sends the push message too
if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_message() );
}

Order data you can read

• Every request needs a login token. Without it the API answers “401”. The driver id is taken from the token, never from the request, so one driver cannot read or change another driver’s orders, wallet or position.
• Tokens are random and stored as a one-way hash. Logging out, deleting the user or removing the role ends access immediately.
• The step order is enforced on the server, commission is paid once per order, and uploads must be real JPG, PNG or WebP images.
• Login attempts are limited (5 wrong passwords, then 15 minutes).
• The App Builder tab and every admin action need an administrator and a security token; nothing is available to visitors.
• Data stored: the driver’s last 100 positions, push token and login tokens (user meta), delivery photos (media library), order notes. Ask your drivers for consent to location sharing and mention it in your privacy policy.

Updating

Upload the new plugin zip with Replace current with uploaded; your settings and drivers stay. Build a new app version (chapter 12 or 13) and ask drivers to update. Raise Force App Update to the new version number when you want everyone to update.

If you used “Delivery Boy for WooCommerce” (1.0.x) and “Taqnix App Builder”

• This plugin replaces both. Deactivate and delete “Taqnix App Builder”; its builder is now the App Builder tab here. Enter your purchase code there once.
• Upload this plugin over the old one. Your drivers, settings and orders are kept.
• Old driver apps stop working on purpose. Version 1.1 closed a serious hole: until then anybody who knew a driver’s id could read and change orders. The new app logs in with a token. Build and install the new app, then raise Force App Update.
• The commission used to be a fixed 15, paid again every time an order was saved as completed. It is now a setting (default 0) and is paid once per order.

Removing

Deactivate and delete the plugin. Your drivers (users), orders and photos stay. Plugin settings are removed.

Installation help and bug fixes are included for 6 months, with lifetime updates. Contact us through the marketplace item page where you bought the package. Please include your store address, what you did, and what you saw on the screen (a screenshot helps).