Change an order

PATCH

orders

{order_id}

Change an order

curl --request PATCH \
  --url https://sandbox.api.bahnexpress.fi/v2/orders/{order_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'If-Match: <if-match>' \
  --data '{}'

const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({})
};

fetch('https://sandbox.api.bahnexpress.fi/v2/orders/{order_id}', 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/{order_id}"

payload = {}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

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

print(response.text)

{
  "id": "ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "ordered_for": null,
  "customer_reference": "PO-2026-1042",
  "status": "accepted",
  "pickup_readiness": "confirmed",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-31T09: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": {
      "start_at": "2026-08-03T08:00:00+03:00",
      "end_at": "2026-08-03T12:00:00+03:00",
      "timezone": "Europe/Helsinki"
    },
    "eta": "2026-08-03T09:30:00+03:00",
    "eta_updated_at": "2026-08-03T09:20:00+03:00",
    "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": "2026-08-04T18:00:00+03:00",
    "eta": "2026-08-03T14:30:00+03:00",
    "eta_updated_at": "2026-08-03T09:20:00+03:00",
    "actual_at": null
  },
  "items": [
    {
      "id": "item_01k1a2b3c4d5e6f7g8h9j0k1m2_primary",
      "role": "primary",
      "status": "in_transit",
      "vin": "WBA00000000000001",
      "registration_number": "ABC-123",
      "make": "BMW",
      "model": "330e",
      "note": null,
      "fuel_type": "hybrid_petrol",
      "transmission": "automatic",
      "engine_power_kw": 215,
      "first_registered_year": 2023,
      "kerb_weight_kg": 1845,
      "cmr": "digital",
      "plates": "none",
      "pickup_condition": {
        "status": "clear",
        "description": null,
        "evidence_file_ids": []
      },
      "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": "N2f8Kp4Vx1Qa7Js5Dc9Lm3Rw6Ty0Bh8GeUiZoAqCdEs"
}

{
  "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>"
    }
  ]
}

{
  "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>"
    }
  ]
}

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

If-Match

string

required

The current order revision inside double quotation marks.

X-Request-Id

string

A caller-supplied request identifier for support.

Required string length: 1 - 255

Path Parameters

order_id

string

required

The order identifier. Stable Bahn order identifier used in every order resource path.

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

Body

application/merge-patch+json

Order fields to change. Omitted fields keep their current values.

customer_reference

string | null

Replacement customer reference, or null to clear it.

Required string length: 1 - 255

pickup

object

Changes only the supplied pickup fields.

Show child attributes

delivery

object

Changes only the supplied delivery fields.

Show child attributes

items

Primary vehicle · object[]

Replaces the supplied fields for the primary item. A trade-in item remains unchanged.

Required array length: 1 element

Show child attributes

service_options

object

Replacement transport and inspection service.

Show child attributes

file_ids

string[]

Adds uploaded files to the order. Existing order files remain attached.

Stable identifier for an uploaded or published order file.

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

customer_note

string | null

Replacement order-level note, or null to clear it.

Maximum string length: 5000

Response

The updated 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

Change an order

curl --request PATCH \
  --url https://sandbox.api.bahnexpress.fi/v2/orders/{order_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'If-Match: <if-match>' \
  --data '{}'

const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({})
};

fetch('https://sandbox.api.bahnexpress.fi/v2/orders/{order_id}', 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/{order_id}"

payload = {}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

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

print(response.text)

{
  "id": "ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "ordered_for": null,
  "customer_reference": "PO-2026-1042",
  "status": "accepted",
  "pickup_readiness": "confirmed",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-31T09: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": {
      "start_at": "2026-08-03T08:00:00+03:00",
      "end_at": "2026-08-03T12:00:00+03:00",
      "timezone": "Europe/Helsinki"
    },
    "eta": "2026-08-03T09:30:00+03:00",
    "eta_updated_at": "2026-08-03T09:20:00+03:00",
    "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": "2026-08-04T18:00:00+03:00",
    "eta": "2026-08-03T14:30:00+03:00",
    "eta_updated_at": "2026-08-03T09:20:00+03:00",
    "actual_at": null
  },
  "items": [
    {
      "id": "item_01k1a2b3c4d5e6f7g8h9j0k1m2_primary",
      "role": "primary",
      "status": "in_transit",
      "vin": "WBA00000000000001",
      "registration_number": "ABC-123",
      "make": "BMW",
      "model": "330e",
      "note": null,
      "fuel_type": "hybrid_petrol",
      "transmission": "automatic",
      "engine_power_kw": 215,
      "first_registered_year": 2023,
      "kerb_weight_kg": 1845,
      "cmr": "digital",
      "plates": "none",
      "pickup_condition": {
        "status": "clear",
        "description": null,
        "evidence_file_ids": []
      },
      "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": "N2f8Kp4Vx1Qa7Js5Dc9Lm3Rw6Ty0Bh8GeUiZoAqCdEs"
}

{
  "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>"
    }
  ]
}

{
  "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

Authorizations

Headers

Path Parameters

Body

Response