> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bahnexpress.fi/llms.txt
> Use this file to discover all available pages before exploring further.
# Orders and timing
> Create orders and present their status, timing, vehicles, and available actions.
An order represents one vehicle transport. It always contains one primary vehicle and can also contain one trade-in vehicle.
Read [Quickstart](../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:
| Fact | Rule |
| --------------- | ----------------------------------------------------------------------------- |
| Pickup | Send an address, a pickup type, and `available_from` or one requested window. |
| Delivery | Send an address and a delivery type. |
| Primary vehicle | Send the `primary` role and a VIN or registration number. |
| Service options | Select a transport preference and inspection type. |
Use the example that matches your order. Each example is a complete request.
```json theme={null}
{
"customer_reference": "PO-2026-1042",
"pickup": {
"address": {
"formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
},
"type": "dealership",
"available_from": "2099-08-03T08:00:00+03:00"
},
"delivery": {
"address": {
"formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland"
},
"type": "dealership"
},
"items": [
{
"role": "primary",
"vin": "WBA00000000000001"
}
],
"service_options": {
"transport_preference": "flexible",
"inspection": "standard"
},
"customer_note": "Call the pickup contact before arrival."
}
```
```json theme={null}
{
"customer_reference": "PO-2026-1043",
"pickup": {
"address": {
"formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
},
"type": "dealership",
"requested_windows": [
{
"start_at": "2099-08-03T08:00:00+03:00",
"end_at": "2099-08-03T12:00:00+03:00",
"timezone": "Europe/Helsinki"
}
]
},
"delivery": {
"address": {
"formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland"
},
"type": "dealership",
"requested_windows": [
{
"start_at": "2099-08-04T13:00:00+03:00",
"end_at": "2099-08-04T17:00:00+03:00",
"timezone": "Europe/Helsinki"
}
]
},
"items": [
{
"role": "primary",
"vin": "WBA00000000000001"
}
],
"service_options": {
"transport_preference": "flexible",
"inspection": "standard"
}
}
```
```json theme={null}
{
"ordered_for": {
"business_id": "FI12345678",
"country_code": "FI"
},
"customer_reference": "MARKETPLACE-8472",
"pickup": {
"address": {
"formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
},
"type": "dealership",
"available_from": "2099-08-03T08:00:00+03:00"
},
"delivery": {
"address": {
"formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland"
},
"type": "dealership"
},
"items": [
{
"role": "primary",
"registration_number": "ABC-123"
}
],
"service_options": {
"transport_preference": "flexible",
"inspection": "standard"
}
}
```
Only an ordering-channel credential can use `ordered_for`. Read [Platform ordering](./ordering-channels) before you use the platform example.
A cross-border order needs the primary VIN. A Finland order can use the primary registration number without a VIN.
Use `customer_note` for instructions that apply to the complete order. Use `items[].note` for instructions about one vehicle.
A `201` response means that Bahn accepted the order. Store these fields from the response:
```json theme={null}
{
"id": "ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
"customer_reference": "PO-2026-1042",
"status": "accepted",
"allowed_actions": ["update", "cancel", "get_files", "get_tracking"],
"revision": "7qS4Jd1cKx9Nw2Yh6mVb8Pz0Rt3Fu5AeLgCiEoUaWQk"
}
```
The order also contains the price that Bahn accepted at creation.
## Order and item status
The order status summarizes all required vehicles.
| Order status | Meaning |
| ------------ | ------------------------------------------------------------------ |
| `accepted` | No vehicle has entered transit. |
| `in_transit` | At least one vehicle is in transit, but the order is not complete. |
| `delivered` | All required items are delivered. |
| `cancelled` | The order was cancelled. |
Each vehicle also has its own status. Use the item status when a primary and trade-in vehicle are at different stages.
| Item status | Meaning |
| ----------------- | ----------------------------------------------------- |
| `awaiting_pickup` | The vehicle has not been collected. |
| `in_transit` | The vehicle was collected but has not been delivered. |
| `delivered` | The vehicle was delivered. |
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
| Field | Question that it answers |
| --------------------------------- | ------------------------------------------- |
| `pickup.available_from` | When can Bahn first collect the vehicle? |
| `requested_windows` | Which ranges did the customer request? |
| `agreed_window` | Which target range did Bahn agree to? |
| `delivery.commitment_deadline_at` | What is the latest committed delivery time? |
| `eta` | When does Bahn currently expect to arrive? |
| `actual_at` | When did the stop complete? |
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.
You can send `available_from`, `requested_windows`, or both in the same pickup object.
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.
| Transport preference | Meaning |
| -------------------- | ------------------------------------ |
| `flexible` | Bahn selects a driver or a truck. |
| `truck_preferred` | Bahn should prefer a truck. |
| `truck_required` | A driver must not drive the 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.