Platform ordering

This guide is for marketplaces, auction platforms, and other products that arrange transport on behalf of the businesses that use them. Bahn calls this kind of credential an ordering channel. One ordering channel does both of these:

You want to	Send `ordered_for`
Order a transport for your own company	No
Order a transport for a business on your platform	Yes

ordered_for is optional. Leave it out and the order behaves exactly like an order from any other customer: your own Bahn account owns it. Add it and Bahn assigns the order to the business you name. You do not need a second credential to switch between the two. You decide per request. If your company only ever arranges its own transports, you do not need an ordering channel. Use a standard credential and ignore ordered_for. Contact support@bahnexpress.com to have your account configured as an ordering channel before you start production testing.

Compare the two requests

Everything else in the request stays the same.

Your own order
Order for a business on your platform

{
  "customer_reference": "PO-2026-1042",
  "pickup": {
    "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
    "type": "dealership",
    "available_from": "2099-08-03T08:00:00+03:00"
  },
  "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" }
}

The order response contains "ordered_for": null.

{
  "ordered_for": {
    "business_id": "FI12345678",
    "country_code": "FI"
  },
  "customer_reference": "MARKETPLACE-8472",
  "pickup": {
    "address": { "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland" },
    "type": "dealership",
    "available_from": "2099-08-03T08:00:00+03:00"
  },
  "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" }
}

The order response repeats the ordered_for value you sent.

Send the same ordered_for value in the price check and in the order that follows it. A price check for your own account and an order for another business can return different prices.

Name the represented business

Send the official business ID and the country code of the business:

{
  "ordered_for": {
    "business_id": "FI12345678",
    "country_code": "FI"
  }
}

The supported country codes are FI, DK, DE, and PL. Bahn ignores spaces, punctuation, and a leading country prefix when it matches the business ID, so FI12345678, 12345678, and 1234567-8 all reach the same business. The country_code must match the country on that business’s Bahn account. In production the business must already exist as a Bahn customer, and exactly one must match. A request that matches none, or more than one, is rejected with ordered_for_customer_not_found. Ask support@bahnexpress.com to confirm the setup before your first production order for a new business. The represented business does not need its own API credential or a Bahn portal account, and there is no separate consent or grant step in the API flow.

Check before showing the order flow

Call POST /v2/represented-business-checks when your platform needs to decide whether to offer Bahn transport for a business. Send the business identity directly:

{
  "business_id": "FI12345678",
  "country_code": "FI"
}

A successful check returns only the eligibility result:

{
  "status": "eligible"
}

The check does not expose the Bahn customer ID, name, or profile data, and it does not create a customer or order. In production, handle ordered_for_customer_not_found as not eligible. When no customer matches, the sandbox still returns eligible, so it tests your integration flow rather than production customer existence. More than one matching customer is rejected in both environments.

Understand who owns what

The represented business owns the transport and the commercial order. You own the integration: the customer reference, the stored Bahn order ID, the webhook handling, and the support relationship with Bahn. An ordering channel can read and change every order that belongs to its own Bahn account, regardless of where the order was created. It can also read and change orders it created for another business. It cannot read other orders of a business it represents. If the represented business also has its own Bahn credential, it can read the order you created for it. When you rotate your credential, the replacement keeps access to every order the ordering channel created.

Store the context you need

Keep these values together in one record:

Value	Purpose
Bahn order `id`	Read and change the order.
`customer_reference`	Match the transport to the transaction in your product.
`ordered_for`	Identify the represented business, or `null` for your own order.

The same context appears in webhook events and report rows, so one integration can serve many businesses without mixing their data.

Route webhooks

Configure one webhook endpoint for your ordering channel. Read data.ordered_for on every order event to decide which business the event belongs to. A null value means the order is your own. Bahn can also deliver the same event to an active endpoint that the represented business configured. Both deliveries carry the same event ID and order sequence, so each receiver deduplicates normally. Your own orders produce a single delivery, because there is no second business to notify.

Upload files

Upload documents with your ordering-channel credential, then attach the returned file IDs to the order. The represented business can read the attached files. Only your channel can delete its own upload through the API, and only while can_delete is true.

Test the flow

The sandbox accepts any business ID in a supported country. When none matches, the sandbox creates an isolated business for that ID, so you can build the flow before any real business exists in Bahn. Cover all four cases before you go live:

One represented-business check, and confirm your product offers the order flow only after eligible.
One order without ordered_for, and confirm your product treats it as your own.
Two orders with different ordered_for values, and confirm your storage, webhook routing, and customer-facing views never mix them.
One rejected request, so you handle the problem codes below.

Problem code	Meaning	What to do
`ordered_for_not_allowed`	The credential is not an ordering channel.	Remove `ordered_for`, or contact support to configure the channel.
`ordered_for_customer_not_found`	Production found no matching business, or more than one.	Check the business ID and country code with the business, then contact support.

Get started

Create and manage orders

Follow the transport

Reliability and production

Automation

Platform ordering

Compare the two requests

Name the represented business

Check before showing the order flow

Understand who owns what

Store the context you need

Route webhooks

Upload files

Test the flow

​Compare the two requests

​Name the represented business

​Check before showing the order flow

​Understand who owns what

​Store the context you need

​Route webhooks

​Upload files

​Test the flow

Compare the two requests

Name the represented business

Check before showing the order flow

Understand who owns what

Store the context you need

Route webhooks

Upload files

Test the flow