Check a price

POST

price-checks

Check a price

curl --request POST \
  --url https://sandbox.api.bahnexpress.fi/v2/price-checks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
    },
    "type": "dealership"
  },
  "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"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    pickup: {
      address: {formatted_address: 'Teollisuuskatu 1, 00510 Helsinki, Finland'},
      type: 'dealership'
    },
    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'}
  })
};

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

import requests

url = "https://sandbox.api.bahnexpress.fi/v2/price-checks"

payload = {
    "pickup": {
        "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
        "type": "dealership"
    },
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "status": "available",
  "ordered_for": null,
  "price": {
    "currency": "EUR",
    "total_cents": 45900,
    "transport_cents": 43900,
    "additional_fees_cents": 2000,
    "trade_in_cents": 0
  },
  "distance_meters": 178000,
  "estimated_pickup_at": "2026-08-03T08:00:00+03:00",
  "estimated_delivery_at": "2026-08-03T13:15:00+03:00"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request body is not valid JSON.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/price-checks",
  "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/price-checks",
  "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/price-checks",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

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

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The price could not be checked.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/price-checks",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A trade-in price is available only for a route inside Finland."
}

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

X-Request-Id

string

A caller-supplied request identifier for support.

Required string length: 1 - 255

Body

application/json

Route, vehicles, and service choices used to calculate a price.

pickup

object

required

Proposed pickup details. A price check does not require pickup availability.

Show child attributes

delivery

object

required

Proposed delivery details.

Show child attributes

items

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

required

One primary vehicle and, optionally, one reverse-route trade-in vehicle.

Required array length: 1 - 2 elements

One vehicle included in a price calculation.

Primary vehicle
Trade-in vehicle

Show child attributes

service_options

object

required

Proposed transport and inspection service.

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

Response

The price check is complete.

Automatic price available
Custom quote required

Automatic price result or a clear custom-quote result.

status

any

required

available means the response contains an automatic price.

ordered_for

object | null

required

Business the price was calculated for, or null when it is for your own account.

Show child attributes

price

object

required

Automatic price for this request.

Show child attributes

distance_meters

integer | null

required

The driving distance in meters that the price calculation uses for this route. Bahn's per-km prices use this distance rounded up to whole kilometers. Use it to calculate your own derived prices from exactly the same distance. The value is null when no driving distance is available for the route.

Required range: x >= 0

estimated_pickup_at

string<date-time>

required

Indicative pickup time for this price result. It is not an agreed window or ETA.

estimated_delivery_at

string<date-time>

required

Indicative delivery time for this price result. It is not an agreed window or ETA.

Check a price

curl --request POST \
  --url https://sandbox.api.bahnexpress.fi/v2/price-checks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pickup": {
    "address": {
      "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland"
    },
    "type": "dealership"
  },
  "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"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    pickup: {
      address: {formatted_address: 'Teollisuuskatu 1, 00510 Helsinki, Finland'},
      type: 'dealership'
    },
    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'}
  })
};

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

import requests

url = "https://sandbox.api.bahnexpress.fi/v2/price-checks"

payload = {
    "pickup": {
        "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
        "type": "dealership"
    },
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "status": "available",
  "ordered_for": null,
  "price": {
    "currency": "EUR",
    "total_cents": 45900,
    "transport_cents": 43900,
    "additional_fees_cents": 2000,
    "trade_in_cents": 0
  },
  "distance_meters": 178000,
  "estimated_pickup_at": "2026-08-03T08:00:00+03:00",
  "estimated_delivery_at": "2026-08-03T13:15:00+03:00"
}

{
  "type": "https://api.bahnexpress.fi/problems/validation-error",
  "title": "The request body is not valid JSON.",
  "status": 400,
  "code": "validation_error",
  "instance": "/v2/price-checks",
  "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/price-checks",
  "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/price-checks",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "The orders:write scope is required."
}

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

{
  "type": "https://api.bahnexpress.fi/problems/business-rule-violation",
  "title": "The price could not be checked.",
  "status": 422,
  "code": "business_rule_violation",
  "instance": "/v2/price-checks",
  "request_id": "req_01k1a2b3c4d5e6f7g8h9j0k1m2",
  "detail": "A trade-in price is available only for a route inside Finland."
}

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

Overview

Authentication

Prices

Orders

Webhooks

Tracking

Files

Inspections

Reports

Platform ordering

Sandbox

Authorizations

Headers

Body

Response