Configuration Reference
All settings are managed from the app’s admin page in your Shopify dashboard.
Merchant Settings
Field Mapping
These settings control which Shopify address fields the pickup location data is written to.
| Setting | Default | Description |
|---|---|---|
| Street field | address1 |
Receives the street name and house number of the pickup location |
| Name field | address2 |
Receives the location name (e.g. “Packstation 186”) |
| Number field | — | Optional field for the Packstation number |
| Postnummer field | company |
Where the customer’s Postnummer is stored |
| Additional address fields | Off | When enabled, uses extra address fields for mapping |
Postnummer
| Setting | Default | Description |
|---|---|---|
| Postnummer required | Off | When on, customers must enter a Postnummer for Packstation deliveries |
When Postnummer is not required, customers see a checkbox to skip it. This is useful for customers who don’t have a DHL account but want to collect from a Paketshop or Postfiliale instead.
Validation
| Setting | Default | Description |
|---|---|---|
| Block on manual modification | Off | Show a validation error if the customer edits populated address fields |
| Require finder for Packstation | Off | Block checkout if a Packstation address is detected but wasn’t selected via the finder |
Display
| Setting | Default | Description |
|---|---|---|
| Title | DHL Pickup Point | Heading shown above the finder button at checkout |
| Description | — | Optional description text shown below the heading |
Environment Variables
These are set on the server (e.g. in Fly.io secrets or .env):
| Variable | Required | Description |
|---|---|---|
DHL_API_KEY |
Yes | DHL Developer Portal API key, used for the Location Finder API |
DHL_API_SECRET |
No | DHL API secret, needed for Postnummer validation |
DHL_POSTNUMBER_USERNAME |
No | DHL Geschäftskundenportal username for Postnummer API |
DHL_POSTNUMBER_PASSWORD |
No | DHL Geschäftskundenportal password for Postnummer API |
DATABASE_URL |
Yes | PostgreSQL connection string |
If the Postnummer credentials are not set, Postnummer validation is skipped gracefully and checkout continues.
DHL API Setup
Location Finder API
- Register at developer.dhl.com
- Create an app and add the Unified Location Finder API
- Copy your API key into
DHL_API_KEY
This is all that’s needed for the core location search functionality.
Postnummer Validation API (Optional)
For server-side Postnummer validation against DHL’s database:
- Add the Post DE Number Management AM API to your app on the DHL Developer Portal
- Become a DHL business customer at dhl.de/becomeacustomer
- Use your Geschäftskundenportal credentials for
DHL_POSTNUMBER_USERNAMEandDHL_POSTNUMBER_PASSWORD - Set
DHL_API_SECRETto your app’s client secret
Even without this, client-side validation checks Postnummer format and check digits.