Create an order

POST

orders

Create an order

curl --request POST \
  --url https://sandbox.api.bahnexpress.fi/v2/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
    },
    "type": "dealership",
    "contact": {
      "name": "Aino Seller",
      "phone": "+358401234567",
      "email": "aino@example.com"
    },
    "release_code": "GATE-17",
    "available_from": "2099-08-03T08:00:00+03:00",
    "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",
    "contact": {
      "name": "Olli Receiver",
      "phone": "+358409876543",
      "email": "olli@example.com"
    },
    "requested_windows": []
  },
  "items": [
    {
      "role": "primary",
      "vin": "WBA00000000000001",
      "winter_tires": {
        "mounted": true,
        "in_vehicle": false
      }
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pickup: {
      address: {formatted_address: 'Teollisuuskatu 1, 00510 Helsinki, Finland'},
      type: 'dealership',
      contact: {name: 'Aino Seller', phone: '+358401234567', email: 'aino@example.com'},
      release_code: 'GATE-17',
      available_from: '2099-08-03T08:00:00+03:00',
      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',
      contact: {name: 'Olli Receiver', phone: '+358409876543', email: 'olli@example.com'},
      requested_windows: []
    },
    items: [
      {
        role: 'primary',
        vin: 'WBA00000000000001',
        winter_tires: {mounted: true, in_vehicle: false}
      }
    ],
    service_options: {transport_preference: 'flexible', inspection: 'standard'}
  })
};

