How to Integrate Retool with DHL API

DHL's developer platform is at developer.dhl.com. Create an account using your business email address. After email verification, you can explore DHL's available API products. Each API product has a separate registration and approval process — select the APIs relevant to your use case. For a tracking dashboard, register for the DHL Unified Tracking API (labeled 'Shipment Tracking' in the portal). Click 'Get Access' and complete the registration form, which asks for your intended use case and expected API call volume. DHL typically approves tracking API access within 24-48 hours for business accounts. After approval, your API key appears in the developer portal under the approved API's credential section. For the DHL Express API (for creating shipments, not just tracking), you additionally need to link a DHL Express customer account number — this requires contacting DHL Express sales or your account manager to enable API access on your existing DHL account. The Express API base URL is https://express.api.dhl.com/mydhlapi and the Tracking API base URL is https://api.dhl.com/track/shipments. API authentication uses a DHL-API-Key header for the tracking API and HTTP Basic Authentication (username + password from the Express API credentials) for the Express API. Store your tracking API key in a Retool Configuration Variable named DHL_TRACKING_API_KEY marked as secret. If using the Express API, store your username as DHL_EXPRESS_USERNAME and password as DHL_EXPRESS_PASSWORD, both marked as secret.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API. Name the resource 'DHL Tracking API'. Set the Base URL to https://api.dhl.com/track/shipments (for the Unified Tracking API). For the DHL Tracking API, authentication uses a custom header. Scroll to the Headers section and add a custom header: Name → DHL-API-Key, Value → {{ retoolContext.configVars.DHL_TRACKING_API_KEY }}. Add a second header: Accept → application/json to ensure JSON responses. Click Save Resource. If you also need the DHL Express API for shipment creation, create a second resource named 'DHL Express API' with Base URL https://express.api.dhl.com/mydhlapi and select Basic Authentication with username {{ retoolContext.configVars.DHL_EXPRESS_USERNAME }} and password {{ retoolContext.configVars.DHL_EXPRESS_PASSWORD }}. Test the Tracking API resource by creating a query in a Retool app: set Method to GET and Path to / (empty path to track a shipment use /trackingNumber query param). Add URL parameter trackingNumber → 1234567890 (any valid test tracking number). A successful 200 response returns shipment tracking data. A 404 means the tracking number is not found. A 401 means the API key header is missing or incorrect. A 404 on the base path is expected — use a real or sandbox tracking number to verify authentication succeeds.

Create the core tracking queries. Create a query named 'trackSingleShipment'. Set Method to GET and Path to / (the DHL Tracking API path structure uses the base URL itself, with trackingNumber as a URL parameter). Add URL parameters: trackingNumber → {{ trackingInput.value }}, requesterCountryCode → {{ retoolContext.configVars.DHL_REQUESTER_COUNTRY || 'US' }} (the country code of the requester, required by some DHL tracking endpoints). The response JSON contains a shipments array (even for a single tracking number). Each shipment object has: id (tracking number), service (DHL service used), origin (address object), destination (address object), status (current status object with timestamp, location, description, and statusCode), events (array of all tracking events in reverse chronological order), and estimatedTimeOfDelivery. Create a transformer named 'normalizeTrackingData' that extracts the first shipment from the array and formats it: current status code, current status description, origin city and country, destination city and country, estimated delivery date formatted as a readable string, number of total events, days since first scan, and a boolean for whether the shipment has any exception-type status codes (useful for conditional formatting). Create a second transformer named 'normalizeTrackingEvents' that maps the events array to a flat list: each event has timestamp (formatted), location (city + country), description, and statusCode. Sort by timestamp descending for a most-recent-first display.

1// Transformer: normalize DHL tracking events
2const shipments = data.shipments || [];
3if (shipments.length === 0) return [];
4
5const shipment = shipments[0];
6const events = shipment.events || [];
7
8const EXCEPTION_CODES = ['transit-exception', 'failure', 'customs-hold',
9  'returned', 'lost'];
10
11return events.map(event => ({
12  timestamp: event.timestamp
13    ? new Date(event.timestamp).toLocaleString()
14    : 'N/A',
15  location: [
16    event.location?.address?.addressLocality,
17    event.location?.address?.countryCode
18  ].filter(Boolean).join(', ') || 'Unknown',
19  description: event.description || event.status || '',
20  status_code: event.typeCode || '',
21  is_exception: EXCEPTION_CODES.some(code =>
22    (event.typeCode || '').toLowerCase().includes(code)
23  )
24}));

