Troubleshooting & FAQ

Here you will find solutions for common problems with the GLS Connector as well as general questions.

Connection Problems

"Authentication failed" (HTTP 401)

Possible Cause	Solution
Username or password incorrect	Check the credentials in the GLS setup
Credentials expired	Contact your GLS account manager
Sandbox credentials used for production URL	Make sure Sandbox Mode is set correctly

"Authorization failed" (HTTP 403)

Possible Cause	Solution
No access to this API endpoint	Check permissions with your GLS account manager
Contact ID not activated	Have the Contact ID confirmed by GLS

"Test Connection" Fails

Step-by-step diagnosis:

Check Sandbox Mode: Is the correct mode enabled?
Check API Base URL: The URL must point to the GLS server
- Sandbox: https://shipit-wbm-sandbox01.gls-group.eu:443/backend/rs
- Production: Provided by GLS
Check Credentials: Username and password correct?
Check Contact ID: GLS customer number entered?
Check Network: Can the BC server reach the GLS URL?
Firewall/Proxy: Is the GLS URL allowed in the firewall?

Connection Test Method

The test uses the AllowedServices endpoint as a proxy, since GLS does not provide a dedicated health check. If this endpoint responds, the connection is active.

Label Creation

Errors in HTTP Headers (GLS-specific)

GLS-specific: Errors in HTTP Headers

Unlike DHL, UPS, and DPD, GLS returns error messages in the HTTP response headers, not in the JSON body. The connector automatically extracts these from the headers X-GLS-ErrorCode, X-GLS-ErrorMessage, and X-GLS-ErrorArgs.

Common API Errors

Error Code	Message	Solution
`INVALID_ADDRESS`	Invalid recipient address	Check postal code, city, and country
`WEIGHT_EXCEEDED`	Weight exceeded	Max. 31.5 kg per parcel; use GLS Freight for heavy shipments
`SERVICE_NOT_ALLOWED`	Service not allowed	Deactivate this VAS for the route
`PARCELS_ALREADY_EXIST`	Shipment already exists	Check if label was already created
`CONTACT_ID_INVALID`	Contact ID invalid	Check Contact ID in setup

Validation Errors (local)

These errors are detected before the API call:

Error Message	Cause	Solution
Missing GLS API credentials	Username/password missing	Enter credentials in setup
Contact ID is required	No Contact ID	Enter Contact ID in setup
Shipper Name 1 is required	Shipper name missing	Complete the shipper address
Ship-to Name is required	Recipient name missing	Enter name
Ship-to Post Code is required	Postal code missing	Enter postal code
Ship-to City is required	City missing	Enter city
Ship-to Country Code is required	Country code missing	Enter ISO-2 country code
Weight must be greater than 0	Weight = 0 and no default	Enter weight or set default in setup
ParcelShop ID is required	ShopDelivery active but no ID	Enter ParcelShop ID
Cash Amount must be greater than 0	COD active, amount = 0	Enter COD amount
Liability Amount must be greater than 0	Insurance active, amount = 0	Enter insurance amount

Cancellation Problems

"Cancellation failed — parcel already in transit"

Shipments can only be cancelled before GLS has physically picked up the parcel. Once the parcel has been scanned, cancellation via the API is no longer possible.

Alternative: Contact GLS customer service directly.

"Track ID not found"

Check if the Track ID is correct
Sandbox labels cannot be cancelled with the production endpoint (and vice versa)

End of Day (EndOfDay)

"No shipments found for end of day"

Cause	Solution
No open shipments for the day	Check if labels were created
Wrong date	The date must match the day of label creation
Shipments already closed	EndOfDay has already been performed

Manifest PDF Missing

The end of day returns a PDF document
Check if the GLS API response was correct
On errors, the cause is in the HTTP response headers

Weight and Measurement Issues

Weight is Transmitted Incorrectly

