# How a booking works

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

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

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.test.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.test.transferz.com/reference/partners/request-quotes) for the route and time  | No journey yet                      |
| 2. Book            | [Create a booking](https://developers.test.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.test.transferz.com/guides/partners/change-a-journey) or
[cancel](https://developers.test.transferz.com/guides/partners/cancel-a-journey-or-booking) 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.test.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.test.transferz.com/guides/partners/suggest-a-pickup-time) from the traveller's flight. See
[Request quotes](https://developers.test.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.test.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.test.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.test.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.test.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.

> **To be confirmed by Transferz:** Which emails and text messages Transferz sends to the booker and the traveller of a partner booking
> is still to be confirmed by Transferz.

## Next steps

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

## Related

### Endpoints

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