For an operational dashboard tracking dozens or hundreds of active shipments, fetching tracking data one by one through a form input is impractical. Build a batch tracking workflow using your internal order database. Create a query named 'getActiveOrders'. This uses a PostgreSQL or other database resource to fetch all orders with DHL tracking numbers that are not yet in a final delivery status: SELECT order_id, customer_name, tracking_number, destination_country, order_date FROM orders WHERE carrier = 'DHL' AND delivery_status NOT IN ('delivered', 'returned') ORDER BY order_date DESC LIMIT 100. Create a JavaScript query named 'batchTrackShipments'. This iterates over getActiveOrders.data and calls the DHL Tracking API for each tracking number. Use Promise.all to parallelize requests (limit to 5 concurrent to respect rate limits): split the array into chunks of 5, process each chunk with Promise.all, then concatenate results. Each result is merged with the order record by tracking_number to produce rows containing both order metadata (customer name, order ID) and tracking status (current status, last location, estimated delivery). Store the merged results in a Retool state variable named 'batchTrackingResults'. Create a transformer that flags shipments with exception statuses, those in customs for more than 5 days, and those with no movement in more than 7 days. These flagged rows form the alert section of your dashboard.

1// JavaScript query: batch track multiple DHL shipments
2// References getActiveOrders.data for tracking numbers
3const orders = getActiveOrders.data || [];
4const CHUNK_SIZE = 5;
5
6const chunks = [];
7for (let i = 0; i < orders.length; i += CHUNK_SIZE) {
8  chunks.push(orders.slice(i, i + CHUNK_SIZE));
9}
10
11const allResults = [];
12for (const chunk of chunks) {
13  const chunkResults = await Promise.all(
14    chunk.map(async order => {
15      try {
16        const result = await dhlTrackingResource.get('/', {
17          params: { trackingNumber: order.tracking_number }
18        });
19        const shipment = result.data?.shipments?.[0] || {};
20        return {
21          order_id: order.order_id,
22          customer: order.customer_name,
23          tracking_number: order.tracking_number,
24          destination: order.destination_country,
25          status: shipment.status?.description || 'Unknown',
26          status_code: shipment.status?.typeCode || '',
27          last_location: [
28            shipment.status?.location?.address?.addressLocality,
29            shipment.status?.location?.address?.countryCode
30          ].filter(Boolean).join(', '),
31          eta: shipment.estimatedTimeOfDelivery
32            ? new Date(shipment.estimatedTimeOfDelivery).toLocaleDateString()
33            : 'N/A',
34          has_exception: ['failure', 'returned'].some(e =>
35            (shipment.status?.typeCode || '').includes(e))
36        };
37      } catch (e) {
38        return { ...order, status: 'API Error', has_exception: false };
39      }
40    })
41  );
42  allResults.push(...chunkResults);
43}
44
45return allResults;

Build the complete shipping dashboard. Add a Stat bar at the top with four Stat components: Active Shipments ({{ getActiveOrders.data.length }}), In Transit (count of shipments where status_code includes 'transit'), In Customs (count where last_location includes 'customs' or status includes 'customs'), and Exception Alerts (count of has_exception === true). Below the stats, add an Alert Banner component (red, warning-style) that shows when exception shipments exist: 'You have {{ exceptionCount }} shipments with delivery exceptions. Review below.' Make this banner conditionally visible using {{ batchTrackingResults.filter(s => s.has_exception).length > 0 }}. Add a Table named 'shipmentsTable' with Data bound to the batchTrackingResults state variable. Configure columns: tracking_number (as a link to DHL's tracking page: https://www.dhl.com/us-en/home/tracking/tracking-express.html?submit=1&tracking-id={{ row.tracking_number }}), customer, destination, status (color-coded tag: green for delivered, blue for in-transit, red for exception, orange for customs), last_location, and eta. Enable row selection. On row selection, show a detail Container on the right side displaying the full event timeline from trackSingleShipment.data (triggered on selection). Add a Refresh button that triggers batchTrackShipments on click. Add a Search input that filters the table client-side by tracking number or customer name using Retool's table search feature.