Skip to content

Accept or decline offers

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

Updated · 4 min read

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).

Step 1: Receive the offer

When Transferz offers you a journey, your endpoint receives offerCreatedEvent. 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:

FieldMeaning
idThe offer id. Use it to accept or decline. It is not the journey id.
expiryAccept or decline before this time. After it, the offer is EXPIRED.
meetingPointRequiredWhen true, you must choose one of meetingPoints when you accept.
preferredtrue when your company is a preferred supplier for this journey.
replacementtrue when the journey is one you accepted before and has changed; see Replacement offers.
journey.travellerInfo.driverCommentsRequests from the traveller. Check you can meet them before you accept.

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:

GET/offers/available/allReference
Sign in to fill in your staging key. Sign in
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'
Response 200
[  {    "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 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:

POST/offers/6120044/acceptReference
Sign in to fill in your staging key. Sign in
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"}'
Response 200
{  "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 and offerStatusChangedEvent 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).

POST/offers/6120044/declineReference
Sign in to fill in your staging key. Sign in
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."}'
Response 204
HTTP/1.1 204 No Content

The reasons are listed in Constants. You receive offerStatusChangedEvent with newStatus DECLINED.

Follow the offer's status

offerStatusChangedEvent tells you when an offer changes:

newStatusWhat happenedWhat you do
NOTIFIEDThe offer was sent to you.Decide before expiry.
ACCEPTEDYou accepted it.Nothing; the journey arrives by journeyFleetAssignedEvent.
DECLINEDYou declined it.Remove it from your list.
EXPIREDNobody answered in time.Remove it.
MISSEDAnother 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.

Errors

StatusCodeCauseWhat to do
400OFFER_MISSEDAnother company accepted the journey first.Remove the offer.
400OFFER_EXPIREDThe offer passed its expiry.Remove the offer; answer offers sooner.
400OFFER_FINALIZEDYou already declined the offer, or you try to decline an offer that is accepted, expired or missed.Check the offer with Get an offer.
400INVALID_MEETING_POINTA 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.
400INBOUND_JOURNEY_MEETING_POINTA meeting point was sent for an inbound journey.Accept without a body.
400DECLINE_DESCRIPTION_MISSEDThe reason OTHER was sent without a description.Add a description.
403INSUFFICIENT_PERMISSIONSThe 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.

Was this helpful?

Back to your build path: How a journey reaches you →