Create an order

POST

orders

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",
      "country_code": "FI"
    },
    "type": "dealership",
    "available_from": "2099-08-03T08:00:00+03:00"
  },
  "delivery": {
    "address": {
      "formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland",
      "country_code": "FI"
    },
    "type": "dealership"
  },
  "items": [
    {
      "role": "primary",
      "vin": "WBA00000000000001"
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  }
}
'

{
  "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": "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"
      }
    ],
    "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
  },
  "distance_meters": 178000,
  "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 not valid.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [
    {
      "path": "items.0.vin",
      "code": "too_small",
      "message": "Too small: expected string to have exactly 17 characters"
    }
  ]
}

{
  "type": "https://api.bahnexpress.fi/problems/authentication-failed",
  "title": "The access token is not valid.",
  "status": 401,
  "code": "authentication_failed",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/permission-denied",
  "title": "The access token does not have the required scope.",
  "status": 403,
  "code": "permission_denied",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

{
  "type": "https://api.bahnexpress.fi/problems/idempotency-conflict",
  "title": "The order could not be created.",
  "status": 409,
  "code": "idempotency_conflict",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The idempotency key was used for a different operation."
}

{
  "type": "https://api.bahnexpress.fi/problems/request-too-large",
  "title": "The request body is too large.",
  "status": 413,
  "code": "request_too_large",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The order could not be created.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A cross-border order requires the primary vehicle VIN."
}

{
  "type": "https://api.bahnexpress.fi/problems/internal-error",
  "title": "The server could not complete the request.",
  "status": 500,
  "code": "internal_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/internal-error",
  "title": "The server could not complete the request in time.",
  "status": 503,
  "code": "internal_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

Required scope: orders:write. Read the workflow guide for setup, examples, and recovery behavior.

Authorizations

Authorization

string

header

required

OAuth 2.0 client credentials.

Headers

Idempotency-Key

string

required

A unique key for this logical write across the customer account. Reuse it only for retries of the same operation and request data.

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

Optional. Send it only when an ordering-channel credential orders for another business. Omit it to order for your own account.

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

Business the order was placed for, or null when it belongs to your own account.

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.

distance_meters

integer | null

The driving distance in meters that the price calculation used. The field appears only in the creation response. Bahn does not store the value on the order.

Required range: x >= 0

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",
      "country_code": "FI"
    },
    "type": "dealership",
    "available_from": "2099-08-03T08:00:00+03:00"
  },
  "delivery": {
    "address": {
      "formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland",
      "country_code": "FI"
    },
    "type": "dealership"
  },
  "items": [
    {
      "role": "primary",
      "vin": "WBA00000000000001"
    }
  ],
  "service_options": {
    "transport_preference": "flexible",
    "inspection": "standard"
  }
}
'

{
  "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": "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"
      }
    ],
    "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
  },
  "distance_meters": 178000,
  "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 not valid.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "errors": [
    {
      "path": "items.0.vin",
      "code": "too_small",
      "message": "Too small: expected string to have exactly 17 characters"
    }
  ]
}

{
  "type": "https://api.bahnexpress.fi/problems/authentication-failed",
  "title": "The access token is not valid.",
  "status": 401,
  "code": "authentication_failed",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/permission-denied",
  "title": "The access token does not have the required scope.",
  "status": 403,
  "code": "permission_denied",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

{
  "type": "https://api.bahnexpress.fi/problems/idempotency-conflict",
  "title": "The order could not be created.",
  "status": 409,
  "code": "idempotency_conflict",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The idempotency key was used for a different operation."
}

{
  "type": "https://api.bahnexpress.fi/problems/request-too-large",
  "title": "The request body is too large.",
  "status": 413,
  "code": "request_too_large",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The order could not be created.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A cross-border order requires the primary vehicle VIN."
}

{
  "type": "https://api.bahnexpress.fi/problems/internal-error",
  "title": "The server could not complete the request.",
  "status": 500,
  "code": "internal_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/internal-error",
  "title": "The server could not complete the request in time.",
  "status": 503,
  "code": "internal_error",
  "instance": "/v2/orders",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

Overview

Authentication

Prices

Orders

Webhooks

Tracking

Files

Inspections

Reports

Platform ordering

Sandbox

Authorizations

Headers

Body

Response