fetch('https://sandbox.api.bahnexpress.fi/v2/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.api.bahnexpress.fi/v2/orders"

payload = {
    "pickup": {
        "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
        "type": "dealership",
        "contact": {
            "name": "Aino Seller",
            "phone": "+358401234567",
            "email": "aino@example.com"
        },
        "release_code": "GATE-17",
        "available_from": "2099-08-03T08:00:00+03:00",
        "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",
        "contact": {
            "name": "Olli Receiver",
            "phone": "+358409876543",
            "email": "olli@example.com"
        },
        "requested_windows": []
    },
    "items": [
        {
            "role": "primary",
            "vin": "WBA00000000000001",
            "winter_tires": {
                "mounted": True,
                "in_vehicle": False
            }
        }
    ],
    "service_options": {
        "transport_preference": "flexible",
        "inspection": "standard"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "ordered_for": null,
  "customer_reference": "PO-2026-1042",
  "status": "accepted",
  "pickup_readiness": "preparing",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-30T13:00:00Z",
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland",
      "name": null,
      "address_line_1": "Teollisuuskatu 1",
      "address_line_2": null,
      "postal_code": "00510",
      "city": "Helsinki",
      "country_code": "FI",
      "coordinates": {
        "latitude": 60.188,
        "longitude": 24.951
      }
    },
    "type": "dealership",
    "contact": {
      "name": "Aino Seller",
      "phone": "+358401234567",
      "email": "aino@example.com"
    },
    "release_code": "GATE-17",
    "available_from": "2026-08-03T08:00:00+03:00",
    "requested_windows": [
      {
        "start_at": "2026-08-03T08:00:00+03:00",
        "end_at": "2026-08-03T12:00:00+03:00",
        "timezone": "Europe/Helsinki"
      }
    ],
    "agreed_window": null,
    "eta": null,
    "eta_updated_at": null,
    "actual_at": null
  },
  "delivery": {
    "address": {
      "formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland",
      "name": null,
      "address_line_1": "Hatanpään valtatie 24",
      "address_line_2": null,
      "postal_code": "33100",
      "city": "Tampere",
      "country_code": "FI",
      "coordinates": {
        "latitude": 61.489,
        "longitude": 23.766
      }
    },
    "type": "dealership",
    "contact": {
      "name": "Olli Receiver",
      "phone": "+358409876543",
      "email": "olli@example.com"
    },
    "requested_windows": [],
    "agreed_window": null,
    "commitment_deadline_at": null,
    "eta": null,
    "eta_updated_at": null,
    "actual_at": null
  },
  "items": [
    {
      "id": "item_01k1a2b3c4d5e6f7g8h9j0k1m2_primary",
      "role": "primary",
      "status": "awaiting_pickup",
      "vin": "WBA00000000000001",
      "registration_number": null,
      "make": null,
      "model": null,
      "note": null,
      "fuel_type": "unknown",
      "transmission": "unknown",
      "engine_power_kw": null,
      "first_registered_year": null,
      "kerb_weight_kg": null,
      "cmr": "digital",
      "plates": "none",
      "pickup_condition": null,
      "delivery_condition": null,
      "winter_tires": {
        "mounted": true,
        "in_vehicle": false
      }
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  },
  "price": {
    "currency": "EUR",
    "total_cents": 45900,
    "transport_cents": 43900,
    "additional_fees_cents": 2000,
    "trade_in_cents": 0
  },
  "customer_note": "Call the pickup contact before arrival.",
  "allowed_actions": [
    "update",
    "cancel",
    "get_files",
    "get_tracking"
  ],
  "revision": "7qS4Jd1cKx9Nw2Yh6mVb8Pz0Rt3Fu5AeLgCiEoUaWQk"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request is invalid.",
  "status": 400,
  "code": "validation_error",
  "detail": "One or more fields are invalid.",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [
    {
      "path": "items.0.vin",
      "code": "invalid_length",
      "message": "The VIN must contain 17 characters."
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Start with a complete example before you inspect every field.

Create your first order

Get a token and create a complete sandbox order.

Review order rules

See the timing, vehicle, and service rules with focused examples.

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials.

Headers

Idempotency-Key

string

required

A unique key for this logical write.

Required string length: 8 - 255

X-Request-Id

string

A caller-supplied request identifier for support.

Required string length: 1 - 255

Body

application/json

Complete transport request that creates an order in the selected environment.

pickup

object

required

Pickup location and handover details. Send available_from, one or more requested_windows, or both.

Show child attributes

delivery

object

required

Delivery location, handover details, and requested windows.

Show child attributes

items

(Primary vehicle · object | Trade-in vehicle · object)[]

required

Exactly one item must have the primary role.

Required array length: 1 - 2 elements

One vehicle in an order. Use primary for the transported vehicle and trade_in for the return vehicle.

Primary vehicle
Trade-in vehicle

Show child attributes

service_options

object

required

Transport and inspection service for the order.

Show child attributes

ordered_for

object

Represented business for a platform order. Direct customers omit this field.

Show child attributes

customer_reference

string | null

Your reference for matching the Bahn order to your system. It does not need to be unique.

Required string length: 1 - 255

file_ids

string[]

IDs returned by POST /v2/files. Use a customer_document file for a pickup release document.

Stable identifier for an uploaded or published order file.

Pattern: ^file_[a-z0-9]+$

customer_note

string | null

Order-level note for Bahn. Use item.note for vehicle-specific instructions.

Maximum string length: 5000

Response

Bahn created the order.

Current state of one transport order.

string

required

Stable Bahn order ID. Store it after order creation.

Pattern: ^ord_[a-z0-9]+$

ordered_for

object | null

required

Represented business for a platform order, or null for a direct customer order.

Show child attributes

customer_reference

string | null

required

Reference supplied by your system, or null when none was supplied.

status

enum<string>

required

Current overall order state.

Available options:

accepted,

in_transit,

delivered,

cancelled

pickup_readiness

enum<string>

required

Current seller readiness for pickup.

Available options:

pending,

preparing,

confirmed

created_at

string<date-time>

required

Time when Bahn accepted the order.

updated_at

string<date-time>

required

Time when Bahn last updated the order.

pickup

object

required

Current pickup location, contact, requested timing, agreed timing, ETA, and actual time.

Show child attributes

delivery

object

required

Current delivery location, contact, requested timing, agreed timing, ETA, and actual time.

Show child attributes

items

object[]

required

Primary vehicle and optional trade-in vehicle, each with its own state and handover condition.

Required array length: 1 - 2 elements

Show child attributes

service_options

object

required

Transport and inspection service selected for this order.

Show child attributes

price

object | null

required

Price accepted when the order was created, or null when unavailable.

Show child attributes

customer_note

string | null

required

Order-level note supplied by the customer.

allowed_actions

enum<string>[]

required

Actions currently available to this credential. Use this list to enable order controls.

Operation the current credential can perform on the current order state.

Available options:

update,

cancel,

get_files,

get_inspection_report,

get_tracking

revision

string

required

An opaque order revision. Use this value in the If-Match header for an order change. A live ETA update does not change this value.

⌘I

Create an order

curl --request POST \
  --url https://sandbox.api.bahnexpress.fi/v2/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
    },
    "type": "dealership",
    "contact": {
      "name": "Aino Seller",
      "phone": "+358401234567",
      "email": "aino@example.com"
    },
    "release_code": "GATE-17",
    "available_from": "2099-08-03T08:00:00+03:00",
    "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",
    "contact": {
      "name": "Olli Receiver",
      "phone": "+358409876543",
      "email": "olli@example.com"
    },
    "requested_windows": []
  },
  "items": [
    {
      "role": "primary",
      "vin": "WBA00000000000001",
      "winter_tires": {
        "mounted": true,
        "in_vehicle": false
      }
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pickup: {
      address: {formatted_address: 'Teollisuuskatu 1, 00510 Helsinki, Finland'},
      type: 'dealership',
      contact: {name: 'Aino Seller', phone: '+358401234567', email: 'aino@example.com'},
      release_code: 'GATE-17',
      available_from: '2099-08-03T08:00:00+03:00',
      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',
      contact: {name: 'Olli Receiver', phone: '+358409876543', email: 'olli@example.com'},
      requested_windows: []
    },
    items: [
      {
        role: 'primary',
        vin: 'WBA00000000000001',
        winter_tires: {mounted: true, in_vehicle: false}
      }
    ],
    service_options: {transport_preference: 'flexible', inspection: 'standard'}
  })
};

fetch('https://sandbox.api.bahnexpress.fi/v2/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.api.bahnexpress.fi/v2/orders"

payload = {
    "pickup": {
        "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
        "type": "dealership",
        "contact": {
            "name": "Aino Seller",
            "phone": "+358401234567",
            "email": "aino@example.com"
        },
        "release_code": "GATE-17",
        "available_from": "2099-08-03T08:00:00+03:00",
        "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",
        "contact": {
            "name": "Olli Receiver",
            "phone": "+358409876543",
            "email": "olli@example.com"
        },
        "requested_windows": []
    },
    "items": [
        {
            "role": "primary",
            "vin": "WBA00000000000001",
            "winter_tires": {
                "mounted": True,
                "in_vehicle": False
            }
        }
    ],
    "service_options": {
        "transport_preference": "flexible",
        "inspection": "standard"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "ordered_for": null,
  "customer_reference": "PO-2026-1042",
  "status": "accepted",
  "pickup_readiness": "preparing",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-30T13:00:00Z",
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland",
      "name": null,
      "address_line_1": "Teollisuuskatu 1",
      "address_line_2": null,
      "postal_code": "00510",
      "city": "Helsinki",
      "country_code": "FI",
      "coordinates": {
        "latitude": 60.188,
        "longitude": 24.951
      }
    },
    "type": "dealership",
    "contact": {
      "name": "Aino Seller",
      "phone": "+358401234567",
      "email": "aino@example.com"
    },
    "release_code": "GATE-17",
    "available_from": "2026-08-03T08:00:00+03:00",
    "requested_windows": [
      {
        "start_at": "2026-08-03T08:00:00+03:00",
        "end_at": "2026-08-03T12:00:00+03:00",
        "timezone": "Europe/Helsinki"
      }
    ],
    "agreed_window": null,
    "eta": null,
    "eta_updated_at": null,
    "actual_at": null
  },
  "delivery": {
    "address": {
      "formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland",
      "name": null,
      "address_line_1": "Hatanpään valtatie 24",
      "address_line_2": null,
      "postal_code": "33100",
      "city": "Tampere",
      "country_code": "FI",
      "coordinates": {
        "latitude": 61.489,
        "longitude": 23.766
      }
    },
    "type": "dealership",
    "contact": {
      "name": "Olli Receiver",
      "phone": "+358409876543",
      "email": "olli@example.com"
    },
    "requested_windows": [],
    "agreed_window": null,
    "commitment_deadline_at": null,
    "eta": null,
    "eta_updated_at": null,
    "actual_at": null
  },
  "items": [
    {
      "id": "item_01k1a2b3c4d5e6f7g8h9j0k1m2_primary",
      "role": "primary",
      "status": "awaiting_pickup",
      "vin": "WBA00000000000001",
      "registration_number": null,
      "make": null,
      "model": null,
      "note": null,
      "fuel_type": "unknown",
      "transmission": "unknown",
      "engine_power_kw": null,
      "first_registered_year": null,
      "kerb_weight_kg": null,
      "cmr": "digital",
      "plates": "none",
      "pickup_condition": null,
      "delivery_condition": null,
      "winter_tires": {
        "mounted": true,
        "in_vehicle": false
      }
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  },
  "price": {
    "currency": "EUR",
    "total_cents": 45900,
    "transport_cents": 43900,
    "additional_fees_cents": 2000,
    "trade_in_cents": 0
  },
  "customer_note": "Call the pickup contact before arrival.",
  "allowed_actions": [
    "update",
    "cancel",
    "get_files",
    "get_tracking"
  ],
  "revision": "7qS4Jd1cKx9Nw2Yh6mVb8Pz0Rt3Fu5AeLgCiEoUaWQk"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request is invalid.",
  "status": 400,
  "code": "validation_error",
  "detail": "One or more fields are invalid.",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [
    {
      "path": "items.0.vin",
      "code": "invalid_length",
      "message": "The VIN must contain 17 characters."
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 499,
  "instance": "<string>",
  "request_id": "<string>",
  "detail": "<string>",
  "errors": [
    {
      "path": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Authentication

Prices

Files

Orders

Inspections

Tracking

Reports

Sandbox

Webhooks

Create your first order

Review order rules

Authorizations

Headers

Body

Response