How a booking works
The lifecycle of a partner booking, from quote to completed journey.
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
expirestime. - A booking is what you create from one or more quotes. It has a
partnerReference(your own order number) and acodethat 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
| Stage | What you do | Journey status |
|---|---|---|
| 1. Quote | Request quotes for the route and time | No journey yet |
| 2. Book | Create a booking from the chosen quote | NOT_PAID |
| 3. Pay | Pay by invoice, payment link, Stripe Connect or card | PENDING (or AWAITING_APPROVAL) |
| 4. Confirmed | Nothing: Transferz finds a transfer company | CONFIRMED |
| 5. Driver assigned | Nothing: the transfer company assigns a driver and a vehicle | PLANNED |
| 6. On the way | Show the driver and the meeting point to the traveller | DRIVER_UNDERWAY, DRIVER_ARRIVED |
| 7. On board | Nothing | JOURNEY_IN_PROGRESS |
| 8. Completed | Nothing | COMPLETED |
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
| Value | Where it comes from | Used for |
|---|---|---|
Quote id | Request quotes | Creating the booking, before the quote expires |
Booking id | Create booking | Paying, fetching and cancelling the booking |
Booking code | Create booking | Showing to the traveller and to customer service |
Journey id | journeys[].id | Following, changing and cancelling a journey; matching webhook events |
Journey code | journeys[].code | Showing 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
- Request quotes
- Set up webhooks early: you need them to follow journeys.
- Read Test data on staging to run a journey end to end.