# Accept or decline offers

> Receive offers for journeys and accept or decline them with a reason.

Section: Transfer companies · Last updated: 2026-11-15

You will receive an offer for a journey, decide on it, and accept it (with a meeting point when one
is required) or decline it with a reason. You need an API key and a webhook endpoint; offers are only
sent to companies that work with the offer flow (see
[How a journey reaches you](https://developers.test.transferz.com/guides/transfer-companies/how-a-journey-reaches-you)).

## Step 1: Receive the offer

When Transferz offers you a journey, your endpoint receives
[`offerCreatedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-created). Its `id` is the offer id. The event carries the
route, the pickup time, the vehicle category, the add-ons, the fare you would be paid and the meeting
points you can choose from. Traveller names and contact details are left out until you accept.

```json
{
  "offerCreatedEvent": {
    "id": 6120044,
    "preferred": true,
    "fleet": { "fleetId": 3301, "fleetName": "Amsterdam airport fleet", "transferCompanyId": 2290, "transferCompanyName": "Canal City Transfers" },
    "journey": {
      "id": 488213,
      "code": "TZ7K4Q-1",
      "pickUpTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" },
      "vehicleCategory": "SEDAN",
      "fareSummary": { "includingVat": 57.0, "excludingVat": 52.29, "vat": 4.71, "currency": "EUR" },
      "travellerInfo": { "passengerCount": 2, "luggageCount": 2, "flightNumber": "TZ1234", "language": "en" }
    },
    "meetingPoints": [
      { "id": 2561, "title": "Schiphol Plaza meeting point", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" }
    ],
    "meetingPointRequired": true,
    "expiry": "2026-11-20T12:47:00",
    "status": "NOTIFIED",
    "replacement": false,
    "created": "2026-11-20T10:47:00.215"
  }
}
```

The example is shortened. Acknowledge the event with `2xx` first and decide afterwards.

What the offer fields tell you:

| Field                                  | Meaning                                                                                                            |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`                                   | The offer id. Use it to accept or decline. It is not the journey id.                                               |
| `expiry`                               | Accept or decline before this time. After it, the offer is `EXPIRED`.                                              |
| `meetingPointRequired`                 | When `true`, you must choose one of `meetingPoints` when you accept.                                               |
| `preferred`                            | `true` when your company is a preferred supplier for this journey.                                                 |
| `replacement`                          | `true` when the journey is one you accepted before and has changed; see [Replacement offers](#replacement-offers). |
| `journey.travellerInfo.driverComments` | Requests from the traveller. Check you can meet them before you accept.                                            |

> **To be confirmed by Transferz:** The time zone of `expiry` and `created` is still to be confirmed by Transferz.

## Step 2: List open offers

If you missed an event, or want to check what is still open, list the offers you can still accept or
decline:

**Request:** [`GET /offers/available/all`](https://developers.test.transferz.com/reference/transfer-companies/list-available-offers)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
[
  {
    "id": 6120044,
    "preferred": true,
    "fleet": { "fleetId": 3301, "fleetName": "Amsterdam airport fleet", "transferCompanyId": 2290, "transferCompanyName": "Canal City Transfers" },
    "journey": {
      "id": 488213,
      "code": "TZ7K4Q-1",
      "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" },
      "vehicleCategory": "SEDAN",
      "fareSummary": { "includingVat": 57, "excludingVat": 52.29, "vat": 4.71, "currency": "EUR" }
    },
    "meetingPoints": [
      { "id": 2561, "title": "Schiphol Plaza meeting point", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" }
    ],
    "meetingPointRequired": true,
    "expiry": "2026-11-20T12:47:00",
    "status": "NOTIFIED",
    "replacement": false
  }
]
```

An empty list means nothing is open. To look at one offer, use
[Get an offer](https://developers.test.transferz.com/reference/transfer-companies/get-offer) with `GET /offers/6120044`.

## Step 3: Accept the offer

Send the offer id in the path. When `meetingPointRequired` is `true`, send the `id` and `type` of one
of the offer's `meetingPoints`:

**Request:** [`POST /offers/6120044/accept`](https://developers.test.transferz.com/reference/transfer-companies/accept-offer)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "meetingPointId": 2561,
  "type": "HUB"
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "meetingPointId": 2561,
    "type": "HUB"
  }),
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    String body = """
        {
          "meetingPointId": 2561,
          "type": "HUB"
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "meetingPointId": 2561,
      "type": "HUB"
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$body = <<<'JSON'
{
  "meetingPointId": 2561,
  "type": "HUB"
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "id": 488213,
  "code": "TZ7K4Q-1",
  "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" },
  "vehicleCategory": "SEDAN",
  "status": "CONFIRMED",
  "meetingPoint": {
    "id": 2561,
    "title": "Schiphol Plaza meeting point",
    "latitude": 52.3094,
    "longitude": 4.7622,
    "type": "HUB"
  },
  "driverCode": "482KQM731",
  "assignmentStatus": "ASSIGNED",
  "travellerInfo": {
    "firstName": "Alex",
    "lastName": "Traveller",
    "email": "alex.traveller@example.com",
    "phone": "+447700900123",
    "passengerCount": 2
  }
}
```

The response is the full journey, now including the traveller's details (shortened above).
`assignmentStatus` is `ASSIGNED`: the journey is yours. You also receive
[`journeyFleetAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-assigned) and
[`offerStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-status-changed) with `newStatus` `ACCEPTED`. From here on,
use the journey id `488213`, not the offer id.

When no meeting point is needed, send no body or an empty object. Do not send a meeting point for an
inbound journey (from an address to a hub): it is refused.

Accepting an offer you already accepted succeeds again and returns the journey, so a retry after a
timeout is safe.

## Step 4: Or decline it

Give a `reason`. With `OTHER`, a `description` is required; with the other reasons it is optional
(up to 4,000 characters).

**Request:** [`POST /offers/6120044/decline`](https://developers.test.transferz.com/reference/transfer-companies/decline-offer)

```bash title="cURL"
curl --request POST \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY' \
  --data '{
  "reason": "NO_VEHICLE_AVAILABILITY",
  "description": "All sedans are booked on 1 December in the afternoon."
}'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
  body: JSON.stringify({
    "reason": "NO_VEHICLE_AVAILABILITY",
    "description": "All sedans are booked on 1 December in the afternoon."
  }),
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    String body = """
        {
          "reason": "NO_VEHICLE_AVAILABILITY",
          "description": "All sedans are booked on 1 December in the afternoon."
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline"))
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("POST", HttpRequest.BodyPublishers.ofString(body))
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

var json = """
    {
      "reason": "NO_VEHICLE_AVAILABILITY",
      "description": "All sedans are booked on 1 December in the afternoon."
    }
    """;
request.Content = new StringContent(json, Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$body = <<<'JSON'
{
  "reason": "NO_VEHICLE_AVAILABILITY",
  "description": "All sedans are booked on 1 December in the afternoon."
}
JSON;

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (204):**

```http
HTTP/1.1 204 No Content
```

The reasons are listed in [Constants](https://developers.test.transferz.com/guides/essentials/constants#offer-decline-reasons). You receive
[`offerStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-status-changed) with `newStatus` `DECLINED`.

## Follow the offer's status

[`offerStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-status-changed) tells you when an offer changes:

| `newStatus` | What happened                                                             | What you do                                                  |
| ----------- | ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `NOTIFIED`  | The offer was sent to you.                                                | Decide before `expiry`.                                      |
| `ACCEPTED`  | You accepted it.                                                          | Nothing; the journey arrives by `journeyFleetAssignedEvent`. |
| `DECLINED`  | You declined it.                                                          | Remove it from your list.                                    |
| `EXPIRED`   | Nobody answered in time.                                                  | Remove it.                                                   |
| `MISSED`    | Another company accepted the journey first, or the journey was cancelled. | Remove it.                                                   |

```json
{
  "offerStatusChangedEvent": {
    "created": "2026-11-20T12:47:00.533",
    "offerId": 6120044,
    "journeyId": 488213,
    "transferCompanyId": 2290,
    "previousStatus": "NOTIFIED",
    "newStatus": "EXPIRED"
  }
}
```

## Replacement offers

When a journey you accepted changes, Transferz can offer it to you again as a replacement offer:
`replacement` is `true` and the journey id is the one you already have. Read the changed details
and accept or decline it as usual.

- **Accept** to keep the journey with its new details.
- **Decline** and the journey is taken away from you: you receive
  [`journeyFleetUnassignedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-unassigned).

> **To be confirmed by Transferz:** Which changes produce a replacement offer, and what happens to the journey when a replacement offer
> expires unanswered, is still to be confirmed by Transferz.

## Errors

| Status | Code                                                                                                                  | Cause                                                                                               | What to do                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `400`  | [OFFER_MISSED](https://developers.test.transferz.com/reference/errors/offer-missed)                                   | Another company accepted the journey first.                                                         | Remove the offer.                                                                                                  |
| `400`  | [OFFER_EXPIRED](https://developers.test.transferz.com/reference/errors/offer-expired)                                 | The offer passed its `expiry`.                                                                      | Remove the offer; answer offers sooner.                                                                            |
| `400`  | [OFFER_FINALIZED](https://developers.test.transferz.com/reference/errors/offer-finalized)                             | You already declined the offer, or you try to decline an offer that is accepted, expired or missed. | Check the offer with [Get an offer](https://developers.test.transferz.com/reference/transfer-companies/get-offer). |
| `400`  | [INVALID_MEETING_POINT](https://developers.test.transferz.com/reference/errors/invalid-meeting-point)                 | A meeting point is required and none was sent, or the id is not one of the offer's meeting points.  | Send the `id` and `type` of one of `meetingPoints`.                                                                |
| `400`  | [INBOUND_JOURNEY_MEETING_POINT](https://developers.test.transferz.com/reference/errors/inbound-journey-meeting-point) | A meeting point was sent for an inbound journey.                                                    | Accept without a body.                                                                                             |
| `400`  | [DECLINE_DESCRIPTION_MISSED](https://developers.test.transferz.com/reference/errors/decline-description-missed)       | The reason `OTHER` was sent without a `description`.                                                | Add a description.                                                                                                 |
| `403`  | `INSUFFICIENT_PERMISSIONS`                                                                                            | The offer is for another company.                                                                   | Check the offer id.                                                                                                |
| `404`  | —                                                                                                                     | No offer with this id (empty body).                                                                 | Check the offer id and the environment.                                                                            |

The error format is described in [Errors](https://developers.test.transferz.com/guides/essentials/errors).

## Related

### Endpoints

- [GET Get available offers](https://developers.test.transferz.com/reference/transfer-companies/list-available-offers) (`GET /offers/available/all`)
- [GET Get offer](https://developers.test.transferz.com/reference/transfer-companies/get-offer) (`GET /offers/{id}`)
- [POST Accept offer](https://developers.test.transferz.com/reference/transfer-companies/accept-offer) (`POST /offers/{id}/accept`)
- [POST Decline offer](https://developers.test.transferz.com/reference/transfer-companies/decline-offer) (`POST /offers/{id}/decline`)

### Walk-through steps

- [Offer flow](https://developers.test.transferz.com/walkthrough/transfer-company/offer-flow)
