SMS order notifications in Shopware 6: plugin, templates and the Flow Builder route

An e-mail saying “your order has shipped” competes with newsletters, spam filters and a full inbox. An SMS arrives on the lock screen and is read within minutes. For a Shopware 6 shop this makes SMS the natural channel for the few messages a customer actually waits for: the order confirmation, the dispatch notice with the tracking number and the message that something went wrong. This guide shows how to set that up with the TopSMS plugin for Shopware, which states are worth a message, how to write texts that fit into one SMS, and how to do the same without a plugin through the Flow Builder and our REST API.

Which order events deserve an SMS

Shopware tracks three separate state machines per order: the order state (open, in progress, completed, cancelled), the payment state (for example paid, failed, refunded) and the delivery state (for example shipped, partially shipped, returned). Not every transition is worth a text message. Customers appreciate messages that answer a question they would otherwise ask you; everything else is noise and costs money.

The TopSMS plugin for Shopware 6

TopSMS provides a plugin for Shopware 6.6 and 6.7, “TopSMS – SMS für Shopware”, currently in version 1.0.0. It is available as a ZIP download from our integrations page; it is not listed in the Shopware Store yet, so you install it by upload rather than from the store inside the administration.

It covers the events from the table: the order states open (right after checkout), in progress, completed and cancelled, the delivery states shipped and partially shipped, and the payment state paid. Each event is switched on separately and sent at most once per order. In addition, the plugin can send you, the shop owner, an SMS about every new order.

Installation

1. Download the ZIP from the integrations page.
2. In the Shopware administration open Extensions → My extensions, choose Upload extension and select the ZIP.
3. Install and activate the plugin, then open its configuration.
4. Make sure the Shopware message queue is processed, as it is for Shopware’s e-mails: sending runs in the background, so the checkout never waits for the SMS gateway.

Configuration

In the configuration you connect the plugin to your TopSMS account and decide what is sent:

• API Client ID and API Secret. Create a key with the send and read permissions in the TopSMS dashboard under API access and copy both parts into the configuration.
• Test mode. The plugin renders and logs the texts without sending anything, so you can check every event before going live.
• Sender name. Up to 11 letters and digits, for example your shop name. German and Austrian networks deliver alphanumeric sender names without registration; the name must be approved for your TopSMS account (see the article on sender IDs).
• Events and templates. For each event you switch the notification on or off and edit the text. The default texts are in German, and every setting can differ per sales channel.

The result of each message is written to the Shopware log and to the order’s custom field “Last SMS”. Temporary gateway errors are retried with an Idempotency-Key, so a retry never produces a duplicate SMS.

Placeholders

Templates are personalised with placeholders that the plugin fills in from the order:

• {orderNumber} is the Shopware order number,
• {firstName} the customer’s first name,
• {trackingCode} the tracking code of the delivery; if there is none, the sentence that contains it is left out.

Further placeholders are {lastName}, {amountTotal} with {currency} and {shopName}. The customer’s phone number is taken from the billing address and converted to international format according to the billing country, so “0151 2345678” in a German order becomes +491512345678. Shopware does not ask for a phone number by default, so enable the phone number field for registration and checkout in the settings (Settings → Login & registration), ideally as a required field if SMS notifications are important to you.

Templates that fit into one SMS

One SMS segment holds 160 characters of the GSM-7 alphabet. German umlauts and ß belong to it, but emoji, typographic quotes or an en dash switch the whole message to Unicode with only 70 characters per segment, and the message suddenly costs two or three times as much. Keep each template comfortably below 160 characters, including the values that replace the placeholders: an order number such as 10045 is short, a tracking code can be 20 characters. These texts work well (all under 160 characters with realistic values):

• Payment received: MyShop: Thank you {firstName}, we have received your payment for order {orderNumber}. We will let you know when it ships.
• Shipped: MyShop: Order {orderNumber} is on its way. Tracking number: {trackingCode}
• Partially shipped: MyShop: Part of order {orderNumber} has shipped (tracking {trackingCode}). The rest follows separately.
• Payment failed (via the Flow Builder): MyShop: The payment for order {orderNumber} did not go through. Please try again in your customer account or contact us.
• Cancelled: MyShop: Order {orderNumber} has been cancelled. Questions? info@myshop.de

Remember that nobody can reply to an alphanumeric sender. Give an e-mail address or a phone number where a reaction is likely, for example after a cancellation.

Without a plugin: Flow Builder webhook and the REST API

If you prefer not to install a plugin, or need an event the plugin does not cover, such as a failed payment or a custom state, the Flow Builder can call the TopSMS API directly. According to the Shopware documentation, the Webhook Actions (action “Call URL”) are part of the Shopware Commercial extension and available from the Evolve plan onwards. On the Community Edition you would use the plugin or a small custom extension instead.

1. Create a flow with the trigger for the event, for example state_enter.order_delivery.state.shipped for “delivery shipped”, or checkout.order.placed for new orders.
2. Add the action Call URL (Webhook) with method POST and the URL https://www.topsms.cz/api/sms/send.
3. Add the header parameters below. Use headers, not the Basic Auth option: the TopSMS API expects a bearer key.
4. Write the body as JSON with Shopware variables.

Authorization: Bearer CLIENT_ID:SECRET
Content-Type: application/json
Idempotency-Key: shipped-{{ order.orderNumber }}

{
  "to": "{{ order.billingAddress.phoneNumber }}",
  "text": "MyShop: Order {{ order.orderNumber }} has shipped. Tracking: {{ order.deliveries.first.trackingCodes|first }}",
  "from": "MyShop"
}

The variable paths are an example; check them against the variables your Shopware version offers in the body editor, and make sure the phone number arrives in international format (+49…), because a number without a country code cannot be routed reliably. The Idempotency-Key header protects against duplicates: if the webhook is called twice for the same order and event, the second call returns the original response and no second SMS is sent. Send the same request first with a test key; it returns the price and simulates a delivery report without sending anything.

What it costs

An SMS to a German or Austrian number costs €0.084 per segment with TopSMS, with no monthly fee and no extra charge for the plugin or the API. A shop with 1,000 orders a month that sends two notifications per order pays €167.90 a month, as long as each text stays in one segment.

On the legal side, order and shipping notices are transactional messages that belong to the performance of the contract. They do not need marketing consent, but they must stay free of advertising, and your privacy policy should mention that you use the phone number for order notifications. The article on SMS and GDPR in Germany covers the details.