TID Packstations

Introduction

The Packstations Plugin extends the Shopware Storefront with deliveries to DHL Packstations and post offices. During registration, checkout, and address management, customers can choose between a regular delivery address and a DHL collection point.

A responsive finder displays the available collection points in a list and on a map. Customers can search using an address, postal code, or city. After a result is selected, the plugin transfers the DHL collection point to the Shopware delivery address in the required address format.

How It Works

The Packstation selection is integrated into Shopware’s existing address management:

Choice between Address and Post Office or Packstation
Search for Packstations and post offices through the DHL Location Finder API
Results displayed in a list and on a map
Distance, opening hours, and accessibility information displayed when provided by DHL
Selected collection point transferred to the delivery address
Postnumber saved for later reuse

The DHL search is performed by the shop server. The configured DHL API Key is therefore never sent to the customer’s browser.

Packstations and post offices can only be used as delivery addresses. They cannot be selected as the default billing address or created from an existing default billing address.

Requirements

Requirement	Description
`Shopware`	Shopware 6.6 and 6.7 are supported.
`PHP`	PHP 8.2 or newer is required.
`DHL API Key`	Required for searches through the DHL Location Finder API.
`LocationIQ API Key`	Optional; used for the red marker showing the searched customer location on the map.

Installation and Updates

Install the plugin through the deployment process used by the shop. Its technical name is TidPackstationen.

What should be done after installation:

Create a DHL developer account: Register with the DHL API Developer Portal and confirm the email address.
Request access to Location Finder: Create a developer app under My Apps, add the Location Finder - Unified API, and wait for DHL approval if required. The app can be used once its status is Approved.
Copy the DHL API key: Open the app under My Apps, then open the Location Finder API under Credentials. Select Show to display the Consumer Key, enter this value as the DHL API Key in the plugin configuration, save the configuration, and run the DHL connection test.
Configure a LocationIQ Access Token (optional): Create and confirm an account with LocationIQ. Under API Access Tokens in the dashboard, select Show Token for the existing Access Token or create a new Access Token. Enter this value as the LocationIQ API Key, save the configuration, and run the LocationIQ connection test.
Complete the plugin settings: Configure the search radius, result limit, search limit, and Postnumber rule for the shop. When LocationIQ is enabled, LocationIQ requests per second must match the subscribed LocationIQ plan.

LocationIQ officially calls the required credential an Access Token. A separate reverse-search token is not required; the plugin uses the Access Token to find the coordinates of the entered postal code or city.

Configuration

The configuration can be set separately for each sales channel.

DHL Packstations

Setting	Description
`DHL API Key`	Access key for the DHL Location Finder API. The key must be saved before running the connection test.
`Sandbox`	Uses the DHL test environment instead of production. Disabled by default.
`Search radius (km)`	Radius used for the DHL search. Values from `1` to `25` km are supported; the default is `10` km.
`DHL API limit`	Maximum number of DHL collection points displayed. The default is `20`; no more than `50` results are used.
`Search limit (per 20 seconds)`	Maximum number of accepted DHL searches per IP address within 20 seconds. Values from `2` to `30` are supported; the default is `5`.
`Postnumber rule`	Defines for which DHL collection points a Postnumber is required.

Warning

When Sandbox is enabled, DHL sandbox credentials must be used. Production credentials only work when Sandbox is disabled.

DHL API errors are logged and displayed as controlled error messages in the Storefront. After too many search requests, the configured 20-second window must expire before another search can be performed.

Optional Map Extension with LocationIQ

LocationIQ determines the coordinates of the postal code or city entered by the customer. This allows the searched position to be displayed as a separate red marker on the map.

LocationIQ is not required for the DHL search or for the distance information returned by DHL. If a LocationIQ request fails, the DHL results continue to be displayed without the additional position marker.

Setting	Description
`LocationIQ API Key`	Optional access key for geocoding the customer location entered in the search.
`LocationIQ connection`	Tests the previously saved LocationIQ API Key.
`LocationIQ requests per second`	Request limit matching the subscribed LocationIQ plan. Values from `1` to `40` are supported; the default is `2`.

The LocationIQ limit is shared by all requests using the configured API key; it is not applied separately to each visitor.

Postnumber Rule

The DHL Postnumber is saved in the customer custom field dhl_customer_number and reused in later address forms. A Postnumber always consists of exactly 10 digits.

Setting	Description
`Optional`	The Postnumber may remain empty. When provided, it must consist of exactly `10` digits.
`Required for Packstations`	The Postnumber is required for a Packstation and optional for a post office.
`Always required`	The Postnumber is required for every DHL collection point offered by the plugin.

Validation takes place in the Storefront and again on the server during registration and address management.

Usage

In the delivery address form, the customer selects Post Office or Packstation instead of Address. The customer then:

Enters an address, postal code, or city.
Starts the search for available DHL collection points.
Selects a result in the list or on the map.
Transfers the Packstation or post office to the delivery address form.
Enters their personal DHL Postnumber when required.

The search uses the customer’s active delivery country. The collection-point types available in a country depend on the response from the DHL API.

Stored Address Format

The type and number of the DHL collection point are saved in Shopware’s regular street field:

Packstation 123
Postfiliale 45

Postal code, city, country, and recipient are saved in the corresponding Shopware address fields.

Warning

Packstations and post offices are always delivery addresses. Preventing these addresses from being selected as billing addresses is intentional and is additionally enforced through the Shopware Store API.

Privacy and Consent

The Leaflet map library is included in the plugin and served locally. However, the visitor’s browser loads the actual map tiles from tile.openstreetmap.org. This transfers standard connection data, such as the IP address, to the map server.

