Skip to content

[EXTRAS-37] Add travel book event docs #1532

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[EXTRAS-37] Add travel book event docs #1532

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aebc946
feat: add travel book event docs
Jul 17, 2025
d0d2456
feat: add prerelease header
leorpedroso Jul 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
304 changes: 304 additions & 0 deletions src/event-topics/travel/v4.travel-book-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,304 @@
---
title: Concur Travel Booking Events
layout: reference
---

{% include prerelease.html %}

## <a name="overview"></a>Overview


This page will host the documentation for the travel booking information related events that are publicly available on the `public.concur.travel.book` topic in the Event Subscription Service (ESS).
Subscribers to this topic will receive events when travel bookings are performed within SAP Concur.

To subscribe to these events follow the steps described on the [Event Subscription Service v4](/api-reference/ess/v4.event-subscription.html) page.

## <a name="limitations"></a>Limitations
Access to this documentation does not provide access to the subscription.

## <a name="scope-usage"></a>Scope Usage

Scopes required to interact with this topic:

Name | Description
----------------------------|------------
`events.topic.read` | Read events.
`travel.trips.booking.read` | Read booking data.

## <a name="events"></a>Events

The topic `public.concur.travel.book` contains events for air and hotel bookings at the moment they are completed.

## <a name="schema"></a>Schema

### <a name="schema-booking-event"></a>Schema for Booking Event

