Skip to main content
Use the order resource to answer when Bahn expects to arrive. Use the tracking resource to answer where the vehicle is and whether the driver is approaching pickup. These values are related, but they are not interchangeable. Do not calculate an ETA from the map position or turn a requested window into an ETA.

​
Show the current ETA

The order contains separate ETA fields for pickup and delivery. Each ETA is an RFC 3339 timestamp, and eta_updated_at tells you when Bahn last updated it. When an ETA is present, show it as the current estimate. If it is null, fall back to the agreed window and then the requested window. After pickup or delivery, show actual_at instead. Bahn sends com.bahn.order.eta_changed.v1 when an ETA appears, disappears, changes materially, or crosses a target boundary. Read the order after the event before you send a customer message or save the estimate.

​
Read one tracking entry per vehicle

Call GET /v2/orders/{order_id}/tracking. The response contains one entry for each order item, so the primary vehicle and trade-in vehicle can have different tracking states and positions. Use the item id to join each tracking entry to the matching vehicle in the order.

​
Tracking state

The phase is pickup before collection and transport after collection.

​
Position

When position is present, render position.point as one GeoJSON map marker. Use accuracy_meters for an accuracy circle and heading_degrees for marker direction when those values are available. Show observed_at near the map. It is the time when Bahn observed the position, not the time when your application fetched it. During a short location gap, the same position can remain available with its original observed_at. Keep the marker stable and let the timestamp show its age. When tracking is paused, position is null and the map should not show a live marker.

​
Show pickup approach

pickup_progress helps the seller prepare for handover: Once progress becomes nearby, it remains nearby for that pickup approach. Use this field directly. A map position does not mean that the driver is nearby or has arrived. driver.name can contain the known driver’s full name during pickup approach. Show it when present and omit the driver element when it is null.

​
Refresh the map efficiently

The tracking response includes an ETag. Send it in If-None-Match on the next request:
A 304 response means that the tracking snapshot did not change. Poll every 30 to 60 seconds while the map is visible, and stop when the user leaves the page or tracking reaches ended. Bahn does not send a webhook for each position. Tracking webhooks tell you about state or pickup-progress changes; polling keeps the marker current while the map is open.