Please make sure you read the Conventions before continuing with this guide.
Requirements.
You will need an X-API-KEY.
Rules
These are existing rules that may change in the future, which include:
The product family must be a reservation.
You cannot change the fare type.
You cannot make a change if the end result is a less expensive trip.
If the ticket is part of a group of tickets that require a companion, you cannot make a change.
For a multi-leg trip (connex), if the trip has already started, you cannot make a change.
1) Get data for an ticket change.
You will interact with the /operations/trip-change-info endpoint of the Operations Bucket to create a changeset for changing the date of a trip.
The value for returnDate is only needed when the original ticket is part of a roundtrip and we want to change both departure and return.
When successful, a json object will be returned. This object will contain most of the data required to create a cart item in a later step. This includes whether a departure or return trip can be changed (canChange: true).
Sample Response :
{
"ticketToChangeInfo": {
"productFamily": "reservation",
"ticketNumber": "ZZZ49M",
"type": "roundtrip",
"productId": "59837157936abc274d077777",
"journeyId": "5e5e7af9-a55f-45bc-90c3-72f49b77745",
"originId": "598cb1c9a23a8d777fb8f9ec",
"destinationId": "598cc7c7a23a8d777fb8fa52",
"ticketId": "5ad4eeba414c35ef42b7a777"
},
"operationsData": [
{
"passenger": {
"firstName": "Firstname-test",
"lastName": "Lastname-test",
"email": "testemail@betterez.com",
"fare": "Adult",
"fareId": "7770e67f697aa69e4ff86116",
"comments": "",
"ssrs": []
},
"departure": {
"ticketId": "5ad4eeba414c35ef42b7a777",
"ticketNumber": "ZZZ49M",
"expirationDate": "2018-04-21",
"canChange": true,
"price": 2295000
},
"return": {
"ticketId": "5ad4eeba414c35ef42b7a768",
"ticketNumber": "ZZZKHK",
"expirationDate": "2018-04-22",
"canChange": true,
"price": 2295000
}
}
],
"newDepartureDate": "{yyyy-mm-dd}"
}
2) Get available trips.
You will interact with the /inventory-trips/trips endpoint of the Inventory Bucket to get a list of trips that are available.
The returnDate can be omitted if it is a one way trip.
The departureDate should match the value of newDate from step 1.
minDeparturePrice will be the price for the departure object in the response above.
minReturnPrice will be the minimum price for the return object in the response above.
When successful, a json object is returned. This object will contain available departure and return trips.
The data required for the next step is the selected departure trip id (trips.departures[x].id) and return trip id, if applicable (trips.returns[x].id).
Sample Response :
{
"trips":{
"departures":[
{
"segments":[
{
"routeId":"testc9657c97f1de44000073",
"name":"test42f5-37aa-4544-b6e0-113426ca737d",
"scheduleDisplayName":"32",
"from":"Alban",
"to":"Yorkdale",
"seatMapId":"",
"departureDate":"2018-01-12",
"stops":[
{
"scheduleDisplayName":"32",
"departureDate":"2018-01-12",
"departure":"17:20",
"name":"Alban",
"arrival":"17:30",
"to":"Bigwood",
"minsWaiting":"0m",
"fromId":"testad1ca23a8d704fb8f9e8",
"toId":"testb21aa23a8d704fb8f9ee"
},
{
"scheduleDisplayName":"32",
"departureDate":"2018-01-12",
"departure":"17:30",
"name":"Bigwood",
"arrival":"17:35",
"to":"Pickerel River Rd",
"minsWaiting":"0m",
"fromId":"testb21aa23a8d704fb8f9ee",
"toId":"testc302a23a8d704fb8fa39"
}
],
"price":7250000,
"fares":[
{
"id":"teste67f697aa69e4ff86116",
"name":"Adult",
"value":7250000,
"valueToDisplay":"72.50",
"lexiconKeys":{
"name":"fares-name-test7157936abc274d000050-7bdc6c86-d87e-497a-8685-58b6c7e44df1",
"description":"fares-description-test7157936abc274d000050-477b82a8-6c10-4ff9-b7eb-665483487b81",
"requiresCompanionErrMsg":"fares-requiresCompanionErrMsg-test7157936abc274d000050-10ed0d34-4940-4af7-8fa8-cc6ef50c749c"
}
}
],
"fareClasses":[
],
"scheduleTime":"16:30",
"manifestDay":0,
"buckets":[
],
"fareRules":[
],
"capacity":50,
"load":0
},
{
"routeId":"test22a3df260ee44400001c",
"name":"test91b8-2f3a-4157-b9ec-feed52bef589",
"scheduleDisplayName":"799",
"from":"Yorkdale",
"to":"Barrie",
"seatMapId":"",
"departureDate":"2018-01-13",
"stops":[
{
"scheduleDisplayName":"799",
"departureDate":"2018-01-13",
"departure":"00:01",
"name":"Yorkdale",
"arrival":"01:00",
"to":"Barrie",
"minsWaiting":"136m",
"fromId":"testcbd9a23a8d704fb8fa5d",
"toId":"testb1c9a23a8d704fb8f9ec"
}
],
"price":2295000,
"fares":[
{
"id":"teste67f697aa69e4ff86116",
"name":"Adult",
"value":2295000,
"valueToDisplay":"22.95",
"lexiconKeys":{
"name":"fares-name-test7157936abc274d000050-7bdc6c86-d87e-497a-8685-58b6c7e44df1",
"description":"fares-description-test7157936abc274d000050-477b82a8-6c10-4ff9-b7eb-665483487b81",
"requiresCompanionErrMsg":"fares-requiresCompanionErrMsg-test7157936abc274d000050-10ed0d34-4940-4af7-8fa8-cc6ef50c749c"
}
}
],
"fareClasses":[
],
"scheduleTime":"23:35",
"manifestDay":-1,
"buckets":[
],
"fareRules":[
],
"capacity":50,
"load":0
}
],
"arrival":"01:00",
"capacity":"",
"departure":"17:20",
"duration":"07:40",
"fareRules":[
],
"from":"Alban",
"to":"Barrie",
"load":"",
"manifestDay":0,
"fares":[
{
"id":"teste67f697aa69e4ff86116",
"name":"Adult",
"value":9545000,
"valueToDisplay":"95.45",
"lexiconKeys":{
"name":"fares-name-test7157936abc274d000050-7bdc6c86-d87e-497a-8685-58b6c7e44df1",
"description":"fares-description-test7157936abc274d000050-477b82a8-6c10-4ff9-b7eb-665483487b81",
"requiresCompanionErrMsg":"fares-requiresCompanionErrMsg-test7157936abc274d000050-10ed0d34-4940-4af7-8fa8-cc6ef50c749c"
}
}
],
"fareClasses":[
],
"id":"tripId_string",
"tripSegmentsId":"tripSegmentsId_string",
"price":"9545000"
}
],
"returns":[]
}
}
3) Create a new cart, with the item to be updated.
For this task, you will need to include a Bearer token in the header. (JWT token how to)
Please note, that for this change to be completed successfully, it must be the only item in the cart.
You will interact with the /sales/cart endpoint of the Sales Bucket to create a new cart with the trip change.
Data obtained from the previous requests will be required here.
When successful, a json cart object will be returned.
Sample Response :
{
"cartId":"test3504021149e422f129ce",
"total":"58.73",
"items":{
"tickets":[
{
"from":"Alban",
"to":"Yorkdale",
"date":"2018-01-12",
"productId":"test7157936abc274d000051",
"scheduleId":"test815d-7ebf-4deb-a120-96158a2648f1",
"operationId":"test3c5d-3940-4668-98ed-802c4ed7b692",
"productFamily":"reservation",
"routeId":"testc9657c97f1de44000073",
"journeyFrom":"Alban",
"journeyTo":"Barrie",
"journeyOrder":0,
"fares":[
{
"id":"teste67f697aa69e4ff86116",
"name":"Adult",
"qty":1,
"total":"72.50"
}
],
"passengers":[
{
"firstName":"Adult",
"lastName":"Change",
"email":"test@change.com",
"name":"Adult Change",
"fare":"Adult",
"fareId":"teste67f697aa69e4ff86116",
"qty":1,
"total":"72.50",
"fareClassName":null,
"fareClassTerms":null,
"fareClassId":null
}
],
"total":"72.50"
},
{
"from":"Yorkdale",
"to":"Barrie",
"date":"2018-01-12",
"productId":"test7157936abc274d000051",
"scheduleId":"testb6c7-bc3f-4898-840f-28c8bbae580e",
"operationId":"test3c5d-3940-4668-98ed-802c4ed7b692",
"productFamily":"reservation",
"routeId":"test22a3df260ee44400001c",
"journeyFrom":"Alban",
"journeyTo":"Barrie",
"journeyOrder":1,
"fares":[
{
"id":"teste67f697aa69e4ff86116",
"name":"Adult",
"qty":1,
"total":"22.95"
}
],
"passengers":[
{
"firstName":"Adult",
"lastName":"Change",
"email":"test@change.com",
"name":"Adult Change",
"fare":"Adult",
"fareId":"teste67f697aa69e4ff86116",
"qty":1,
"total":"22.95",
"fareClassName":null,
"fareClassTerms":null,
"fareClassId":null
}
],
"total":"22.95"
}
],
"redeemableItems":[
],
"parcels":[
],
"insurance":[
],
"items":[
]
},
"itemIds":{
"test7157936abc274d000051":[
"test3504021149e422f129cf",
"test3504021149e422f129d0"
]
},
"feesTotal":"14.32",
"taxesTotal":"14.27",
"promosTotal":"0.00",
"creditsTotal":"-65.31",
"fees":[
{
"name":"Change Fee",
"code":"Change Fee Percent",
"total":"14.32",
"qty":1,
"lexiconKeys":{
"name":"fees-name-test7157936abc274d000050-89122c89-96d8-4d0e-87ec-6fd2be9a1324"
}
}
],
"taxes":[
{
"name":"HST",
"total":"14.27",
"value":"13%"
}
],
"promos":[
],
"credits":[
{
"name":"Change credit",
"valueType":"$",
"value":-6531000,
"reason":{
"id":"BT4KTV",
"object":"ticket",
"description":"change",
"_id":"test67346b0c6032442b9ef7"
},
"calculated":-6531000,
"total":"-65.31"
}
],
"seats":[
"scheduleId-test815d-7ebf-4deb-a120-96158a2648f1-",
"scheduleId-testb6c7-bc3f-4898-840f-28c8bbae580e-"
],
"cutOffDate":"2018-01-12",
"cutOffTime":"11:05"
}
The numbers explained: From the above json, the total of 58.73 comes from the tickets prices (72.50 + 22.95) + fees (14.32) + taxes (14.27) - credits (65.31).
Notes
Now that the new reservation item has been created in the cart, you can proceed with payment and submission of the cart. See making a reservation purchase flow for further details.
In the case of a zero pay situation (the new trip price is the same as the old, and no real payment is required), you can send an empty payments array in the object used for POST sales/cart. See create an order for details of that endpoint.