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-REV-A",
  "status": "accepted",
  "pickup_readiness": "preparing",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-30T14: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": [
      {
        "start_at": "2099-08-03T15:00:00+03:00",
        "end_at": "2099-08-03T18:00:00+03:00",
        "timezone": "Europe/Helsinki"
      }
    ],
    "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": "x5Bm9Qa2Kd7Rv1Nu4Le8Yc3Hj6Wp0Tg5FsZiAoUkEnM"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request body is not valid JSON.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/authentication-failed",
  "title": "The access token is not valid.",
  "status": 401,
  "code": "authentication_failed",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "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/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

{
  "type": "https://api.bahnexpress.fi/problems/resource-not-found",
  "title": "The order could not change.",
  "status": 404,
  "code": "resource_not_found",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The order does not exist."
}

{
  "type": "https://api.bahnexpress.fi/problems/order-not-updateable",
  "title": "The order could not change.",
  "status": 409,
  "code": "order_not_updateable",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "This order can no longer change."
}

{
  "type": "https://api.bahnexpress.fi/problems/revision-conflict",
  "title": "The order could not change.",
  "status": 412,
  "code": "revision_conflict",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The order revision does not match If-Match."
}

{
  "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/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The order could not change.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A requested window has already ended."
}

{
  "type": "https://api.bahnexpress.fi/problems/internal-error",
  "title": "The server could not complete the request.",
  "status": 500,
  "code": "internal_error",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "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/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "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

If-Match

string

required

The current order revision inside double quotation marks. Preserve it when retrying the same logical write.

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 primary vehicle input. Include its identifier and every fact to retain. 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

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

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-REV-A",
  "status": "accepted",
  "pickup_readiness": "preparing",
  "created_at": "2026-07-30T13:00:00Z",
  "updated_at": "2026-07-30T14: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": [
      {
        "start_at": "2099-08-03T15:00:00+03:00",
        "end_at": "2099-08-03T18:00:00+03:00",
        "timezone": "Europe/Helsinki"
      }
    ],
    "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": "x5Bm9Qa2Kd7Rv1Nu4Le8Yc3Hj6Wp0Tg5FsZiAoUkEnM"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request body is not valid JSON.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/authentication-failed",
  "title": "The access token is not valid.",
  "status": 401,
  "code": "authentication_failed",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "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/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

{
  "type": "https://api.bahnexpress.fi/problems/resource-not-found",
  "title": "The order could not change.",
  "status": 404,
  "code": "resource_not_found",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The order does not exist."
}

{
  "type": "https://api.bahnexpress.fi/problems/order-not-updateable",
  "title": "The order could not change.",
  "status": 409,
  "code": "order_not_updateable",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "This order can no longer change."
}

{
  "type": "https://api.bahnexpress.fi/problems/revision-conflict",
  "title": "The order could not change.",
  "status": 412,
  "code": "revision_conflict",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The order revision does not match If-Match."
}

{
  "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/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2"
}

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The order could not change.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/orders/ord_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A requested window has already ended."
}

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

Overview

Authentication

Prices

Orders

Webhooks

Tracking

Files

Inspections

Reports

Platform ordering

Sandbox

Authorizations

Headers

Path Parameters

Body

Response