This guide will lead you to buy a product which has been configured to select seats for customers in a seatmap. We assume you have a seatmap configured properly for being used.

Please make sure you read the Conventions before continuing with this guide.

Prerequisites

You will need an X-API-KEY and a username and password to authenticate.

Steps to complete a purchase

1) Select a product

Get the list of configured products, select one, and remember its _id. The product that you select will determine which Fares (and Fare Classes, if in use) are available when performing a Trip Search and making a purchase.

If you have configured Fare Classes for your passengers, you must select a product with pricingType = "journey" to make use of Fare Classes in the following steps.

2) Get fares

Get available fares for the product that you have selected, using your product's _id as a filter parameter.

3) Select an origin station

Get all possible origin stations for your selected product.

Select an origin station, and remember its _id.

4) Select a destination station

After selecting an 'origin' station, get all possible destination stations that can be reached from that starting point.

This endpoint does not guarantee that there are schedules available between the origin and destination stations - this can only be determined by performing a Trip Search.

Select a destination station, and remember its _id - this will be needed when searching for Trips.

5) Find and select available trips

Find trips that are available for your selected product, fares, origin, destination, and travel date(s).

From the results, select a single departure trip. If searching for a round-trip, also select a return trip. Remember each trip id, a long hash that will look something like this:

{
  "id": "eyJhY2NvdW50SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTUiLCJwcm9kdWN0SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTYiLCJvcmlnaW5JZCI6IjU5MjQ1OTBlOTk4MmNmMjA3YzBkZjQwMCIsImRlc3RpbmF0aW9uSWQiOiI1OTI0NTkyODk5ODJjZjIwN2MwZGY0MDEiLCJmYXJlSWRzIjoiNTkyNDViNTc5OTgyY2YyMDdjMGRmNDAyOjEiLCJkZXBhcnR1cmVEYXRlIjoiMjAxNy0xMC0yOCIsImRlcGFydHVyZVRpbWUiOiIwOTowMCIsImNoYW5uZWwiOiJ3ZWJzYWxlcyIsInNlZ21lbnRzIjpbeyJyb3V0ZUlkIjoiNTkyNDU5NDE1MDJjYzcxMDcyMDAwMDFlIiwic2NoZWR1bGVJZCI6IjU0MGZkNWQ5LThiZDEtNGIxNS05ZDZlLTJiNzk3ZmFhYWM1NyIsIm9yaWdpbiI6IkJlcmxpbiBDZW50cmFsIGJ1cyBzdGF0aW9uIChaT0IpIiwiZGVzdGluYXRpb24iOiJXYXJzYXcgV2VzdCBidXMgc3RhdGlvbiJ9XSwidGlja2V0VHlwZSI6Im9uZXdheSJ9"
}

If Fare Classes are being used, you will need to select the passenger's desired Fare Class . Select only one Fare Class from the trip search results, and remember it's id. The id will need to be specified when adding the item to the shopping cart.

At this time, if you are searching for a round-trip, the Fare Class that is selected for the passenger's Outbound and Return Trip must be the same.

6) Select seats

If departure or/and return trip selected has a seatmap associated you have to select seats for all passengers.

6.1) Iframe "old" seatmap version

For seats selection you will need to use the seatmap iframe API, at Seatmap iframe documentation you can find all the information about how to import and use it.

Using seatmap iframe API select a seat for all passengers and remember this information for each one:
seatMapId
rowLabel
seatNumber
seatId
sectionName
scheduleId

All this information will be needed when add items to the cart. At Seatmap iframe documentation you will find where to get all of these fields when interact with seatmap iframe. Also, if there are seat fees configured for the account then they will be available with these endpoints. Each seat in the seatmap will have a 'fee' property where the configured seat fee Id will be available.

IMPORTANT: In the case of redeemable items, open return and flexpass, the seat fee will not be applied even though a seat has a fee configured.

6.2) "New" seatmap version

For reservation products ONLY, working on accounts having "seatmapsNewDesign" flag turned ON under preferences in "accounts" collection or those working with the simplified sales flow (it can be activated through "Use simplified sales flow with reservation products" checkbox under admin/setup), the new seatmap version will be activated, when select passenger seats option is required. For seats selection you will need to use the seatmap new design. At New seatmap version documentation you can find all the information about how to import and use it.

Using "new" seatmap version select a seat for all passengers and remember this information for each one:
seatMapId
sectionId
rowLabel
seatNumber
seatId
sectionName
seatId
seatRow
seatCol
row
col
sectionName
seatFeeValue
seatFeeName
seatFeeId
seatClass
seatClassName
scheduleId

All this information will be needed when adding items to the cart and can find on every single seat returned by the seatmap events. Here New seatmap version documentation you will find the list of events you could attach to. Also, if there are seat fees configured for the account then they will be available with these endpoints. Each seat in the seatmap will have a 'fee' property where the configured seat fee Id will be available. Something similar happens with seat classes. Here you can find endpoints with the related information.

IMPORTANT: In the case of redeemable items, open return and flexpass, the seat fee will not be applied even though a seat has a fee configured.

7) Add an item to the cart

When add items in the cart make sure that you are sending the seats information for each passenger under seats field. This passenger field is an Array because a passenger can have more than one seat in a purchase, in a round-trip or a connection trip for example.

Add the selected trip to the shopping cart.

Remember the cartId and the total from the response. You will need this information to complete the order.

8) Retrieve payment types

To complete the order, first retrieve the available payment types and select one. Remember, these must be the payment types for the main provider, "Provider A" in our example.

9) Complete the order

Create an order (pay for the items in the cart) using one of the available payment types.

Once the payment is accepted, the booking is complete.

10) Download tickets

In some cases you may want to download tickets for the booking. The tickets are downloaded as PDF files.