Installation

For merchants

Requirements

• Shopware 6.6 or 6.7, PHP 8.2+. The plugin ships a separate Administration build for each version.
• A map backend: a Google Maps API key (Geocoding API + Distance Matrix API), or OpenStreetMap — see Distance & map providers.
• Working email sending (Shopware: Mailer) — the delivery-code and delivery-confirmed emails use it.
• A database backup — installation creates tables, adds a delivery status, mail templates and flows.

1. Install the plugin

Last-Mile Delivery is not available on Packagist. Install it from the release ZIP or from the Git repository.

Option A — ZIP upload

1. Get the release ZIP from KommandHub.
2. Extensions → My extensions → Upload extension (Shopware: My extensions), select the ZIP.

Option B — Composer from the repository

Requires read access to the repository. Add it to your project's composer.json:

"repositories": [
  { "type": "vcs", "url": "https://github.com/KommandHub-Org/KmhLastMileDeliverySW.git" }
]

Then require a tagged beta release (current: 0.9.0-beta.2):

composer require "kommandhub/last-mile-delivery-sw:^0.9@beta"

Install a tag, not a development branch. For a private repository, give Composer a GitHub token with read access: composer config --global github-oauth.github.com <token> (never commit it). Background: Shopware: extension management.

2. Activate

bin/console plugin:refresh
bin/console plugin:install --activate KmhLastMileDeliverySW
bin/console cache:clear

Or in the Administration: Extensions → My extensions, find Last-Mile Delivery, click Install and switch it active. Once active, Configure on the same row opens its settings.

Installing and activating creates:

What	Details
Shipping method Instant Delivery	technical name kmh_lastmiledelivery_instant; German name Sofortlieferung; tax calculation auto; base price 0 (the real cost is calculated per cart); the first delivery time found in your shop; linked to every sales channel; no availability rule
Delivery status In transit	technical name in_transit (German In Zustellung), with transitions Open → In transit, Shipped partially → In transit, In transit → Shipped, In transit → Cancelled
Mail templates	Delivery OTP — order on its way and Delivery confirmed, English and German
Flows (active)	Delivery OTP: order on its way and Delivery OTP: delivery confirmed — each only if no flow exists yet for its trigger
Administration	Settings → Shop → Delivery price rules, Settings → Shop → Delivery surcharges, and the Delivery verification and Delivery price breakdown cards on the order's General tab
Permission	Last-Mile Delivery for Shopware 6 → Manage under the role's additional permissions
Settings	The plugin settings with their defaults

The shipping method is reset on every activation and update

Install, activate and update all re-apply the shipping method: its name (English Instant Delivery, German Sofortlieferung), active flag, tax type auto and delivery time are set again, and it is linked to every sales channel again. Renames, a deactivation or a removal from a sales channel do not survive an update. Check your storefronts after each update.

Instant Delivery is offered as soon as it is active and linked — but it can't price anything until the map provider and fulfilment location and at least one price rule are set up. Until then customers who pick it see We could not determine the delivery distance… or Instant Delivery is not available… and can't complete checkout. Set it up before your storefront goes live, or remove Instant Delivery from storefronts that don't need it:

1. In the left menu under Sales Channels, click a storefront. On the General tab, scroll to Payment and shipping.
2. Remove Instant Delivery from Shipping methods and click Save (Shopware: Sales channels).

3. Configure the map and your location

Extensions → My extensions → Last-Mile Delivery → Configure:

1. Map provider — OpenStreetMap (default) or Google Maps. For Google, paste the Google Maps API key.
2. Fulfilment latitude and Fulfilment longitude — the point every distance is measured from.
3. Fulfilment timezone — for example Africa/Lagos, if you will use time-based surcharges.

Details: Configuration · Distance & map providers.

4. Create a price rule

Settings → Shop → Delivery price rules → Add rule — name, priority, a price, and conditions such as Distance (km) from 0 to 20. Step by step: Price rules.

5. Verify

1. Storefront: add a product to the cart, go to checkout with a complete street address and choose Instant Delivery. The shipping cost in the summary is your rule's price.
2. Place the order.
3. Administration: open the order. The Delivery price breakdown card shows the base price, any surcharges and the total.
4. Set the order's delivery status to In transit. The customer receives Your order … is on its way with the delivery code.
5. On the Delivery verification card, enter the code and click Verify delivery. The delivery status becomes Shipped and the customer receives Your order … has been delivered.

Each step is described with its screens in Checkout and Handle deliveries.

Permissions

Staff need Last-Mile Delivery for Shopware 6 → Manage in their role (Settings → System → Users & permissions → Roles → role → Additional permissions) to open the price-rule and surcharge modules and to use the Delivery verification card. Changing the delivery status by hand still needs Shopware's normal order permissions. See Shopware: Users & permissions.

Updating

composer update kommandhub/last-mile-delivery-sw     # or upload the new ZIP
bin/console plugin:refresh
bin/console plugin:update KmhLastMileDeliverySW
bin/console cache:clear

plugin:update runs new migrations, re-applies the shipping method (see the warning above) and the default flows — a flow that already exists for its trigger is left alone — and rewrites a raw {{ otpExpiresAt }} placeholder left in the order on its way template by earlier versions into a localised date.

Deactivating

Deactivating sets Instant Delivery inactive. Activating sets it active again.

Uninstalling

Extensions → My extensions → ⋯ → Uninstall, or bin/console plugin:uninstall KmhLastMileDeliverySW (add --keep-user-data to keep the data).

• Instant Delivery is deactivated, never deleted — placed orders reference it.
• With keep user data: price rules, surcharges, price breakdowns, delivery-code records, flows and mail templates stay; reinstalling picks them up again.
• Without keep user data:
  • all plugin tables are dropped: price rules, surcharges, the stored price breakdowns and the delivery-code / proof-of-delivery records. Orders themselves are kept; proof-of-delivery images stay in the media library;
  • every flow on the plugin's three triggers is deleted, including flows you built yourself;
  • the plugin's mail templates are deleted unless a Send email action in another flow still uses them;
  • the In transit status and its transitions are removed — unless a delivery is currently in that status or a status history entry mentions it; then it stays so those orders remain valid;
  • Shopware removes the plugin's settings.
• Uninstalling does not change your project's composer.json.