Travel Cards
Many travelers hold a card that changes what they pay: a discount card like a BahnCard or a Carte Avantage, an operator's loyalty card, a railcard in the UK, or a rail pass such as Interrail. The API calls all of these travel cards. You attach them to passengers, and the train operators price the journey accordingly.
What a travel card does
A travel card changes which fares a passenger can get. There are two kinds:
- Discount and loyalty cards lower the fare. The passenger gets the fare the card entitles them to, and the ticket names the card. A UK 16-25 Railcard and a Swedish senior discount work this way.
- Rail passes change the product. A passholder already has the right to travel, so the operator sells them a passholder product instead: a seat reservation, or a reduced passholder fare where the operator requires one. With an Interrail Pass attached, those are the offers you get.
In both cases the card affects the price. That is why you attach it both when you get offers and when you create the booking, and why it can't be changed afterward.
Discovering available cards
Use travelCardOptions to list the cards your account can use. Each option has a code, which you send with the passenger, a name to display, and inputFields for any extra data the card needs.
Example: List available travel cards
query GetTravelCardOptions {
travelCardOptions {
code
name
inputFields {
fieldName
requirement
}
}
}{
"data": {
"travelCardOptions": [
{
"code": "aatc_interrail",
"name": "Interrail Pass",
"inputFields": [
{ "fieldName": "identifier", "requirement": "CONDITIONAL" }
]
},
{
"code": "aatc_bahncard_25",
"name": "BahnCard 25",
"inputFields": [{ "fieldName": "identifier", "requirement": "ALWAYS" }]
},
{
"code": "aatc_uk_16_25",
"name": "UK 16-25 Railcard",
"inputFields": []
},
{
"code": "aatc_swe_senior",
"name": "Senior in Sweden",
"inputFields": []
}
]
}
}The requirement of each input field says when the field is needed:
ALWAYS: Send the field whenever you attach the card.CONDITIONAL: You can leave the field out at first. Whether it is needed depends on what is in the booking, and the API tells you when you create it. The Interrail Pass identifier works this way. See Fields Some Cards Need.OPTIONAL: The field is never required.
Pricing with a travel card
Add cards to passengers in the travelCards field of PassengerPlaceholderInput. Send the cards everywhere you send passengers: to journeyOffer and combinedJourneyOffer when you price, and to createBooking.
Cards are set per passenger. If only one traveler in a group has a railcard, attach it to that passenger, and the others get the regular fare. A card that the operator doesn't apply is ignored, and the passenger gets the regular fare. A code that isn't in the catalog is rejected when you create the booking.
Send the same cards when you create the booking as when you priced it. The passengers are compared on their card codes, as well as on their type and age. If the cards differ from the offer's, the booking fails with PASSENGER_MISMATCH. A passholder fare can't be sold to a passenger without the pass, and a regular fare can't be sold to one who is booked as a card holder. The identifier isn't compared, so where an operator prices without it, you can add it when you book.
Example: Get offers for card holders
subscription GetJourneyOffer {
journeyOffer(
journeyId: "dad77557-37d0-4ec9-9b29-a9200b932907"
passengers: [
{ type: ADULT, travelCards: [{ code: "aatc_uk_16_25" }] }
{ type: ADULT }
]
) {
status
itinerary {
... on SegmentCollection {
offers {
id
price {
amount
currency
}
parts {
... on AdmissionPart {
flexibility
serviceClass
comfortClass
}
... on ReservationPart {
flexibility
comfortClass
accommodation {
type
}
}
}
}
}
}
}
}subscription GetJourneyOffer {
journeyOffer(
journeyId: "d534c3c1-ef97-43e5-a415-2f011f283dc6"
passengers: [{ type: ADULT, travelCards: [{ code: "aatc_interrail" }] }]
) {
status
itinerary {
... on SegmentCollection {
offers {
id
price {
amount
currency
}
parts {
... on AdmissionPart {
flexibility
serviceClass
comfortClass
}
... on ReservationPart {
flexibility
comfortClass
accommodation {
type
}
}
}
}
}
}
}
}Creating the booking
Create the booking with the same passengers you priced, including their cards. The booking returns the cards on each passenger, so you can show the traveler what was applied.
Example: Create a booking for card holders
mutation CreateBooking {
createBooking(
offerIds: ["offer_04j29685a4m7g4g3s732k7t137"]
passengers: [
{ type: ADULT, travelCards: [{ code: "aatc_uk_16_25" }] }
{ type: ADULT }
]
) {
id
passengers {
id
type
travelCards {
code
name
identifier
}
}
}
}mutation CreateBooking {
createBooking(
offerIds: ["offer_812304h3w4t5943730n457f4d4"]
passengers: [
{
type: ADULT
travelCards: [{ code: "aatc_interrail", identifier: "PXK7Q2" }]
}
]
) {
id
passengers {
id
type
travelCards {
code
name
identifier
}
}
}
}Fields some cards need
Most cards only need their code. A card with inputFields needs more, usually an identifier: the number on the card or pass.
The Interrail Pass is the main case. Its identifier is CONDITIONAL. Most journeys can be priced without it, so a traveler can look at prices before they find their pass number. A few operators, SJ in Sweden among them, won't price a passholder fare without the number. The offer request then fails with TRAVEL_CARD_FIELD_REQUIRED. Ask for the number and price again.
Whether the identifier is needed to book depends on the operators and the kinds of train in the booking, for example a high-speed reservation. You can't tell in advance, and you don't have to. Create the booking with the cards as you have them. If that succeeds, nothing more is needed. If the identifier is required, the call fails with TRAVEL_CARD_FIELD_REQUIRED, which names the field:
{
"errors": [
{
"message": "Travel card identifier is required.",
"extensions": {
"code": "TRAVEL_CARD_FIELD_REQUIRED",
"args": {
"field": "identifier"
}
}
}
]
}The failed call books nothing. Ask the traveler for the field named in args.field, and create the booking again with the same offer ids while the offers are still valid. If your interface already asks card holders for their number, send it from the start.
Travel cards are fixed at creation
A booking is priced on its passengers' cards, so the cards can't change once the booking exists. Leave travelCards out when updating passengers, and only fill in names, contact details and documents. To book with a different card, or without one, price the journey again with the right passengers and create a new booking from that offer.
This applies to every kind of card, discount cards as well as rail passes. If you send cards that differ from the ones the passenger already has, the call fails with TRAVEL_CARDS_IMMUTABLE, and none of its passenger changes are saved:
{
"errors": [
{
"message": "Travel cards can't be changed on an existing booking. Search again with the right cards and create a new booking.",
"extensions": {
"code": "TRAVEL_CARDS_IMMUTABLE"
}
}
]
}Sending the cards a passenger already has is accepted and changes nothing. Cards are compared on code and identifier, in any order. The input doesn't take the name that a booking's cards come back with, so send code and identifier only.
Everything else counts as a change and fails:
- A different
identifier - An added or removed card, or the same card sent twice
- An empty list or
nullfor a passenger who has cards - A card on a passenger who was booked without one. This would leave a booking priced as a regular ticket, but with a passholder's card on it.
Using the embeds
The embeds take the same passenger objects as the API, so travel cards work there too. Set the element's passengers property from JavaScript, with travelCards on each passenger, and the embed prices and books with the cards. See the passengers attribute of the Journey List.
const list = document.querySelector('aa-journey-list')
list.passengers = [{ type: 'ADULT', travelCards: [{ code: 'aatc_interrail' }] }]