Docs

Booking Rail Passes ​

Booking rail passes follows the same flow as booking tickets: create a booking, add passenger details, then create and finalize an order. The main difference is that passes are issued as codes (not PDF tickets) that passengers use in the pass provider's app.

Creating a Booking ​

Start by creating a booking from a pass bundle. This reserves the pass but doesn't confirm it yet.

Example: Create a booking with rail passes
graphql
mutation CreateBooking {
  createBooking(
    passBundle: "697f9dfe-5ef0-4db2-ae0f-6b358c53cf58"
    passengers: [{
      birthDate: "1980-02-15"
      firstName: "Jane"
      lastName: "Doe"
    }]
  ) {
    id
    passengers {
      id
      age
      type
    }
    requirements {
      countryResidence
      nationality
      dateOfBirth
      email
      tel
    }
    selections {
      ... on PassBundleSelection {
        class
        product
        price {
          amount
          currency
        }
        travelDayCount
        validityPeriod
      }
    }
  }
}
mutation CreateBooking {
  createBooking(
    passBundle: "4bb64920-42b8-4295-835b-40a57fae9daa"
    passengers: [{
      birthDate: "1980-02-15"
      firstName: "Jane"
      lastName: "Doe"
    }]
  ) {
    id
    passengers {
      id
      age
      type
    }
    requirements {
      countryResidence
      nationality
      dateOfBirth
      email
      tel
    }
    selections {
      ... on PassBundleSelection {
        class
        product
        price {
          amount
          currency
        }
        travelDayCount
        validityPeriod
      }
    }
  }
}

The booking includes requirements that tell you what passenger information is needed. Pass requirements often include nationality and country of residence (some passes are only available to residents of certain countries).

Updating Passengers Details ​

Before you can create an order, ensure that all required passenger information is provided. The booking's requirements field shows exactly what's needed.

Contact person

At least one passenger needs to be marked as the contact person. The contact person's details will be forwarded to the train operator and is the person who will be contacted in case of any issues. The contact person must provide both email and phone number.

Travel cards can't be changed

A booking is priced on its passengers' travel cards, so leave travelCards out when updating passengers. To book with a different card, create a new booking from a fresh offer. See Travel Cards.

Example: Updating passengers details
graphql
mutation UpdatePassengers {
  updateBooking(
    id: "booking_y737r3y6k3v2c691f5d3y4j0h0"
    passengers: [
      {
        id: "b4ef1102-843b-4e7d-afbe-52003805701c"
        email: "jane.doe@example.com"
        isContactPerson: true
        birthDate: "1980-02-15"
        nationality: "NL"
        firstName: "Jane"
        lastName: "Doe"
      }
    ]
  ) {
    id
    passengers {
      ... on FullPassenger {
        id
        isContactPerson
        email
        birthDate
        nationality
        firstName
        lastName
        title
      }
    }
  }
}
mutation UpdatePassengers {
  updateBooking(
    id: "booking_y737r3y6k3v2c691f5d3y4j0h0"
    passengers: [
      {
        id: "b4ef1102-843b-4e7d-afbe-52003805701c"
        email: "jane.doe@example.com"
        isContactPerson: true
        birthDate: "1980-02-15"
        nationality: "NL"
        firstName: "Jane"
        lastName: "Doe"
      }
    ]
  ) {
    id
    passengers {
      ... on FullPassenger {
        id
        isContactPerson
        email
        birthDate
        nationality
        firstName
        lastName
        title
      }
    }
  }
}

Creating and Finalizing Orders ​

Once your booking has all passenger details, create an order with createOrder. This pre-books the pass and is the same first step for every payment method. How you complete the order depends on how you pay:

  • Wallet credits or invoice: Finalize the order yourself with finalizeOrder (see Orders)
  • Payment gateway: Pass the order's id to createPayment as orderId; the order is finalized automatically after payment (see Payments)

Most API users use wallet credits. See Payments for details on all payment methods.

Retrieving Pass Codes ​

Once an order is finalized, passes are automatically issued. Instead of PDF tickets, you receive pass codes that passengers use in the pass provider's mobile app or website.

Pass codes are usually available within 15 minutes of finalization, but can take longer during peak times.

Pass code availability

Pass codes may not be available immediately after finalization. Poll the order every few minutes until codes appear. Most codes are available within 15 minutes.

Retrieve pass codes from the finalized order:

Example: Get pass codes from finalized order
graphql
query GetPassCodes {
  node(id: "order_53x4n1c3g4s1h0q560n5s095c6") {
    ... on Order {
      items {
        ... on PassBundleOrderItem {
          passenger {
            firstName
            lastName
          }
          code
          class
          product
          travelDayCount
          validityPeriod
        }
      }
    }
  }
}
query GetPassCodes {
  node(id: "order_k7n6841236c762n3p3b622b0t7") {
    ... on Order {
      items {
        ... on PassBundleOrderItem {
          passenger {
            firstName
            lastName
          }
          code
          class
          product
          travelDayCount
          validityPeriod
        }
      }
    }
  }
}

Each passenger gets their own pass code. Share the code with the passenger; they use it to activate their pass in the provider's app (e.g., Interrail app, BritRail app).

Pass Activation ​

Pass codes are used to activate passes in the provider's mobile app or website. Passengers:

  1. Download the provider's app (e.g., Interrail app)
  2. Enter the pass code
  3. Activate the pass (usually on their first travel day)
  4. Use the pass to travel on trains

The pass code includes all the details passengers need: product type, class, travel days, and validity period.

Reserving Seats with a Pass ​

A pass gives the right to travel, but many trains still need a seat reservation, and some operators sell passholders a dedicated fare. Book those through the ticket flow with the pass attached to each passenger as a travel card. See Travel Cards.

Complete Flow Summary ​

The complete pass booking flow:

  1. Find passes using getPassBundles (see Finding Rail Passes)
  2. Create booking from a pass bundle
  3. Add passenger details (required information)
  4. Create order (pre-books the pass)
  5. Finalize order (completes purchase, triggers pass code issuance)
  6. Retrieve pass codes (share codes with passengers)

For detailed information on each step, see the relevant sections in this documentation.