Docs

Key Concepts and Terminology ​

Understanding rail-specific terminology helps you build better integrations and communicate clearly with users. This guide explains the key concepts used throughout the All Aboard API.

Core Concepts ​

Journey vs Segment ​

A complete trip from origin to destination, which may include multiple train segments, stopovers, and routing options. Journeys are what you search for and book.

A single train connection between two stations. A journey can consist of multiple segments connected together.

Example: A journey from London to Rome might include segments: London→Paris, Paris→Milan, Milan→Rome.

Offer vs Ticket ​

A pricing option for a journey. Offers include price, return conditions, service class, and reservation details. Multiple offers exist for each journey, giving travelers choices.

Ticket: The confirmed, issued document that allows travel. Tickets are only issued after an order is finalized. Most tickets are PDFs, but some are codes or collection references.

Relationship: You select an offer that is part of a booking, and that offer is issued ticket when the order is finalized.

Booking vs Order ​

A temporary reservation that holds selected offers and passenger details. Bookings expire if not converted to orders within a set time.

The confirmed purchase. Creating an order pre-books tickets with train operators. Finalizing an order completes the purchase and triggers ticket issuance.

Lifecycle: Booking → Order → Finalized Order → Tickets Issued

Segments and SegmentCollection ​

Segment: A single train ride between two stations. A journey consists of multiple segments connected together.

SegmentCollection: A group of segments that form a ticketable part of a journey. For example, a journey might have: SegmentCollection (London→Paris) → Stopover (Paris) → SegmentCollection (Paris→Strasbourg→Zürich).

Admission vs Reservation ​

Admission: The right to travel. The basic ticket that allows you on the train. Admission parts specify fare type, service class, and comfort class.

Reservation: A reserved seat or accommodation. Not all journeys require reservations, some allow you to sit anywhere in your class. Reservation parts specify seat preferences, accommodation type (seat, couchette, sleeper), and comfort class.

Relationship: Most offers include both admission (right to travel) and reservation (specific seat). Some journeys only require admission.

Journey Types ​

SMART Journey ​

Comfort-optimized journeys that balance travel time with comfort. Long routes may include overnight stopovers in cities, giving travelers time to rest. This is the default journey type and best for most travelers.

NON_STOP Journey ​

Fastest possible routes without planned overnight stops. These prioritize speed but may involve long travel days or tight connections. Best when time is critical.

BLUEPRINT Journey ​

Pre-defined itineraries created in the Dashboard. These include planned stopovers at specific locations and departure times. Suited for tour operators or curated travel experiences.

Offer Properties ​

Flexibility ​

Flexibility indicates how changeable or refundable a fare is, from fully flexible (change/cancel with refund) to non-flexible (lowest price, no changes). See the Flexibility enum for possible values.

Service class ​

Service class describes the level of service (e.g. standard vs premium). It maps to travel class: lower values are typically 2nd class, higher values 1st class. See the ServiceClass enum for possible values.

Comfort Classes ​

All operators have different terminology for comfort class. Some call it 1st class and 2nd class whereas others have specific product naming like Business Premier or 2nd class calm.

Rail Pass Concepts ​

Pass Bundle ​

An optimized combination of passes for your passengers. The API automatically finds the cheapest combination that covers everyone.

Travel Days ​

The number of days within the validity period that passengers can travel. For example, a 5-day pass valid for 1 month means passengers can travel on any 5 days within that month.

Validity Period ​

The time window during which the pass is valid. Passes are usually valid for a set number of months, and passengers choose travel days within that period.

Location Concepts ​

Locations ​

The API supports searching using any of our 18,000+ locations. A location can be used as an origin, destination, or intermediate stop. A Location may represent either a specific geographical location, e.g. a station like "Paris Gare de Nord" or a city like "Paris".

Preferred Locations ​

A curated set of 400+ commonly used locations. These are city-level locations (e.g., "Paris") that should be preferred over specific stations (e.g., "Paris Gare de Lyon") when there's uncertainty. Use these for autocomplete and city-level searches.

Using preferred locations will increase chances of good connections being found.

Location UID ​

A unique identifier for each location. Store these in your system and use them for journey searches instead of searching by name each time.

Payment Concepts ​

Wallet Credits ​

Pre-paid credits that are deducted automatically when orders are finalized. Most API integrations use this method. It's simple and doesn't require handling customer payment flows.

Payment Gateway ​

Stripe integration for collecting payment directly from end customers. Redirects customers to All Aboard's secure payment page, then automatically completes orders after payment.

Invoice Billing ​

Monthly invoicing for vetted commercial clients. Orders are accumulated throughout the month and billed at month-end.

Ticket Types ​

PDF Tickets ​

Most common format: digital PDF files that passengers download and show on their phone or print. Works for most operators.

Some operators require online check-in before departure. Passengers visit a URL, complete check-in, and receive their tickets.

Ticket Collection References ​

UK-specific format where passengers use a reference code at station ticket machines to collect physical tickets.

Best Practices ​

  1. Use preferred locations for city-level searches to ensure users find the right location
  2. Store location UIDs in your system instead of searching by name repeatedly
  3. Handle partial success: journeys can have some segments succeed while others fail
  4. Show progress during slow operations (getting offers, creating orders)
  5. Poll for tickets after finalization; they may not be available immediately
  6. Explain fare types to users so they understand flexibility vs price trade-offs