Skip to main content
An order represents one vehicle transport. It always contains one primary vehicle and can also contain one trade-in vehicle. Read Quickstart for a complete sandbox creation request. Use the API reference for every request and response field.

​
Create an order

Supply these facts for a standard order: A cross-border order needs the primary VIN. A Finland order can use the primary registration number without a VIN. A 201 response means that Bahn accepted the order. Store these fields from the response:
The order also contains the price that Bahn accepted at creation.

​
Order and item status

The order status summarizes all required vehicles. Each vehicle also has its own status. Use the item status when a primary and trade-in vehicle are at different stages. A trade-in order can stay in_transit after Bahn delivers the primary vehicle. Cancellation keeps the last physical item status and actual times.

​
Keep time facts separate

An ETA is one RFC 3339 timestamp. It is null when no current estimate is available. Use eta_updated_at to show when Bahn last updated the ETA. Do not present a requested or agreed window as an ETA. The pickup needs available_from or one requested window. Requested windows for one stop must not overlap. Each window needs start_at, end_at, and an IANA time zone. A requested window is not a commitment.

​
Vehicle condition and inspection

Each item has a pickup_condition and a delivery_condition. A condition stays null until the handover result is available. Use evidence_file_ids to find related photos in the order file list. Do not infer a condition from an item status or a photo. A full inspection report is a separate resource. Read GET /v2/orders/{order_id}/inspection-report when you need it.

​
Vehicle and service rules

A trade-in vehicle needs a registration number. Trade-in orders are available only for routes inside Finland. A private pickup cannot have a trade-in vehicle. Use standard for the normal pickup check. Use full only when the commercial agreement permits a full inspection.

​
Update an order

Update only when allowed_actions contains update. Send a JSON Merge Patch request with the current revision in If-Match. An omitted field keeps its current value. A supplied pickup or delivery object changes only its supplied fields. The file_ids field adds files. It does not remove files. A live ETA change does not change the order revision. You can keep the revision when only the live ETA changes.

​
Cancel an order

Cancellation stops open production work. Confirm the customer intent before you send a production cancellation.
Cancel only when allowed_actions contains cancel. Send the current revision in If-Match and use an idempotency key. The cancelled order stays available for reads.