Please make sure you read the Conventions before continuing with this guide.
Requirements.
You will need an X-API-KEY and a JWT token to interact with the shopping cart.
Adding an item
Use the /sales/cart endpoint of the Sales Bucket to add items to the shopping cart.
The first call will create a shopping cart and return information about it, including the cartId:
Replace the placeholders in the payload above with information returned by other APIs during the purchase reservation flow.
The passengers array contains a list of passenger information retrieved from the travellers. You will need one passenger entry for each journey that is being travelled.
Note that the passenger's fareClassIds only need to be specified if Fare Classes are in use. Otherwise, this parameter should be left out of the request.
Adding an item with seatmaps
Use the /sales/cart endpoint of the Sales Bucket to add items to the shopping cart.
The first call will create a shopping cart and return information about it, including the cartId:
Replace the placeholders in the payload above with information returned by other APIs during the purchase reservation flow.
The passengers array contains a list of passenger information retrieved from the travellers. You will need one passenger entry for each journey that is being travelled.
When working with seatmaps the passenger will have a property seats in which the information about the trip and the seatmap has to be included (tripId, seatMapId, sectionId, sectionName, rowLabel, seatNumber, seatId, scheduleId).
Note that the passenger's fareClassIds only need to be specified if Fare Classes are in use. Otherwise, this parameter should be left out of the request.
The syncEntryId should be a unique identifier for the passenger perfered a UUID.
Adding an item with open return
Use the /sales/cart endpoint of the Sales Bucket to add items to the shopping cart.
The first call will create a shopping cart and return information about it, including the cartId:
Replace the placeholders in the payload above with information returned by other APIs during the purchase reservation flow.
Note that the payload has to have any return information as null (selectedTrips.returnTripId, passengers.fareClassIds.return), openReturn: true and roundTrip: false.
Adding an item with SSRs
Use the /sales/cart endpoint of the Sales Bucket to add items to the shopping cart.
The first call will create a shopping cart and return information about it, including the cartId:
Replace the placeholders in the payload above with information returned by other APIs during the purchase reservation flow.
The passengers array contains a list of passenger information retrieved from the travellers. You will need one passenger entry for each journey that is being travelled.
Each passenger can have none or more SSRs.
There are different types of SSRs, text based, boolean based or quantity based.
Adding an item with associated (paid-in) items as SSRs
Use the /sales/cart endpoint of the Sales Bucket to add items to the shopping cart.
The first call will create a shopping cart and return information about it, including the cartId:
Replace the placeholders in the payload above with information returned by other APIs during the purchase reservation flow.
The passengers array contains a list of passenger information retrieved from the travellers. You will need one passenger entry for each journey that is being travelled.
Each passenger can have none or more associated (paid-in) items.
About the information we must pass into the items array, notice they have the same structure as ssrs (as listed in previous sample), and only the _id field is required so far. The rest of the fields were kept to maintain compatibility.
In order to determine which items can be associated, we need to look for those having the right type: paid_in, and they should also have the right associatedProductId matching the id of the product we are associating the item with. Finally, only those items having attachToTicket set as true will be able to have associated products.
Adding a reservation item when using Dynamic forms (with or without people lookup)
To learn how to use Dynamic forms for the passenger screen go to Using a dynamic form.
If you want to do a people lookup to augment the passenger information you will need to perform a GET to /account/people-lookups.
You will first have do a post for each passenger to the /accounts/people-lookups endpoint to create or update the people lookup record.
For extra info of how to work with peopleLookup: Using people lookup
In the reservation object you will add the dynamicFormId and in the passengers array for each passenger you will add the peopleLookupId that is returned with each post done above.
In the parcel object you will add the peopleLookupId that is returned with each post done above in the extra/from and extra/to property
Here is an example of how you can add a reservation item to a cart:
Reservation Body
"items": {
"reservation": [{
"productId": "{{reservationProductId}}",
"from": {
"_id": "{{originStationId}}"
},
"to": {
"_id": "{{destinationStationId}}"
},
"promo": "",
"roundTrip": false,
"passengers": [
{
"fareId": "{{fareId}}",
"ssrs": [],
"seats" : [],
"firstName": "{{peopleLookupFirstName1}}",
"lastName": "{{peopleLookupLastName1}}",
"email": "{{peopleLookupEmail1}}",
"documentTypeId": "{{documentTypeId1}}",
"documentNumber": "{{documentNumber1}}",
"phone": "{{phone1}}",
"peopleLookupId": "{{peopleLookupId1}}"
},
{
"fareId": "{{fareId}}",
"ssrs": [],
"seats" : [],
"firstName": "{{peopleLookupFirstName2}}",
"lastName": "{{peopleLookupLastName2}}",
"email": "{{peopleLookupEmail2}}",
"documentTypeId": "{{documentTypeId2}}",
"documentNumber": "{{documentNumber2}}",
"phone": "{{phone2}}",
"peopleLookupId": "{{peopleLookupId2}}"
}
],
"selectedTrips": {
"departureTripId": "{{departureTripId}}",
"returnTripId": ""
},
"dynamicFormId": "{{dynamicFormId}}",
"dateFrom": "{{departureDate}}",
"dateTo" : "{{returnDate}}"
}]
}
}
Parcel Body
"items": {
"parcel": [
{
"applyInsurance": false,
"channel": "backoffice",
"comments": "",
"declaredValue": "0",
"displayUnits": {
"dimensions": "in",
"weight": "kg"
},
"extra": {
"from": {
"address": "someAddress",
"city": "someCity",
"companyId": "",
"companyName": "",
"country": {
"_id": "63d7e6b5998ba6d518a3d0e6",
"ISO": "CA",
"name": "Canada"
},
"documentNumber": "111",
"documentType": "someDocumentTypeName",
"documentTypeId": "someDocumentTypeId",
"email": "mail@mail.com",
"firstName": "John",
"lastName": "Doe",
"peopleLookupId": "{{somePeopleLookupId}}",
"phoneNumber": "123-123-1234",
"province": "Ontario",
"selectedCountryId": "63d7e6b5998ba6d518a3d0e6",
"shipTrackNotifications": {
"delivered": false,
"inTransit": false
},
"zipCode": "666"
},
"to": {
"address": "Queen's Avenue 1654",
"city": "Toronto",
"companyName": "",
"country": {
"_id": "63d7e6b5998ba6d518a3d0e6",
"ISO": "CA",
"name": "Canada"
},
"documentNumber": "1111",
"documentType": "DNI",
"documentTypeId": "6419e665894e8e4835ce3a4a",
"email": "",
"firstName": "Anna",
"lastName": "Julia",
"peopleLookupId": "{{anotherPeopleLookupId}}",
"phoneNumber": "",
"province": "Ontario",
"selectedCountryId": "63d7e6b5998ba6d518a3d0e6",
"shipTrackNotifications": {
"delivered": false,
"inTransit": false
},
"zipCode": "E5B0B6"
}
},
"extraInfo": {
"label": "??product-extraInfoLabel-5b9ab527c9a3ce572400043e-f67a2089-2130-494b-87af-2a82791e09ff??",
"value": ""
},
"from": {
"_id": "5b9ab60e951628200ca0dfae",
"address": "Saskatchewan 564",
"city": "Edmonton",
"country": "CA",
"key": "5b9ab60e951628200ca0dfae",
"province": "Alberta",
"value": "Edmonton",
"zip": "E5B0B6",
"zone": "1"
},
"manualFees": [],
"parcels": [
{
"fareId": "6148dc78d0662313fd04e9b4",
"measure": {
"height": {
"unit": "in",
"value": 0
},
"length": {
"unit": "in",
"value": 0
},
"width": {
"unit": "in",
"value": 0
}
},
"weight": {
"unit": "kg",
"value": 0
}
}
],
"productId": "5bc72abd6c243a273561f4bd",
"serviceTypeId": "61044f7ed36df12c39360a07",
"serviceTypeName": "Prepaid Station to Station",
"to": {
"_id": "5b9ab625951628200ca0dfaf",
"address": "Queen's Avenue 1654",
"city": "Toronto",
"country": "CA",
"key": "5b9ab625951628200ca0dfaf",
"province": "Ontario",
"value": "Toronto",
"zip": "E5B0B6",
"zone": "Downtown two"
}
}
]
}
}
const path = "https://sandbox-api.betterez.com/sales/cart"
const jwtToken = "";
const apiKey = "";
const headers = {
"authorization": `Bearer ${jwtToken}`,
"Content-Type": "application/json",
"Accept": "*/*",
"x-api-key": `${apiKey}`
};
async function addItemToCart(){
const response = await fetch(path, {
method: "POST",
headers,
body: JSON.stringify(body)
});
return response.json();
}