Skip to content

How a booking works

The lifecycle of a partner booking, from quote to completed journey.

Updated · 4 min read

This page explains how a transfer goes from a price on your site to a completed ride, and which call moves it forward at each stage. Read it before you start building; the task guides that follow show each call in detail.

Quotes, bookings and journeys

  • A quote is a price for one vehicle category on one route at one time. One quote request returns a quote for each vehicle category that is available. Each quote is valid until its expires time.
  • A booking is what you create from one or more quotes. It has a partnerReference (your own order number) and a code that the traveller can quote to Transferz.
  • A journey is one ride from A to B. Each quote you book becomes one journey. A return trip is one booking with two journeys. Journey codes start with the booking code, for example TZ7K4QM-1.

Every journey starts or ends at a hub: an airport, port or station. You pay per booking, but you follow, change and cancel each journey on its own.

The lifecycle

StageWhat you doJourney status
1. QuoteRequest quotes for the route and timeNo journey yet
2. BookCreate a booking from the chosen quoteNOT_PAID
3. PayPay by invoice, payment link, Stripe Connect or cardPENDING (or AWAITING_APPROVAL)
4. ConfirmedNothing: Transferz finds a transfer companyCONFIRMED
5. Driver assignedNothing: the transfer company assigns a driver and a vehiclePLANNED
6. On the wayShow the driver and the meeting point to the travellerDRIVER_UNDERWAY, DRIVER_ARRIVED
7. On boardNothingJOURNEY_IN_PROGRESS
8. CompletedNothingCOMPLETED

Until stage 6 you can change or cancel a journey. A cancelled journey ends in CANCELLED_FREE or CANCELLED_WITH_COSTS. COMPLETED and the cancelled statuses are final.

Statuses can be skipped, and a journey can go back from PLANNED to CONFIRMED when the driver is removed. Do not build logic that expects every status exactly once. All statuses are explained in Constants.

1. Quote

You send the pickup and drop-off locations, the local pickup time and the number of passengers and bags. Transferz returns one quote per available vehicle category, with price, capacity, add-ons and the free-cancellation deadline. For an airport pickup you can first suggest a pickup time from the traveller's flight. See Request quotes.

2. Book

You send the chosen quote ids with the booker's and the traveller's details and your reference. The response contains the booking and its journeys, all NOT_PAID. Store the booking id and the journey ids: there is no call to list or search your bookings. See Create a booking.

3. Pay

A booking is only processed once it is paid. Until then nobody drives. You pay on invoice, send the booker a payment link, or pass a Stripe payment intent. Which methods you can use is agreed with Transferz. See Pay for a booking.

4 to 8. The ride

After payment Transferz assigns the journey to a transfer company, which assigns a driver and a vehicle and reports progress on the day. You follow this with webhooks or by fetching the journey, and you pass the driver, vehicle and meeting point on to the traveller. Once the journey is CONFIRMED a voucher is available. See Follow a journey.

What to store

ValueWhere it comes fromUsed for
Quote idRequest quotesCreating the booking, before the quote expires
Booking idCreate bookingPaying, fetching and cancelling the booking
Booking codeCreate bookingShowing to the traveller and to customer service
Journey idjourneys[].idFollowing, changing and cancelling a journey; matching webhook events
Journey codejourneys[].codeShowing to the traveller

The ids are for API calls only. Show the traveller the codes.

What the traveller needs

Make sure these details reach the traveller:

  • the booking or journey code, and the pickup time and place;
  • the driver's name and phone number, and the vehicle's make, model and licence plate;
  • the meeting point, with its description and any map or photo;
  • the customer service phone number (customerServiceInfo.supportPhoneNumber).

Each journey also has a travellerAppUrl, a link to the Transferz traveller web app for that journey.

Next steps

Was this helpful?