Working with the cart

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 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();
}