Problem	Cause	Solution
Weight much too high	Hub stores in grams, GLS expects kg	The connector converts automatically (÷ 1000)
Weight = 0	No weight specified	Enter weight or set default weight in setup
Weight > 31.5 kg	GLS limit exceeded	Switch to GLS Freight or split the parcel

Weight Format

The hub stores weights in grams (integer). The GLS Connector automatically converts to kilograms (decimal). Example: 2500 g → 2.500 kg.

Country Codes

Incorrect Country Code Error

GLS uses ISO alpha-2 country codes:

Correct (GLS)	Incorrect	Country
`DE`	`DEU`	Germany
`AT`	`AUT`	Austria
`CH`	`CHE`	Switzerland
`FR`	`FRA`	France

Business Central already uses ISO alpha-2 by default, so normally no conversion is needed. However, if you have configured ISO-3 codes in your system, you must switch them to ISO-2.

Comparison with Other Carriers

Carrier	Country Code Format
GLS	ISO-2 (DE, AT)
DHL	ISO-3 (DEU, AUT)
UPS	ISO-2 (DE, AT)
DPD	ISO-3 (DEU, AUT)

Sandbox vs. Production

How Do I Switch from Sandbox to Production?

Open the GLS Setup page
Disable Sandbox Mode
Enter the production URL (provided by GLS)
Click Test Connection

Production URL

The production URL is not automatically filled in (unlike the sandbox URL). You will receive it from your GLS account manager.

Sandbox Labels Do Not Work for Shipping

This is normal — sandbox labels have no valid Track IDs and are not physically processed by GLS. They are for testing purposes only.

Label Format Issues

Label Does Not Print Correctly

Format	Printer Type	Recommendation
PDF	Standard PC printer (laser/inkjet)	Standard for most users
PNG	Standard PC printer	Alternative to PDF
Zebra (ZPL)	Zebra thermal printer	Only for Zebra printers!

ZPL Template Does Not Match

If you use Zebra printers, check the Template Set in the setup:

Printer	Template Set
Zebra with 200 dpi	`ZPL 200 dpi`
Zebra with 300 dpi	`ZPL 300 dpi`
Not a Zebra	`None`

Template Set for ZPL Only

Set the Template Set only when using the label format Zebra (ZPL). For PDF and PNG, it must be set to None.

Content-Type Header

API Communication Error

GLS expects a special Content-Type header:

Content-Type: application/glsVersion1+json
Accept: application/glsVersion1+json, application/json

These headers are automatically set by the connector. However, if you build custom extensions via the integration events (OnBeforeCreateGLSParcel), make sure these headers are not overwritten.

General FAQ

Which GLS API version is used?

The connector uses the GLS ShipIT REST API v3.2.9.

Do I need a separate GLS API contract?

Yes. You need a GLS business customer contract with API access (ShipIT). Contact your GLS account manager.

Can I use multiple GLS accounts?

Currently, the connector supports one GLS account per Business Central company.

Are tracking numbers automatically returned?

Yes, the Track ID is automatically saved in the Shipment Label after label creation, and the tracking URL is generated.

Do I have to perform the end of day?

Yes, the end of day (EndOfDay) is required at GLS. It generates the manifest PDF that the GLS driver needs at pickup.

Can GLS create return labels?

Not as a standalone return label. GLS offers the ShopReturn service, which automatically includes a return label when creating the shipping label. See Value Added Services → ShopReturn.

Is the GLS API free?

The API itself is free of charge. You only pay the regular GLS shipping costs as per your contract.

Can I reprint a label?

GLS delivers the label only once when it is created. It cannot be re-downloaded from the GLS API later. However, the label is stored in Business Central and can be reprinted from there at any time.

Support

If you cannot resolve a problem:

Check status in setup: Last Error Message and Last Error DateTime show the last API error
Check Activity Log: Open the merchantCENTRAL Activity Log and filter by GLS
Analyze GLS error message: The GLS API returns specific error codes in HTTP headers
Contact administrator: For setup changes or credential issues
GLS Support: For account-related questions, Contact ID, or service availability