Name |Type |Format |Description
---------------|--------|----------------------------------------------|-----------
`id` |`string`|`GUID` |Uniquely identifies the published event.
`correlationId`|`string`|`GUID` |Uniquely identifies the booking request to aid in workflow tracing and troubleshooting.
`eventType` |`string`|- |Identifies the booking event type. Supported values: `travelBookingCompleted`.
`topic` |`string`|- |Topic for subscription. Supported values: `public.concur.travel.book`.
`timeStamp` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Booking event time in UTC.
`facts` |`object`|[Booking Facts](#schema-booking-facts) |Facts for the booking event.
`route` |`string`|- |Routes traffic through the service call tree. Supported values: `stable`.

### <a name="schema-booking-facts"></a>Schema for Booking Facts

Name |Type |Format |Description
-------------------|---------|------------------------------------------------|-----------
`companyId` |`string` |`GUID` |Uniquely identifies the company of the traveler.
`userId` |`string` |`GUID` |Uniquely identifies the user performing the booking. Note: If the travel is booked by a delegate, this will be the traveler's ID. In cases where a profiled user is booking on behalf of a nonprofiled guest, this will be the user performing the booking.
`delegateUserId` |`string` |`GUID` |Uniquely identifies the delegate user performing this action, if applicable.
`type` |`string` |- |Type of the event. Supported values: `concur.travel.trip.Booking.Completed.v1`.
`version` |`string` |- |Semantic version of the event schema. Example: `1.2.0`.
`trip` |`object` |[TripDetails](#schema-trip-details) |Details about the trip the booking belongs to.
`bookings` |`array` |[BookingDetails](#schema-booking-details) |List of bookings added to the trip.

### <a name="schema-booking-details"></a>Schema for Booking Details

Name | Type | Format | Description
----------|----------|--------------------------------------------------------------------------------------------------------|------------
`id` | `string` | `GUID` | Uniquely identifies the air booking.
`type` | `string` | - | Type of the booking. Supported values: `Air`, `Hotel`.
`details` | `object` | [AirBookingDetails](#schema-air-booking-details), [HotelBookingDetails](#schema-hotel-booking-details) | Details about the booking. The object's type depends on the value of the `type` field. For example, if `type` is `Air`, then `details` will be of type `AirBookingDetails`.

### <a name="schema-air-booking-details"></a>Schema for Air Booking Details

Name |Type |Format |Description
--------------|-------|------------------------------------------------|-----------
`journeys` |`array`|[AirJourneyDetails](#schema-air-journey-details)|List of air journey details. A journey is a portion of a passenger's itinerary between origin and destination. There would be one journey for one-way, two journeys for round trip, and (n+1) journeys for a multi-city trip, where n stands for the number of stopovers. Each journey contains one or more segments.

### <a name="schema-air-journey-details"></a>Schema for Air Journey Details

Name |Type |Format | Description
|----------------------|---------|------------------------------------------------|------------
|`origin` |`string` |- |IATA airport code of the airport of initial departure.
|`destination` |`string` |- |IATA airport code of the last airport in the journey.
|`departureDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will depart from the point of departure, local time (without offset).
|`departureDateTimeUtc`|`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will depart from the point of departure, UTC time.
|`arrivalDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will arrive at the point of arrival, local time (without offset).
|`arrivalDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will arrive at the point of arrival, UTC time.
|`international` |`boolean`|- |Whether the journey is international or not. True for international (crosses a country), False for domestic (within the country).
|`index` |`integer`|- |Zero-based index, representing the order of the journey withing the booking, that the passenger will take to get from booking origin to booking destination(s).
|`segments` |`array` |[AirSegmentDetails](#schema-air-segment-details)|List of air segment details. Segment refers to the portion of a passenger's itinerary that represents a single flight. Technical stops are ignored.

### <a name="schema-air-segment-details"></a>Schema for Air Segment Details

Name |Type |Format |Description
|-----------------------|---------|---------------------------------|------------
|`origin` |`string` |- |IATA airport code of the point of departure.
|`destination` |`string` |- |IATA airport code of the point of arrival.
|`departureDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date traveler will depart from the point of departure, local time (without offset).
|`departureDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will depart from the point of departure, UTC time.
|`arrivalDateTime` |`string` |`YYYY-MM-DDTHH:MM:SS.f` |Date and time traveler will arrive at the point of arrival, local time (without offset).
|`arrivalDateTimeUtc` |`string` |`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time traveler will arrive at the point of arrival, UTC time.
|`marketingFlightNumber`|`string` |- |The flight number assigned by the airline that sells the ticket.
|`marketingCarrier` |`object` |[AirCarrier](#schema-air-carrier)|Air carrier of the flight segment.
|`international` |`boolean`|- |Whether the segment is international or not. True for international (crosses a country), False for domestic (within the country).
|`index` |`integer`|- |Zero-based index, representing the order of the segment withing the journey.

### <a name="schema-air-carrier"></a>Schema for Air Carrier

Name |Type |Format| Description
|----------|--------|------|------------
|`iataCode`|`string`| - |IATA airline carrier code. Example: AA, VA, LH
|`name` |`string`| - |Name of the air carrier.

### <a name="schema-hotel-booking-details"></a>Schema for Hotel Booking Details

Name |Type |Format |Description
---------------------|--------|-------------------------------------|-----------
`hotel` |`object`|[HotelDetails](#schema-hotel-details)|Details about the hotel.
`checkInDateTime` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-in in local time (without offset).
`checkOutDateTime` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-out in local time (without offset).
`checkInDateTimeUtc` |`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-in in UTC time.
`checkOutDateTimeUtc`|`string`|`YYYY-MM-DDTHH:MM:SS.fZ` |Date and time representing the time of check-out in UTC time.

### <a name="schema-hotel-details"></a>Schema for Hotel Details

Name |Type |Format |Description
----------|--------|-----------------------------------------|-----------
`name` |`string`|- |Name of the hotel.
`address` |`object`|[AddressDetails](#schema-address-details)|Details about the hotel address.

### <a name="schema-address-details"></a>Schema for Hotel Address Details

Name | Type | Format | Description
-------------------------|----------|------------------------------------------|------------
`address1` | `string` | - | Address line 1.
`address2` | `string` | - | Address line 2.
`administrativeAreaName` | `string` | - | Represents the state or federal land or province the hotel is located in.
`postalCode` | `string` | - | Postal code of the hotel. Between 3 and 10 alphanumeric characters, spaces, and hyphens, which covers most international postal code formats.
`localityName` | `string` | - | Name of the city, town, village, or other locality the address is located in.
`countryCode` | `string` | ISO 3166-1 alpha-2 | Two letter code representing the country the hotel is located in. Uses ISO 3166-1 alpha-2 standard. Example: BR.
`geoCoords` | `object` | [GeoLocation](#schema-hotel-geolocation) | Geographic coordinates of the hotel

### <a name="schema-hotel-geolocation"></a>Schema for Hotel Address GeoLocation

Name | Type | Format | Description
-------|----------|---------|------------
`lat` | `number` | `float` | Latitude of the location.
`long` | `number` | `float` | Longitude of the location.

### <a name="schema-trip-details"></a>Schema for Trip Details

Name|Type |Format|Description
----|--------|------|-----------
`id`|`string`|`GUID`|Uniquely identifies the trip.

## <a name="sample-events"></a>Sample Events

### <a name="sample-air-event"></a>Sample Air Booking Event

Sample roundtrip air booking

```json
{
"id": "51519e89-2c1d-47ec-bd93-7c4ace9c57e6",
"correlationId": "b2fd900a-5935-46fc-8d29-599de9864e21",
"topic": "concur.travel.book",
"eventType": "travelBookingCompleted",
"timeStamp": "2025-04-01T11:01:01.000Z",
"route": "stable",
"facts": {
"userId": "b7d12989-0489-471a-81cd-175f8b78afa5",
"companyId": "ab83bc5f-f66e-4ce0-9dcc-7dbf0195e061",
"delegateUserId": "e5315ec2-5033-4197-b15b-4cec00b838f6",
"type": "concur.travel.trip.Booking.Completed.v1",
"version": "1.0.0",
"trip": {
"id": "8585c3ca-62bd-4585-8f18-f85e331fa7fa"
},
"bookings": [
{
"id": "5040b878-da00-47c7-8676-e0f6c67885b5",
"type": "Air",
"details": {
"journeys": [
{
"origin": "EWR",
"destination": "LAX",
"departureDateTime": "2025-07-01T00:00:00-03:00",
"departureDateTimeUtc": "2025-07-01T05:00:00Z",
"arrivalDateTime": "2025-07-01T16:00:00-03:00",
"arrivalDateTimeUtc": "2025-07-01T21:00:00Z",
"international": false,
"index": 0,
"segments": [
{
"origin": "EWR",
"destination": "DEN",
"departureDateTime": "2025-07-01T00:00:00-03:00",
"departureDateTimeUtc": "2025-07-01T05:00:00Z",
"arrivalDateTime": "2025-07-01T03:00:00-03:00",
"arrivalDateTimeUtc": "2025-07-01T08:00:00Z",
"marketingFlightNumber": "1111",
"marketingCarrier": {
"iataCode": "AA",
"name": "American Airlines"
},
"international": false,
"index": 0
},
{
"origin": "DEN",
"destination": "LAX",
"departureDateTime": "2025-07-01T05:00:00-03:00",
"departureDateTimeUtc": "2025-07-01T10:00:00Z",
"arrivalDateTime": "2025-07-01T16:00:00-03:00",
"arrivalDateTimeUtc": "2025-07-01T21:00:00Z",
"marketingFlightNumber": "2222",
"marketingCarrier": {
"iataCode": "SW",
"name": "SouthWest Airlines"
},
"international": false,
"index": 1
}
]
},
{
"origin": "LAX",
"destination": "EWR",
"departureDateTime": "2025-07-07T00:00:00-03:00",
"departureDateTimeUtc": "2025-07-07T05:00:00Z",
"arrivalDateTime": "2025-07-07T16:00:00-03:00",
"arrivalDateTimeUtc": "2025-07-07T21:00:00Z",
"international": false,
"index": 1,
"segments": [
{
"origin": "LAX",
"destination": "EWR",
"departureDateTime": "2025-07-07T00:00:00-03:00",
"departureDateTimeUtc": "2025-07-07T05:00:00Z",
"arrivalDateTime": "2025-07-07T16:00:00-03:00",
"arrivalDateTimeUtc": "2025-07-07T21:00:00Z",
"marketingFlightNumber": "3333",
"marketingCarrier": {
"iataCode": "DL",
"name": "Delta Airlines"
},
"international": false,
"index": 0
}
]
}
]
}
}
]
}
}
```

### <a name="sample-hotel-event"></a>Sample Hotel Booking Event

```json
{
"id": "51519e89-2c1d-47ec-bd93-7c4ace9c57e6",
"correlationId": "b2fd900a-5935-46fc-8d29-599de9864e21",
"eventType": "travelBookingCompleted",
"topic": "concur.travel.book",
"timeStamp": "2025-04-01T11:01:01.000Z",
"route": "stable",
"facts": {
"companyId": "ab83bc5f-f66e-4ce0-9dcc-7dbf0195e061",
"userId": "b7d12989-0489-471a-81cd-175f8b78afa5",
"delegateUserId": "e5315ec2-5033-4197-b15b-4cec00b838f6",
"type": "concur.travel.trip.Booking.Completed.v1",
"version": "1.0.0",
"trip": {
"id": "8585c3ca-62bd-4585-8f18-f85e331fa7fa"
},
"bookings": [
{
"id": "5040b878-da00-47c7-8676-e0f6c67885b5",
"type": "Hotel",
"details": {
"hotel": {
"name": "The Ritz-Carlton New York, Central Park",
"address": {
"address1": "50 Central Park S",
"address2": "",
"administrativeAreaName": "NY",
"postalCode": "10019",
"localityName": "New York",
"countryCode": "US",
"geoCoords": {
"lat": 40.755630,
"long": -73.977580
}
}
},
"checkInDateTime": "2025-04-02T15:00:00",
"checkInDateTimeUtc": "2025-04-02T20:00:00Z",
"checkOutDateTime": "2025-04-05T16:00:00",
"checkOutDateTimeUtc": "2025-04-05T21:00:00Z"
}
}
]
}
}
```