> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bahnexpress.fi/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For Bahn Customer API V2 integration work, start with /skill.md and /guides/agent-integration.md on this documentation site. Use /llms.txt to find the guides for the requested workflow.
> The main integration orders your company's transports from existing software. Follow the requested screen, service, or job. Omit ordered_for for own-account orders. Use the platform-ordering guide to choose order ownership and billing for businesses using a platform. Add a customer-facing interface only when requested.
> Use /openapi.yaml for paths, schemas, scopes, and operation preconditions. Use the guides for transport rules and recovery behavior. Load only the relevant pages.
> Use the sandbox for development and tests. Keep credentials on the server. Production orders start real transport work; follow the customer's authorized workflow and account context.
> For required writes, preserve write keys and request data across retries, and use current actions and quoted revisions for order changes. When consuming webhooks, verify and durably store them before acknowledgement.
> Deliver the implemented workflow with test evidence, setup steps, and remaining gaps. Distinguish simulated checks from requests actually verified against Bahn.

# End-customer invoicing

> An optional billing arrangement for platform accounts enabled by Bahn.

Selected platforms can ask Bahn to invoice an end business. Your platform keeps order ownership and pricing. The named business pays Bahn.

Bahn staff must enable this arrangement for your platform account. Customers cannot enable it themselves. Contact [Bahn support](mailto:support@bahnexpress.com) to agree the setup.

## Choose the billing arrangement

Include `invoice_recipient` only when Bahn should invoice the end business. Without it, normal account billing applies, including on enabled platforms.

Omit `ordered_for`, which assigns the order to another Bahn customer. Read [Platform ordering](/guides/ordering-channels) for that arrangement. Naming an invoice recipient does not grant order access.

Recipients must be VAT-registered businesses established in EU countries outside Finland. Their VAT number and invoice address must identify the same country. Bahn validates VAT registration through VIES in production.

## Create the order

Use your ordering-channel credential. Add this object to [Create an order](/api-reference/orders/create-an-order). The reference defines every field and includes a complete **Enabled platform: invoice the end business** request.

For a [price check](/api-reference/prices/check-a-price), omit both `ordered_for` and `invoice_recipient` to use the platform's pricing.

```json theme={null}
{
  "invoice_recipient": {
    "business_id": "HRB 12345",
    "vat_id": "DE123456789",
    "name": "Example Motors GmbH",
    "contact_name": "Anna Example",
    "address": {
      "street_address": "Teststraße 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country_code": "DE"
    },
    "email": "invoices@example.com"
  }
}
```

`business_id` is the national company-registration identifier. `vat_id` is the separate EU VAT number, including its country prefix. German businesses supply their USt-IdNr. The example VAT number is for sandbox testing.

Supply the registered company name, responsible contact, postal address, and invoice email. Optional `e_invoicing` supplies both the Finvoice address and operator code. Bahn creates a separate English invoice for each order, with zero VAT under EU service reverse charge.

## Read billing progress

Creation and [Get an order](/api-reference/orders/get-an-order) return `invoicing` with the accepted `recipient` and current progress. Normal account billing returns `invoicing: null`.

| Field and value | Meaning |
| - | - |
| `customer_status: pending` | The order is accepted, but the invoice customer's setup in Netvisor needs a retry. |
| `customer_status: ready` | The invoice customer is set up. The invoice may still be unexported. |
| `invoice_status: not_exported` | No invoice export is currently in progress or confirmed. |
| `invoice_status: export_pending` | An export attempt has started. Bahn must confirm its outcome before retrying. |
| `invoice_status: exported` | Netvisor accepted the invoice. This does not confirm sending or payment. |

`invoice_exported_at` is `null` until an export is confirmed. `language` is `EN` and `vat_treatment` is `eu_reverse_charge`.

Accepted details are fixed for that order. Later orders do not redirect earlier invoices. Contact Bahn for corrections.

## Recover from a failure

| Result | Action |
| - | - |
| `400 validation_error` | Correct the named fields, such as VAT syntax or a mismatched country. |
| `422 business_rule_violation` | Check the account arrangement, incompatible `ordered_for`, or VAT registration described in `detail`. |
| `503 invoicing_validation_unavailable` | Retry with backoff, keeping the same idempotency key and request data. |
| Accepted order with `customer_status: pending` | Retry the original create request with the same key and data. Bahn's billing process also retries setup. |
| `invoice_status: export_pending` | Read the order later. Contact Bahn if progress remains pending. |

Customer setup or export failure never makes the platform the payer. Do not remove `invoice_recipient` or use a new key to recover an unknown result. Read [Errors and retries](/guides/errors-and-retries) for general recovery rules.

## Test the arrangement

The sandbox enforces the same permissions and request rules. VAT checks are simulated: valid syntax passes, except all-zero numbers such as `DE000000000`.

Test with and without `invoice_recipient`, invalid registration, and a retry with the original key. Sandbox billing data stays separate. Simulated VAT checks do not prove production registration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.