# How a booking works

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

Section: Partners · Last updated: 2026-11-18

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](https://developers.transferz.com/guides/get-started/glossary#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](https://developers.transferz.com/reference/partners/request-quotes) for the route and time  | No journey yet                      |
| 2. Book            | [Create a booking](https://developers.transferz.com/reference/partners/create-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](https://developers.transferz.com/guides/partners/change-a-journey) or
[cancel](https://developers.transferz.com/guides/partners/cancellations) 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](https://developers.transferz.com/guides/essentials/constants#journey-status).

### 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](https://developers.transferz.com/guides/partners/suggest-a-pickup-time) from the traveller's flight. See
[Request quotes](https://developers.transferz.com/guides/partners/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](https://developers.transferz.com/guides/partners/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](https://developers.transferz.com/guides/partners/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](https://developers.transferz.com/guides/essentials/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](https://developers.transferz.com/guides/partners/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.

## Messages Transferz sends

Transferz sends these messages to the booker and the traveller:

| Message                                         | Channel      | To        | Sent when                                                                       |
| ----------------------------------------------- | ------------ | --------- | ------------------------------------------------------------------------------- |
| Booking confirmation                            | Email        | Booker    | The booking is paid                                                             |
| Booking created, with a link to follow the trip | Text message | Traveller | The booking is paid                                                             |
| Journey confirmation with voucher               | Email        | Traveller | A transfer company is assigned                                                  |
| Journey reminder                                | Email        | Traveller | About two days before pickup                                                    |
| Pre-pickup message                              | Text message | Traveller | About a day before pickup                                                       |
| Driver details                                  | Text message | Traveller | The driver sets off                                                             |
| Change confirmation, with a new voucher         | Email        | Traveller | A journey change is confirmed                                                   |
| Change notice                                   | Email        | Booker    | A major change is confirmed                                                     |
| Payment link for a change                       | Email        | Traveller | A change needs extra payment                                                    |
| Cancellation confirmation                       | Email        | Traveller | The journey is cancelled                                                        |
| Flight number or phone number alerts            | Email        | Traveller | The flight number is missing or wrong, or a text message could not be delivered |
| Survey                                          | Email        | Traveller | After the journey                                                               |

Transferz can turn specific messages on or off for your company. Ask Transferz for this; you cannot
change it yourself.

## Next steps

- [Request quotes](https://developers.transferz.com/guides/partners/request-quotes)
- Set up [webhooks](https://developers.transferz.com/guides/essentials/webhooks) early: you need them to follow journeys.
- Read [Test data](https://developers.transferz.com/guides/essentials/test-data) to run a journey end to end.

## Related

### Endpoints

- [POST Request quotes](https://developers.transferz.com/reference/partners/request-quotes) (`POST /quotes`)
- [POST Create booking](https://developers.transferz.com/reference/partners/create-booking) (`POST /bookings`)
- [POST Pay by invoice](https://developers.transferz.com/reference/partners/pay-booking-by-invoice) (`POST /bookings/{id}/pay-by-invoice`)
- [GET Get journey by id](https://developers.transferz.com/reference/partners/get-journey) (`GET /journeys/{journeyId}`)
- [POST Cancel journey](https://developers.transferz.com/reference/partners/cancel-journey) (`POST /journeys/{journeyId}/cancel`)
