# Car order update notifications

Learn how to receive and process car order update notifications to keep your car order data synchronised with Booking.com.

## Overview

Booking.com sends a **Car order updated** notification to your webhook endpoint whenever a car rental reservation is updated.

The notification contains key information about the update, including the current order status and the date and time of the latest modification.

Depending on your application's requirements, you can process the notification directly or retrieve the latest car order details from the Demand API.

This guide explains how to:

1. Request webhook registration and subscription.
2. Configure your webhook endpoint.
3. Validate incoming notification requests.
4. Process car order updates safely.
5. Retrieve additional car order information when required.
6. Handle duplicate, delayed and out-of-order notifications.


If you are new to Notifications, start with the [Notifications overview](/demand/docs/additional-services/notifications/about-notifications) to understand the notification and delivery model.

## Before you begin

Before integrating car order update notifications, make sure you:

* Have access to the Demand API.
* Have a publicly accessible HTTPS endpoint that can receive HTTP POST requests.
* Can process JSON request bodies.
* Have a dedicated Booking.com Account Manager who can request the registration and configuration of your webhook.


## How it works

When a car rental reservation is updated, Booking.com sends a notification to webhook endpoints subscribed to car order updates.

The notification provides information about the current order state, such as its status, the time of the latest modification and, when available, pickup, drop-off and insurance information.

Your application can use the notification data directly when it contains everything required. Otherwise, retrieve the latest order details from the Demand API.

![Notifications detailed flow](/assets/flow3.c337bdd1caa372cdddda53509a181597682e7099399d10540c61e1fcd249a24b.7fa386a7.png)

You do not need to retrieve the car order from the Demand API after every notification. Retrieve it only when your application requires information that is not included in the notification payload.

## Step 1 - Request webhook registration and subscription

Before you can receive notifications, Booking.com must register your webhook endpoint and configure it to receive car order updates.

Contact your dedicated Account Manager and provide the information required to configure your integration, including your webhook endpoint.

Booking.com will:

* Register your webhook endpoint.
* Configure the authentication credentials used for notification delivery.
* Subscribe your webhook endpoint to car order updates.


After the configuration is complete, Booking.com can start sending notifications to your webhook endpoint.

### Test notifications

When your webhook endpoint is ready, provide Booking.com with the URL to call and the password to use for authentication.

* Booking.com will send a test notification message to your endpoint so you can verify your integration before receiving live notifications.
* The test message contains randomly generated information, similar to the example in this guide.


When testing, verify that your application:

* Receives the request at the provided URL.
* Authenticates the request using the provided password.
* Accepts and validates the JSON payload according to the Notifications specifications.
* Returns a supported successful acknowledgement response.


Contact your dedicated Account Manager when your endpoint is ready for a test message.

## Step 2 - Configure your webhook

Configure your webhook endpoint to meet the following requirements:

| Requirement | Value |
|  --- | --- |
| Protocol | HTTPS |
| Method | POST |
| Content-Type | `application/json` |
| Successful acknowledgement | HTTP `200`, `201`, `202` and `204` |
| Accessibility | Publicly accessible from Booking.com infrastructure |


Your endpoint must acknowledge a successfully received notification with one of the supported success responses.

Where possible, accept the notification for processing and perform longer-running operations asynchronously.

The Notifications API supports the following successful acknowledgement responses:

- `200`
- `201`
- `202`
- `204`


Return an empty response body for all successful acknowledgements.

## Step 3 - Validate notification requests

When your webhook receives a notification, validate that the request is authenticated before accepting it for processing.

Your application should:

* Validate the configured authentication credentials.
* Reject unauthorised requests.
* Process only authenticated notifications.
* Return an appropriate HTTP `4xx` response when authentication fails.


After authentication succeeds, validate and parse the JSON request body before accepting the notification for processing.

### Notification payload

The following example shows a car order update notification:

```json
{
  "last_modified": "2026-08-20T14:32:00Z",
  "affiliate": 123456,
  "reservation": "934265380",
  "status": "confirmed",
  "insurance": [
    {
      "id": "335",
      "name": "RentalCover Full Protection",
      "status": "confirmed"
    }
  ],
  "pickup": {
    "datetime": "2026-09-18T09:00:00-03:00",
    "location": "Senador Nilo Coelho International Airport",
    "longitude": "-40.56590800",
    "latitude": "-9.36658700",
    "depot_type": "On Airport - Desk in Terminal",
    "depot_id": "54241",
    "contact": {
      "address": "Avenida Deputado Ulisses Guimarães, Petrolina, Brazil, 56313-900",
      "telephone": "+1234567890"
    },
    "instructions": "Proceed to the rental desk inside Terminal 2."
  },
  "dropoff": {
    "datetime": "2026-09-21T10:00:00-03:00",
    "location": "Senador Nilo Coelho International Airport",
    "longitude": "-40.56590800",
    "latitude": "-9.36658700",
    "depot_type": "On Airport - Desk in Terminal",
    "depot_id": "54241",
    "contact": {
      "address": "Avenida Deputado Ulisses Guimarães, Petrolina, Brazil, 56313-900",
      "telephone": "+1234567890"
    },
    "instructions": "Return the vehicle to the designated rental car area."
  }
}
```

### Payload summary

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `last_modified` | string (date-time) | ✓ | Date and time when the car order was last updated, in ISO 8601 UTC format. Use this value to determine the most recent notification when multiple updates are received for the same order. |
| `affiliate` | integer | ✓ | Identifier of the affiliate associated with the car order. |
| `reservation` | string | ✓ | Reservation number associated with the car rental order. |
| `status` | string | ✓ | Current order status. |
| `insurance` | array of objects | Optional | Insurance information associated with the car order, when applicable. This includes: `id`, `name` and `status`. |
| `pickup` | object | Optional | Pickup details associated with the car order. |
| `dropoff` | object | Optional | Drop-off details associated with the car order. |


The notification represents the car order state associated with that update. Because notifications can be delayed or delivered out of order, the payload might not represent the latest state by the time your application receives it.

For the complete payload definition, including nested objects, supported status values and field descriptions, see the [Car order update notification API reference](/demand/docs/additional-services/notifications/notifications/order-update/carsorderupdated).

## Step 4 - Process car order update notifications

Do not assume that notifications arrive in the same order in which the underlying updates occurred.

Process each notification as follows:

1. Validate the authentication credentials.
2. Validate and parse the JSON payload.
3. Identify the car order using `reservation`.
4. Compare `last_modified` with the most recent modification time you have already processed for that car order.
5. If you have already processed a notification with a later `last_modified` value, do not overwrite your local state with the older notification.
6. Otherwise, accept the notification for processing and update your local data as required.
7. Retrieve the latest order details from the Demand API if your application requires information that is not included in the notification.
8. Return a supported successful HTTP response after the notification has been successfully accepted.


![Flow to process notifications](/assets/flow-process-notification.70f5ca95f0114a5642668fafe58fc87dc89914bba9a56a9d614f68a84b576ef2.7fa386a7.png)

Notifications can arrive out of order or more than once. Do not rely on delivery order when determining the current state of a car order.

### Compare `last_modified` values

The `last_modified` property is an ISO 8601 UTC date-time value, for example:

```json
2026-08-20T04:00:00Z
```

Store the latest successfully processed `last_modified` value for each car order.

When another notification for the same affiliate and reservation arrives:

* Process it if `last_modified` represents a later update than the one you have already processed.
* Do not overwrite newer local state if `last_modified` represents an older update.
* Handle repeated notifications idempotently.


This prevents a delayed notification from replacing more recent order information in your system.

## Step 5 - Retrieve the latest car order

Notifications tell your application that a car order has changed. They complement rather than replace the Demand API.

### When should I retrieve the car order details?

You do **not** need to retrieve the car order details after every notification.

* If the notification contains all the information your application needs — for example, the current order status — you can use it directly.
* Retrieve the latest order details (using orders/details/cars/live in Beta) when your application requires information that is not included in the notification payload.


Retrieving the order details from the Demand API gives your application the latest available information at the time of the request rather than relying solely on the state represented by a potentially delayed notification.

## Order status values

The `status` property describes the current status of the car order.

| Value | Description |
|  --- | --- |
| `cancelled` | The order has been cancelled and is no longer active. |
| `confirmed` | The order is confirmed and active. |
| `not_confirmed` | The order request exists but has not yet been confirmed. |
| `quote` | A quotation exists but no order has been placed. |
| `completed` | The rental has finished. |
| `processing` | The order is currently being processed. |
| `unknown` | The order status cannot currently be determined. |


If `insurance` is present, its `status` can be:

| Value | Description |
|  --- | --- |
| `cancelled` | The insurance has been cancelled. |
| `confirmed` | The insurance is active and confirmed. |
| `processing` | The insurance is currently being processed. |
| `unknown` | The insurance status cannot currently be determined. |


## Pickup and drop-off information

The optional `pickup` and `dropoff` objects provide location information associated with the car order.

They can contain:

| Field | Type | Description |
|  --- | --- | --- |
| `datetime` | string (date-time) | Date and time in ISO 8601 format. |
| `location` | string | Name of the location. |
| `longitude` | string | Longitude of the location. |
| `latitude` | string | Latitude of the location. |
| `depot_type` | string | Type of rental location. |
| `depot_id` | string | Identifier of the rental depot. |
| `contact` | object | Contact information for the location. |
| `instructions` | string | Pickup or drop-off instructions. |


The optional `contact` object can contain `address` and `telephone`.

## Example car order lifecycle

A car order can generate multiple notifications as it changes during its lifecycle.

For example:

```text
Car order confirmed
      │
      ▼
Pickup information updated
      │
      ▼
Insurance status updated
      │
      ▼
Car order completed
```

This lifecycle is an example only. The notifications generated for a car order depend on the updates that occur.

Each notification represents the car order state associated with an update when the notification was generated.

The order in which your webhook receives those notifications is not guaranteed.

## Ordering and duplicate delivery

Your application should be designed to handle notifications that are delayed, duplicated or delivered out of order.

Your application should:

* Not rely on the order in which notifications are received.
* Use `last_modified` to prevent an older notification from overwriting newer state.
* Process notifications idempotently.
* Be prepared to receive the same notification more than once.
* Retrieve the latest car order from the Demand API when your application requires the current resource state.


### Design for idempotent processing

Do not assume exactly-once delivery.

Receiving the same notification more than once should not create an incorrect state or repeat an action that should occur only once.

For example, before applying an update, compare its `last_modified` value with the latest value already processed for the reservation.

## Acknowledgements and error handling

Return a successful response only after your application has accepted the notification for processing.

The Notifications API supports the following successful acknowledgement responses:

- `200`
- `201`
- `202`
- `204`


Return an empty response body for all successful acknowledgements.

For requests that cannot be accepted, return an appropriate error response for the failure. For example, reject a request with an appropriate HTTP `4xx` response when authentication fails.

## Test your integration

Currently, car order update notifications can only be tested in a production environment. A dedicated test environment is not available.

Before enabling notification processing in your production systems, make sure your webhook can:

* Authenticate incoming requests.
* Parse valid notification payloads.
* Reject unauthorised requests.
* Accept and acknowledge valid notifications correctly.
* Handle duplicate notifications safely.
* Handle notifications that arrive out of order.
* Compare `last_modified` values correctly.
* Retrieve the latest car order when additional information is required.
* Handle optional `insurance`, `pickup` and `dropoff` objects.


## Best practices

To build a reliable integration:

✅ **Validate every request** - Authenticate incoming notifications before accepting them for processing.

✅ **Acknowledge notifications promptly** - Return a supported successful response after the notification has been accepted for processing.

✅ **Process asynchronously where possible** - Avoid performing long-running operations before acknowledging the notification.

✅ **Do not rely on delivery order** - Notifications can be delayed or arrive out of order.

✅ **Protect newer state** - Use `last_modified` to prevent an older notification from overwriting a more recent local state.

✅ **Make processing idempotent** - Receiving the same notification more than once should not cause unintended side effects.

✅ **Treat optional data as optional** - Do not assume `insurance`, `pickup` or `dropoff` is present.

✅ **Use documented enum values** - Support all documented `status` values, including `unknown`.

✅ **Retrieve data only when required** - Use the Demand API when the notification does not contain all the information your application needs.

✅ **Log processing outcomes** - Record enough information, including `reservation` and `last_modified`, to investigate failed or unexpected processing.

## What's next

Continue with the following documentation:

* [Notifications overview](/demand/docs/additional-services/notifications/about-notifications) — Learn about the notification service and delivery model.
* [Car order update notification API reference](/demand/docs/additional-services/notifications/notifications/order-update) — Review the complete notification payload schema and field definitions.
* [Car order latest details](/demand/docs/open-api/3.2-beta/demand-api/orders/details/cars/live) — Learn how to retrieve the latest car order details when additional information is required.