The Require consent for the Packstation Finder option is disabled by default.

When the option is disabled:

No additional Packstation entry is added to Shopware’s cookie management
The Packstation Finder is provided without checking for consent
The OpenStreetMap map is initialized when the finder is opened

When the option is enabled:

The Packstation Finder remains hidden until consent is given
No map is initialized before consent
A rejected or withdrawn consent switches the form back to a regular delivery address
An open map is closed when consent is withdrawn

The regular delivery-address functionality remains available without consent.

Shopware Cookie Management

When the consent option is enabled, the plugin automatically adds the following entry to Shopware’s cookie management:

Element	Value
Group	`Packstation Finder`
Entry	`OpenStreetMap Map`
Consent cookie	`tid-packstation-consent`
Accepted value	`1`
Lifetime	`30 days`

No additional setup is required when Shopware’s native cookie management is used. The tid-packstation-consent cookie stores only the plugin’s local consent decision and is not an OpenStreetMap cookie.

Usercentrics

Warning

The Shopware plugin cannot create a data-processing service in an external Usercentrics account. If Usercentrics is meant to control consent, OpenStreetMap must be configured and published manually in the Usercentrics Admin Interface.

Manual setup is required when:

The shop uses Usercentrics
Require consent for the Packstation Finder is enabled
Usercentrics should control OpenStreetMap consent

To configure it:

Open the Usercentrics Admin Interface.
Add or create a data-processing service for OpenStreetMap.
Copy the Template ID from the service settings.
Open the TID Packstations plugin configuration in Shopware.
Enter the ID under Usercentrics Template ID or service name and save the configuration.
Publish the updated Usercentrics configuration.
Test the Storefront once with consent granted and once with consent rejected.

The exact service name may be used instead. The Template ID is recommended because it remains stable when the visible service name is renamed or translated.

Once Usercentrics is detected, its decision takes precedence. If the configured identifier cannot be matched to a service, the plugin treats consent as not granted and hides the Packstation Finder.

External Data Flows

Service	Connection	Transmitted Data
`DHL Location Finder`	Shop server to DHL	Delivery country and entered search location. The DHL API key remains on the shop server.
`LocationIQ`	Shop server to LocationIQ	Entered postal code or city. The LocationIQ API key remains on the shop server.
`OpenStreetMap`	Visitor’s browser to OpenStreetMap	Map-tile requests containing standard connection data such as the IP address.

Warning

The consent option provides a technical blocking mechanism. Legal assessment and the wording of the privacy policy remain the shop operator’s responsibility.

Rule Builder

The plugin adds the Shopware condition Delivery address is a DHL collection point. The condition identifies delivery addresses whose street field begins with Packstation or Postfiliale .

For example, this can be used to:

Offer a shipping method only for DHL collection points
Exclude a shipping method for Packstations and post offices
Extend an existing shipping rule with DHL collection points

The exact effect depends on the shop’s shipping and rule configuration.

Packstation Insights

The Administration provides a Packstation Insights section below the orders. Access requires the order.viewer permission.

The analysis includes:

Total searches and searches for today, this week, and this month
Comparisons with the previous day and the previous weekly and monthly periods
Percentage of searches with at least one result
Number of orders delivered to Packstations and post offices
Most active sales channel
Search-limit events that occurred
Daily chart comparing regular orders with DHL collection-point orders for 7, 14, or 30 days
Searchable and sortable order table with recipient, collection point, destination, status, and sales channel
Filters for sales channel and period

For search analysis, the plugin stores the date, sales-channel ID, and counters for searches, successful searches, and search-limit events. The entered search text and the visitor’s IP address are not stored in the analytics table.

The order overview uses the existing Shopware orders and delivery addresses. It does not create a second copy of the orders.

Warning

No automatic retention or deletion period is configured for search analytics. If limited retention is required, the shop operator must implement it.

Plugin Data and Uninstallation

The plugin creates and uses the following data:

Element	Description
`dhl_customer_number`	Customer custom field for the reusable DHL Postnumber.
`packstationen_custom_fields`	Custom-field set created by the plugin.
`tid_packstation_search_daily`	Table containing the daily search and search-limit counters used by Packstation Insights.
`tid_packstationen<environment>.log`	Rotating plugin log containing no more than `10` files.

During uninstallation, the custom-field set and analytics table are removed only when Shopware’s option to retain plugin data is not selected.

Troubleshooting

Why is the Packstation Finder not visible?

Check whether consent is required for the Packstation Finder
With Shopware cookies, check whether Packstation Finder / OpenStreetMap Map has been accepted
With Usercentrics, check whether the OpenStreetMap service has been created and published
Check whether the configured Template ID matches the Usercentrics service
When consent is rejected, hiding the finder is intentional

Why does the DHL search return no results?

Save the DHL API key and check it using the connection test
Check whether Sandbox and the DHL credentials belong to the same environment
Check the active delivery country, search term, and search radius
After a search-limit message, wait for the 20-second window to expire
Check the plugin logs for a controlled DHL error message

Why does the map not show a red position marker?

This is normal when no LocationIQ API key has been configured. The DHL collection points and their distance information continue to work.

When LocationIQ is used:

Save the LocationIQ API key and check it using the connection test
Compare the configured per-second limit with the subscribed LocationIQ plan

Why are changes not visible after an update?

Rebuild the Administration and Storefront when required
Compile the active theme
Clear Shopware and application caches according to the deployment process in use

Why can a Packstation not be selected as a billing address?

This behavior is intentional. Packstations and post offices are supported exclusively as delivery addresses.

TID Relevance Sorting