> ## 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. # Apply a sandbox scenario > Applies one deterministic scenario to a sandbox order. Use this route only with the sandbox base URL. The scenario list defines each supported order change. ## OpenAPI ````yaml /openapi.yaml post /v2/test/orders/{order_id}/advance openapi: 3.1.2 info: title: Bahn Customer API version: 2.0.0-draft summary: Create and follow vehicle transport orders. description: | Create vehicle transport orders and read their current state. contact: name: Bahn API support email: support@bahnexpress.com license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://sandbox.api.bahnexpress.fi description: Customer sandbox - url: https://api.bahnexpress.fi description: Production security: - oauth2: - orders:read - orders:write tags: - name: Authentication description: Create an access token for the selected environment. - name: Prices description: Check the current price for a route. - name: Orders description: Create, read, change, and cancel orders. - name: Files description: Upload and read order files. - name: Inspections description: Get vehicle inspection reports. - name: Tracking description: Get the current location for each order item. - name: Reports description: Get order report rows. - name: Sandbox description: Apply deterministic scenarios in the customer sandbox. - name: Webhooks description: Receive order change events from Bahn. paths: /v2/test/orders/{order_id}/advance: servers: - url: https://sandbox.api.bahnexpress.fi description: Customer sandbox parameters: - $ref: '#/components/parameters/OrderId' - $ref: '#/components/parameters/RequestId' post: tags: - Sandbox summary: Apply a sandbox scenario description: | Applies one deterministic scenario to a sandbox order. Use this route only with the sandbox base URL. The scenario list defines each supported order change. operationId: advanceSandboxOrder parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxAdvanceRequest' example: scenario: pickup_readiness_confirmed occurred_at: '2026-08-03T08:40:00+03:00' responses: '200': description: The sandbox applied the scenario. content: application/json: schema: $ref: '#/components/schemas/SandboxAdvanceResult' example: scenario: pickup_readiness_confirmed order: 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-08-03T08:40:00+03:00' 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: null release_code: null available_from: '2026-08-03T08:00:00+03:00' requested_windows: [] agreed_window: null eta: '2026-08-03T08:40:00+03:00' eta_updated_at: '2026-08-03T08:35: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: null requested_windows: [] 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: false 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: null allowed_actions: - update - cancel - get_files - get_inspection_report - get_tracking revision: x5Bm9Qa2Kd7Rv1Nu4Le8Yc3Hj6Wp0Tg5FsZiAoUkEnM '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' security: - oauth2: - test:write components: parameters: OrderId: name: order_id in: path required: true description: The order identifier. schema: $ref: '#/components/schemas/OrderId' RequestId: name: X-Request-Id in: header required: false description: A caller-supplied request identifier for support. schema: type: string minLength: 1 maxLength: 255 IdempotencyKey: name: Idempotency-Key in: header required: true description: A unique key for this logical write. schema: type: string minLength: 8 maxLength: 255 schemas: SandboxAdvanceRequest: description: Scenario to apply to one sandbox order. type: object additionalProperties: false required: - scenario properties: scenario: $ref: '#/components/schemas/SandboxScenario' description: >- Named state change to apply. Its current-state precondition must be satisfied. occurred_at: type: string format: date-time description: >- Optional event time for deterministic tests. Defaults to the current time. SandboxAdvanceResult: description: Applied scenario and the resulting current order. type: object additionalProperties: false required: - scenario - order properties: scenario: $ref: '#/components/schemas/SandboxScenario' description: Scenario that was applied. order: $ref: '#/components/schemas/Order' description: Current order after the scenario. OrderId: type: string pattern: ^ord_[a-z0-9]+$ description: Stable Bahn order identifier used in every order resource path. SandboxScenario: type: string description: Named deterministic change that advances a sandbox order. enum: - pickup_readiness_confirmed - pickup_approach_started - pickup_nearby - pickup_completed - delivery_eta_changed - inspection_completed - files_published - tracking_available - tracking_unavailable - tracking_paused - delivery_completed - cancelled Order: description: Current state of one transport order. type: object additionalProperties: false required: - id - ordered_for - customer_reference - status - pickup_readiness - created_at - updated_at - pickup - delivery - items - service_options - price - customer_note - allowed_actions - revision properties: id: $ref: '#/components/schemas/OrderId' description: Stable Bahn order ID. Store it after order creation. ordered_for: $ref: '#/components/schemas/NullableOrderedFor' description: >- Represented business for a platform order, or null for a direct customer order. customer_reference: type: - string - 'null' description: Reference supplied by your system, or null when none was supplied. status: $ref: '#/components/schemas/OrderStatus' description: Current overall order state. pickup_readiness: $ref: '#/components/schemas/PickupReadiness' description: Current seller readiness for pickup. created_at: type: string format: date-time description: Time when Bahn accepted the order. updated_at: type: string format: date-time description: Time when Bahn last updated the order. pickup: $ref: '#/components/schemas/Pickup' description: >- Current pickup location, contact, requested timing, agreed timing, ETA, and actual time. delivery: $ref: '#/components/schemas/Delivery' description: >- Current delivery location, contact, requested timing, agreed timing, ETA, and actual time. items: type: array minItems: 1 maxItems: 2 description: >- Primary vehicle and optional trade-in vehicle, each with its own state and handover condition. items: $ref: '#/components/schemas/OrderItem' service_options: $ref: '#/components/schemas/ServiceOptions' description: Transport and inspection service selected for this order. price: $ref: '#/components/schemas/Price' description: Price accepted when the order was created, or null when unavailable. customer_note: type: - string - 'null' description: Order-level note supplied by the customer. allowed_actions: type: array uniqueItems: true description: >- Actions currently available to this credential. Use this list to enable order controls. items: $ref: '#/components/schemas/AllowedAction' revision: type: string description: | 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. Problem: description: A machine-readable API error in RFC 9457 problem-details format. type: object additionalProperties: false required: - type - title - status - code - instance - request_id properties: type: type: string format: uri description: A stable URI for the problem type. title: type: string description: A short problem summary. status: type: integer minimum: 400 maximum: 599 description: The HTTP status code returned with this problem. code: $ref: '#/components/schemas/ProblemCode' description: Stable code for application logic and retry decisions. detail: type: string description: A human-readable explanation of this occurrence. instance: type: string description: The request path that produced the problem. request_id: type: string description: Request identifier to include when you contact Bahn support. errors: type: array description: >- Field-level validation errors, when the problem concerns request input. items: $ref: '#/components/schemas/FieldError' NullableOrderedFor: description: >- Represented business, or null when the order belongs to the direct API customer. oneOf: - $ref: '#/components/schemas/OrderedFor' - type: 'null' OrderStatus: type: string description: > Overall order state derived from all vehicles. accepted means no vehicle is in transit; in_transit means transport is underway; delivered means every required vehicle is delivered; cancelled means the order was cancelled. enum: - accepted - in_transit - delivered - cancelled PickupReadiness: type: string description: >- pending before Bahn can confirm pickup availability, preparing while confirmation is possible, and confirmed after Bahn confirms it. enum: - pending - preparing - confirmed Pickup: description: Current pickup details and timing for the order. type: object additionalProperties: false required: - address - type - contact - release_code - available_from - requested_windows - agreed_window - eta - eta_updated_at - actual_at properties: address: $ref: '#/components/schemas/Address' description: Pickup location stored on the order. type: type: string description: Type of pickup handover. enum: - dealership - private contact: $ref: '#/components/schemas/Contact' description: Pickup contact, or null when none is available. release_code: type: - string - 'null' description: Code or reference needed to release the vehicle, when supplied. available_from: type: string format: date-time description: The first time when the vehicle is available for pickup. requested_windows: type: array description: Pickup windows requested by the customer. These are not commitments. items: $ref: '#/components/schemas/TimeWindowInput' agreed_window: oneOf: - $ref: '#/components/schemas/TimeWindowInput' - type: 'null' description: The agreed pickup window. This value is not an ETA. eta: type: - string - 'null' format: date-time description: >- The current pickup ETA. This value is null when no reliable ETA exists. eta_updated_at: type: - string - 'null' format: date-time description: The time when Bahn last calculated or updated the pickup ETA. actual_at: type: - string - 'null' format: date-time description: The actual pickup time. Delivery: description: Current delivery details and timing for the order. type: object additionalProperties: false required: - address - type - contact - requested_windows - agreed_window - commitment_deadline_at - eta - eta_updated_at - actual_at properties: address: $ref: '#/components/schemas/Address' description: Delivery location stored on the order. type: type: string description: Type of delivery handover. enum: - dealership - end_customer contact: $ref: '#/components/schemas/Contact' description: Delivery contact, or null when none is available. requested_windows: type: array description: >- Delivery windows requested by the customer. These are not commitments. items: $ref: '#/components/schemas/TimeWindowInput' agreed_window: oneOf: - $ref: '#/components/schemas/TimeWindowInput' - type: 'null' description: The agreed delivery window. This value is not an ETA. commitment_deadline_at: type: - string - 'null' format: date-time description: The latest committed delivery time. eta: type: - string - 'null' format: date-time description: >- The current delivery ETA. This value is null when no reliable ETA exists. eta_updated_at: type: - string - 'null' format: date-time description: The time when Bahn last calculated or updated the delivery ETA. actual_at: type: - string - 'null' format: date-time description: The actual delivery time. OrderItem: description: Current identity, transport state, and handover results for one vehicle. type: object additionalProperties: false required: - id - role - status - vin - registration_number - make - model - note - fuel_type - transmission - engine_power_kw - first_registered_year - kerb_weight_kg - cmr - plates - pickup_condition - delivery_condition - winter_tires properties: id: $ref: '#/components/schemas/OrderItemId' description: Stable ID for this vehicle within the order. role: type: string description: >- primary for the outbound vehicle; trade_in for the reverse-route vehicle. enum: - primary - trade_in status: $ref: '#/components/schemas/OrderItemStatus' description: Current physical transport state of this vehicle. vin: type: - string - 'null' description: Vehicle identification number, when available. registration_number: type: - string - 'null' description: Registration number, when available. make: type: - string - 'null' description: Vehicle manufacturer, when available. model: type: - string - 'null' description: Vehicle model, when available. note: type: - string - 'null' description: Vehicle-specific note supplied with the order. fuel_type: $ref: '#/components/schemas/FuelType' description: Vehicle fuel or powertrain type. transmission: $ref: '#/components/schemas/Transmission' description: Vehicle transmission type. engine_power_kw: type: - integer - 'null' minimum: 1 description: Engine or motor power in kilowatts, when available. first_registered_year: type: - integer - 'null' minimum: 1886 description: Calendar year of first registration, when available. kerb_weight_kg: type: - integer - 'null' minimum: 1 description: Vehicle kerb weight in kilograms, when available. cmr: type: string description: >- none for no CMR, physical for a paper CMR, or digital for a Bahn-generated document. enum: - none - physical - digital plates: type: string description: Whether the transport requires registration plates for this vehicle. enum: - none - required pickup_condition: description: Condition recorded at pickup, or null until it is available. oneOf: - $ref: '#/components/schemas/PickupCondition' - type: 'null' delivery_condition: description: Condition recorded at delivery, or null until it is available. oneOf: - $ref: '#/components/schemas/DeliveryCondition' - type: 'null' winter_tires: description: >- Winter-tire details for the primary vehicle, or null when not supplied. oneOf: - $ref: '#/components/schemas/WinterTires' - type: 'null' ServiceOptions: description: Transport and inspection service selected for the order. type: object additionalProperties: false required: - transport_preference - inspection properties: transport_preference: type: string description: > How Bahn may move the primary vehicle. flexible allows driven or truck transport; truck_preferred requests a truck when practical; truck_required means the vehicle must not be driven. enum: - flexible - truck_preferred - truck_required inspection: type: string description: >- standard for the normal handover check; full for a structured inspection report. enum: - standard - full Price: description: Accepted order price, or null when automatic pricing was not available. oneOf: - $ref: '#/components/schemas/PriceValue' - type: 'null' AllowedAction: type: string description: Operation the current credential can perform on the current order state. enum: - update - cancel - get_files - get_inspection_report - get_tracking ProblemCode: type: string description: A stable machine code for client decisions. enum: - validation_error - authentication_failed - permission_denied - resource_not_found - idempotency_conflict - revision_conflict - order_not_cancellable - order_not_updateable - business_rule_violation - ordered_for_required - ordered_for_not_allowed - ordered_for_customer_not_found - file_too_large - request_too_large - scenario_not_allowed - internal_error FieldError: description: One invalid request field. type: object additionalProperties: false required: - path - code - message properties: path: type: string description: Dot-separated path to the invalid field. code: type: string description: Stable validation code for this field error. message: type: string description: Human-readable reason why the field is invalid. OrderedFor: description: Business represented by a platform ordering channel. type: object additionalProperties: false required: - country_code - business_id properties: country_code: type: string pattern: ^[A-Z]{2}$ description: The ISO 3166-1 alpha-2 country code of the Bahn customer. business_id: type: string minLength: 1 maxLength: 100 description: The official business ID of the Bahn customer. Address: description: Address stored on the order. type: object additionalProperties: false required: - formatted_address - name - address_line_1 - address_line_2 - postal_code - city - country_code - coordinates properties: formatted_address: type: string description: Complete human-readable address. name: type: - string - 'null' description: Business or site name, when supplied. address_line_1: type: - string - 'null' description: Street name and building number, when supplied. address_line_2: type: - string - 'null' description: Secondary address detail, when supplied. postal_code: type: - string - 'null' description: Postal code, when supplied. city: type: - string - 'null' description: City or municipality, when supplied. country_code: type: - string - 'null' pattern: ^[A-Z]{2}$ description: Two-letter ISO 3166-1 country code, when supplied. coordinates: type: - object - 'null' description: Map coordinates for the address, when available. additionalProperties: false required: - latitude - longitude properties: latitude: type: number minimum: -90 maximum: 90 description: Latitude in decimal degrees. longitude: type: number minimum: -180 maximum: 180 description: Longitude in decimal degrees. Contact: description: >- Contact details for a pickup or delivery location, or null when none are available. type: - object - 'null' additionalProperties: false required: - name - phone - email properties: name: type: - string - 'null' description: Full name of the handover contact. phone: type: - string - 'null' description: Phone number that Bahn can use to coordinate the handover. email: type: - string - 'null' format: email description: Email address for the handover contact. TimeWindowInput: description: One requested or agreed local time range. type: object additionalProperties: false required: - start_at - end_at - timezone properties: start_at: type: string format: date-time description: Start of the window as an RFC 3339 timestamp with an offset. end_at: type: string format: date-time description: End of the window as an RFC 3339 timestamp with an offset. timezone: type: string description: An IANA time-zone name. OrderItemId: type: string pattern: ^item_[a-z0-9]+_(primary|trade_in)$ description: Stable identifier for the primary or trade-in vehicle within an order. OrderItemStatus: type: string description: >- awaiting_pickup before collection, in_transit after collection, and delivered after handover. enum: - awaiting_pickup - in_transit - delivered FuelType: type: string description: Vehicle fuel or powertrain type. enum: - petrol - diesel - electric - hybrid_petrol - hybrid_diesel - unknown Transmission: type: string description: Vehicle transmission type. enum: - manual - automatic - unknown PickupCondition: description: Vehicle condition recorded when Bahn accepts the pickup handover. type: object additionalProperties: false required: - status - description - evidence_file_ids properties: status: type: string description: >- clear when no damage is recorded; damage_reported when damage is recorded. enum: - clear - damage_reported description: type: - string - 'null' description: Human-readable condition or damage note, when available. evidence_file_ids: type: array description: IDs of order files that support this pickup condition. uniqueItems: true items: $ref: '#/components/schemas/FileId' DeliveryCondition: description: Vehicle condition recorded when Bahn accepts the delivery handover. type: object additionalProperties: false required: - status - description - evidence_file_ids properties: status: type: string description: >- clear when no new damage is recorded; new_damage_reported when new damage is recorded. enum: - clear - new_damage_reported description: type: - string - 'null' description: Human-readable condition or new-damage note, when available. evidence_file_ids: type: array description: IDs of order files that support this delivery condition. uniqueItems: true items: $ref: '#/components/schemas/FileId' WinterTires: description: Winter-tire details for the primary vehicle. type: object additionalProperties: false required: - mounted - in_vehicle properties: mounted: type: boolean description: Whether winter tires are mounted on the vehicle. in_vehicle: type: boolean description: Whether an additional winter-tire set travels inside the vehicle. PriceValue: description: Price breakdown in euro cents. type: object additionalProperties: false required: - currency - total_cents - transport_cents - additional_fees_cents - trade_in_cents properties: currency: const: EUR description: Currency for every amount in this price. total_cents: type: integer minimum: 0 description: >- Total price, including transport, additional fees, and trade-in service. transport_cents: type: integer minimum: 0 description: >- Price of the primary vehicle transport before additional fees and trade-in service. additional_fees_cents: type: integer minimum: 0 description: Total additional service fees. trade_in_cents: type: integer minimum: 0 description: >- Price of the reverse-route trade-in transport, or zero when none is included. FileId: type: string pattern: ^file_[a-z0-9]+$ description: Stable identifier for an uploaded or published order file. responses: BadRequest: description: The request syntax or shape is invalid. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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. Unauthorized: description: Authentication failed. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: The token lacks the required scope or customer access. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: The resource does not exist or the customer cannot access it. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Conflict: description: The request conflicts with the current resource state. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' PayloadTooLarge: description: The request body exceeds the maximum size. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ServerError: description: Bahn could not complete the request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: oauth2: type: oauth2 description: OAuth 2.0 client credentials. flows: clientCredentials: tokenUrl: /oauth2/token scopes: orders:read: Read customer orders. orders:write: Check prices, upload files, and change customer orders. reports:read: Read customer order reports. test:write: Apply customer sandbox scenarios. ````