When a Train Operator (TOC) performs a re-accommodation on a booking, an alert is generated and stored for the retailer whole sold it. Retailers are able to periodically check for stored alerts (no more frequently than every 15 mins) and receive high level details of why the alert was generated.
Alerts will be stored for four days before being deleted.
How to make a call to the Retailer Alerts API endpoint to check for stored alerts
Method:
GET
Authentication:
Standard Reservations authentication requirements apply
mTLS certificates are required.
Parameters
| Key |
Value |
| createdAfter |
YYYY-MM-DDThh:mm:ssZ |
Headers required
Authorization: Bearer {{token}}
client_id: {{client_id}
User-Agent: {{User-Agent}}
Example Retailer Alerts request
GET {{URL}}?createdAfter=2026-07-02T10:00:00Z
Example Retailer Alerts response
The below example displays that a booking with reference number GQ516116 had to be re-accomodated by the TOC on the 2nd of July 2026 at 10:53. We can see this due to the changeField value of productItemsUpdated.
If the retailer performs a recall booking using the given reference number, they will be able to see the change details.
{
"latestStoredBookingChange": "2026-07-02T10:53:42Z",
"hasMaxRequestPeriodExceeded": false,
"createdAfter": "2026-07-01T08:07:24Z",
"bookingRevisions": [
{
"bookingReference": "GQ516116",
"revisionNumber": 3,
"revisionCreatedOn": "2026-07-02T10:53:42Z",
"bookingRevisionChanges": [
{
"changeFieldDataType": "uuids",
"uuidsData": [
"9ac0dcb2-61fe-4a2c-af8f-20f48135bbb9"
],
"changedField": "productItemsUpdated"
}
]
}
]
}
Example recall booking response
An example recall booking response for this booking is seen below. From this we can see the notes section reveals the alert was generated because of "type": "AFTERSALES_SEATCHANGE".
Looking at the required products section of the response, it shows the current seat assigned to this booking as D22.
When making a recall booking, only the current seat assignment is displayed but we know there has been a seat change. Therefore, we know the seat has been changed to D22.
{
"data": {
"uniqueTicketNumber": "",
"agent": {
"organisation": "P2_BAT",
"contractCode": "JP",
"username": "r2d2"
},
"outboundBookingTariffLegs": [
{
"uuid": "135f06d3-0618-4fe7-91af-1d3422054e07",
"routeCode": "00000",
"validityStartDate": "2026-07-03",
"journeyConditions": {
"journeyOD": {
"journeyDestination": "6121",
"journeyOrigin": "8487"
}
},
"boardLocation": "LDS",
"classOfTravel": "2",
"validityEndDate": "2026-07-03",
"journeyLeg": {
"carrierCode": "GR",
"alightLocation": "KGX",
"departureDateTime": "2026-07-03T05:00:00+0100",
"rsid": "GR102000",
"arrivalDateTime": "2026-07-03T07:30:00+0100",
"boardLocation": "LDS"
},
"serviceIdentifier": "0:R|GR102000|TRAIN|2026-07-03",
"validityRsid": "GR102000",
"additionalProducts": [],
"alightLocation": "KGX",
"id": "segment_1",
"serviceOriginDate": "2026-07-03",
"requiredProducts": [
{
"canBeRebooked": true,
"isCancelled": false,
"itemRef": 27252829,
"isProvisional": false,
"inventoryClass": "2S",
"tariffCode": "SOS",
"updatedRevision": 3,
"createdRevision": 1,
"description": "ANYTIME S",
"confirmedOn": "2026-07-02T10:53:12Z",
"seat": {
"id": "22",
"coachId": "D"
},
"productBookingId": "GQ516116-001",
"ticketTypeCode": "SOS",
"canBeCancelled": true,
"canChangeName": true,
"canBeUpgraded": true,
"name": "ANYTIME S",
"passengerId": "passenger_1",
"canChangeSeat": true,
"seatProperties": [
"IDR",
"AISL"
],
"productType": "ST",
"uuid": "9ac0dcb2-61fe-4a2c-af8f-20f48135bbb9"
}
]
}
],
"passengers": [
{
"firstName": "",
"lastName": "Norris",
"protectPrivacy": true,
"phoneNumber": "07700900982",
"discountedOrSeasonCode": [],
"createdRevision": 1,
"id": "passenger_1",
"uuid": "ca11091e-5328-39ef-a267-47d6a478cd7f",
"statusCode": "000"
}
],
"notes": [
{
"createdBy": "r2d2",
"createdRevision": 3,
"type": "AFTERSALES_CONFIRM",
"createdOn": "2026-07-02T11:53:42+0100",
"content": ""
},
{
"createdBy": "uyv7rk6iz7878p4yx5raz727y95b4qm52a46vh222z458t8x9z (r2d2)",
"createdRevision": 2,
"type": "AFTERSALES_SEATCHANGE",
"createdOn": "2026-07-02T11:53:36+0100",
"content": ""
}
],
"revisionNumber": 3,
"inboundBookingTariffLegs": [],
"bookingRef": "GQ516116",
"updatedOn": "2026-07-02T10:53:42Z",
"createdOn": "2026-07-02T10:53:09Z",
"confirmedOn": "2026-07-02T10:53:12Z",
"retailersBookingRef": "",
"salesChannelCode": "P2_ACCTS",
"canBeUpgraded": true,
"recordStructureVersion": "v2",
"customer": {
"firstName": "",
"lastName": "Norris",
"phoneNumber": "07700900982",
"updatedRevision": 1,
"initials": "",
"title": ""
}
}
}
Use cases
Use case 1
A TOC is forced to re-accommodate booked passengers due to unexpected out of service carriages. New seat details are amended on the bookings impacted. When this occurs, an entry is made in the Retailer Alerts database with the retailer of the booking also recorded.
When the retailer who sold these bookings makes their next periodic call to the Retailer Alerts API endpoint, they receive the following details from the above Retailer alerts response in each stored alert. The key fields are;
- Booking reference number
- Revision number
- Revision created date and time
- Change field data type
- Change field
The retailer can then use this information to decide whether to recall the booking using the provided reference in order to see all of the booking details. When they have this information, the retailer can inform the customer of the new booking details.
Example high level process to implement Retailer Alerts
The following is one possible implementation of Retailer Alerts and serves as an example only.
- A batch process is created by a retailer to make a request to the Retailer Alerts API endpoint every 15 mins: GET {{URL}}??createdAfter=2026-07-02T10:00:00Z. The batch process is configured so that it amends the value for the createdAfter parameter to match the frequency of requests so they don't receive alerts they have already processed. For example, if the first run is at 10:00 on 2nd July and the next run is at 10:15, it should amend the createdAfter value to 2026-07-02T10:15:00Z.
- The response to this retailer alerts request (see examples above), should be examined for changes that might require customers to be notified of a change. The example response received above is, productItemsUpdated for booking reference GQ516116.
- The retailer decides to recall this booking to get more details and the notes section reveals the alert was generated because of "type": "AFTERSALES_SEATCHANGE". When we look at the required products section of the response, it shows the current seat assigned to this booking as D22.
- Since there was a booking revision involving an after sales seat change and, since a recall booking only ever returns the current seat assigned to the booking, we can know the seat assigned to this booking has been changed to D22.
- The customer can be informed their new seat number is now D22