African Commerce Core

Set up Shopware for African markets: activate 26 African countries with their ISO states and regions, give African currencies the right number of decimal places, and add the address details local deliveries need — landmark, area, directions, digital address code, local division — plus a live phone-number check.

Install · Configure · Import reference data · Address fields & phone check · Troubleshoot · Developer docs

Version	0.1.0 · Pre-release (0.x)
Shopware	6.6, 6.7
PHP	8.2+
Plugin name	KmhAfricaCommerceCoreSW
Composer package	kommandhub/africa-commerce-core-sw
Licence	Apache-2.0
Get it	Packagist (Composer) or ZIP upload

What does it do?

The plugin is infrastructure, not a checkout feature. It configures and extends what Shopware already has — countries, states, currencies and the storefront address form — and adds no payment, shipping or checkout logic.

• Reference data. One click (or one command) activates 26 African countries, adds 443 first-tier ISO 3166-2 states and regions, corrects the decimal places of 18 African currencies (XOF and XAF have none, TND has three), and applies two country address policies (Ghana: no postal code; Nigeria: state shown at registration). Safe to run again: a second run changes nothing, and records you mark as your own are never touched.
• Local divisions (optional). A tree of divisions below the state, such as Nigerian LGAs and wards, with a cascading Local division drop-down in the storefront. A Lagos sample ships with the plugin.
• Extra address fields (optional). Nearest landmark, Area / neighbourhood, Directions and Digital address code in the registration and address-book forms, saved with the customer's address.
• Phone check (optional). When a customer leaves the phone field, the number is shown in international format, or a warning appears if it does not look valid for the selected country. It never blocks the form.

Who it is for: shops selling into one or more African countries, especially where addresses rely on landmarks and directions rather than postal codes.

How it fits into Shopware: it writes to Shopware's own countries, states and currencies, and extends the storefront address form. Each capability has its own switch.

Key features

• Run reference-data import button in the plugin configuration, and bin/console africa:reference:import, with a created / updated / up-to-date / overridden / missing count per dataset.
• Idempotent and non-destructive — currencies are never created (they need your real exchange rate) and their exchange rate and name are never changed.
• Merchant override custom field — tick it on a country or currency and the import leaves that record alone.
• Four on/off switches — reference data, local divisions, extra address fields, phone check; the storefront ones can differ per sales channel.
• Storefront in English, German and French.
• Store API endpoints for headless storefronts: division tree and phone normalisation.

Requirements

Shopware	6.6 (6.6.1 or newer) or 6.7
PHP	8.2 or newer, with the intl extension
Currencies	To get the precision fix, the African currencies you sell in must already exist under Settings → Currencies — the plugin never creates them
Phone check	Shopware's phone field switched on under Settings → Log-in & sign-up

Quick start

1. composer require kommandhub/africa-commerce-core-sw, then install and activate — Installation.
2. Open the plugin configuration and click Run reference-data import — Reference data.
3. Assign the countries you sell to to your storefront under Sales Channels → your storefront → Countries — activating a country does not do this.
4. Optional: switch on Additive address fields and Phone normalization — Configuration, Address fields & phone check.
5. Register a test customer in the storefront and check the new fields.

Important limitations

• The import does not run on installation. Nothing changes in your shop until you run it.
• Running the import re-activates every one of the 26 countries, and resets the Ghana and Nigeria address flags, unless the record carries the merchant override.
• The extra address fields are stored with the customer's address book entry. They are not copied to the order and are not shown in the Administration in this version.
• Local division data ships only as a Lagos sample (3 LGAs, 2 wards).
• The Country rules setting and the Logging settings have no visible effect in 0.1.0 — see Configuration.

All known issues: Troubleshooting → Known issues.

Documentation

For shop owners and administrators

• Installation — install, activate, first import, update, uninstall
• Configuration — every setting
• Reference data — what is imported, exactly, and how to protect your own records
• Country rules & sales channels — which settings can differ per storefront and per country
• Address fields & phone check — what customers see and what is stored
• Troubleshooting · FAQ

For developers

• Architecture & extension points — domain core vs. Shopware adapter, services, endpoints, data model, CLI
• Changelog

Shopware resources

• Countries · Currencies · Sales channels · Custom fields

Support

info@kommandhub.com · kommandhub.com/support