Troubleshooting

For merchants

Logs

The plugin writes to var/log/kmh_shipbubble_<env>.log in your Shopware directory (rotating, 7 files). Errors are always written; turn on Enable debug logging in the configuration for the full picture, then turn it off again. API keys are never logged.

tail -f var/log/kmh_shipbubble_prod.log

For Shopware's own logging setup, see Shopware: Logging.

Installation problems

The plugin is not listed in Extensions → My extensions. Run bin/console plugin:refresh. With Composer, check the package is in vendor/kommandhub/shipbubble-sw.

Composer can't find kommandhub/shipbubble-sw. Run composer clear-cache and try again. If your project only allows private repositories, add Packagist back (composer config repositories.packagist composer https://repo.packagist.org) — see Installation.

Customers don't see Courier delivery (Shipbubble). The plugin installs it inactive, and deactivating the plugin switches it off again (reactivating doesn't turn it back on). Switch it on under Settings → Shop → Shipping, and check it is assigned to the sales channel and that any availability rule matches.

Configuration problems

Test connection shows an error. Shipbubble's message is shown as is. Check that you saved before testing, that the key matches the Mode (sb_sandbox_… for sandbox, sb_prod_… for live), and that it was copied completely. On a sales-channel view, an empty override inherits All Sales Channels.

The courier and package category lists are empty. They are loaded from Shipbubble with the saved key. Save a working key first, then reload the page.

Validate sender address fails. Shipbubble couldn't find the address. Write the street as precisely as possible (number, street, area), check city and state, and use the two-letter country code NG. Save before validating.

"Add a storefront domain to this sales channel first." The selected sales channel has no web domain, so no webhook URL can be built. Add one under Sales Channels → (channel) → Domains, or use the /default URL from All Sales Channels.

Checkout problems

The messages customers see, and what each one means, are listed in Customer checkout → When a delivery can't be priced.

"Courier delivery is currently unavailable." The API key for the active mode is missing, or the sender isn't validated for that mode. You also get an Administration notification (at most once an hour per sales channel). Fill the key, then Validate sender address — again after switching between sandbox and live.

"Courier delivery is not available in this currency." The storefront isn't in NGN. Shipbubble only quotes in naira.

"Please complete your delivery address, including a phone number…" The shipping address has no phone number, or street, city or country is missing. Turn on the phone field under Settings → Shop → Login & sign-up. Existing customers may need to add a phone number to their address.

"Courier delivery is temporarily unavailable." Shipbubble couldn't be reached in time (the plugin waits 3 seconds). It usually passes; set a fallback price so customers can still order with courier delivery when it happens.

Courier prices look wrong. Check the product weights — products without one are priced with the Default product weight, and the configuration page warns how many active products have none. Weights are in kg. Also check the Package category and your markup.

The price didn't change after editing the cart. It should: any change to products, quantities or the address gets a fresh quote. An unchanged cart and address reuse the quote for the Quote cache time.

Shipment problems

The shipment wasn't booked when the order was paid.

• Check the flow Shipbubble: create shipment when paid is active (Settings → Flow Builder).
• Open the order: a red message on the Shipbubble card shows Shipbubble's reason. You also received the booking failed email.
• Status Needs a new price: the order was placed at the fallback price or the quote expired — book it yourself with Create shipment and confirm the price (re-quote).

Booking fails with "Insufficient wallet balance. Please fund your wallet." Live bookings are paid from your Shipbubble wallet. Top it up in the Shipbubble dashboard, then click Create shipment again. If Shipbubble won't let you fund the wallet, your account isn't verified yet — finish verification with Shipbubble first.

"Confirm new courier price" appears again after I clicked Book shipment. The confirmation is valid for 15 minutes. After that the price is fetched again and you're asked once more.

Cancel shipment shows a red message such as "Shipment label already processed". Shipbubble refused the cancellation — a shipment can only be cancelled before the courier picks it up. The status stays as it was. Contact Shipbubble if the parcel must be stopped.

The Shipbubble card is missing. It only appears for deliveries shipped with Courier delivery (Shipbubble), and your role needs the Shipbubble shipments permission (Permissions).

The status does not change by itself

Status updates arrive as Shipbubble webhooks and are processed in the background. Check:

1. A message queue worker is running — bin/console messenger:consume (or your hosting's worker). Without it, webhooks are accepted and stored but never applied (Shopware: Message queue).
2. The webhook URL in the Shipbubble dashboard (Settings → API keys & webhooks, test and live) is exactly the one on the configuration page.
3. That domain is configured on a Shopware sales channel and reachable from the internet — no basic auth, maintenance mode or firewall in front.
4. Last update from Shipbubble on the configuration page — if it shows no date, no valid webhook has reached the shop.

Webhook responses, as Shipbubble's dashboard or your server log shows them:

Response	Meaning	Fix
200	Accepted (or a redelivery, which is processed only once)	If nothing changes, check the worker.
400 from Shopware	Domain not configured on a sales channel	Add the domain.
400 from the plugin	The body isn't a Shipbubble event	—
401	Signature doesn't match	The key saved for the URL's scope (/default = All Sales Channels, otherwise that channel) must be the key of the Shipbubble account sending the webhook, in the matching mode.

Meanwhile, Refresh status on the order card fetches the current status by hand.

The delivery status didn't change although the Shipbubble status did. The delivery was already in a state that doesn't allow the change (for example cancelling a delivery that is shipped). This is skipped and logged on purpose. Note that Delivered never changes the delivery status — Shopware has no delivered state (details).

Known issues

In version 1.0.0:

Issue	Impact	Workaround
In the Flow Builder list, the Shipbubble triggers are shown by their technical names (sw-flow-custom-event.flow-list.kmh_shipbubble_shipment_…).	Cosmetic; the flows work.	Recognise the flows by their names (Shipbubble: …).
A deleted installed flow is created again on the next plugin update or activation.	Deleting doesn't stop it for good.	Switch the flow off instead of deleting it.
NGN only; one pickup address per sales channel; no cash on delivery through Shipbubble; product dimensions are not used.	See limitations.	—

Still stuck? Contact support with the plugin version, Shopware version, the order number and the log lines.